Credit memos

A credit memo is credit you grant a payer — for a return, an overpayment, a goodwill gesture. The payer applies it themselves against what they owe, in the payer portal.

Note

A credit memo is not a refund. A refund returns money to the card or bank account it came from. A credit memo leaves the money with you and reduces what the payer owes next time. If the payer wants their money back, refund them.

Refund or credit memo?

	Refund	Credit memo
Money moves	Back to the payer's card or bank	Not at all
Needs an original payment	Yes — a COMPLETED one	No
Payer sees	A credit on their statement	Available credit in the payer portal
Redeemed	Automatically	By the payer, against a future payment

You cannot convert one into the other. Decide before you issue it.

Headers

The standard three. No idempotency key.

{
  "x-aptean-apim": "<your api key>",
  "x-aptean-tenant": "<your tenant id>",
  "x-aptean-tenant-secret": "<your tenant secret>"
}

The mutation

mutation UpsertCreditMemo($input: UpsertCreditMemoInput!) {
  upsertCreditMemo(input: $input) {
    code
    message
    error
    creditMemo {
      id
      amount
      status
      referenceNumber
    }
  }
}

Issue a credit memo

{
  "input": {
    "referenceNumber": "CM-2041",
    "amount": 5000,
    "currency": "USD",
    "reason": "Returned two units from order 10042",
    "customerAllocation": [
      {
        "allocationType": "CUSTOMER",
        "customerNumber": "CUST-4471"
      }
    ]
  }
}

Field	Type	Notes
referenceNumber	String	Your own reference. Use your credit note number.
amount	Int	Minor units. 5000 is $50.00.
currency	CurrencyType	USD or CAD.
reason	String	Why the credit was issued. Visible to the payer — write it accordingly.
customerAllocation	[Object]	Who the credit belongs to. See below.
id	ID	Supply to update an existing memo instead of creating one.
status	CreditMemoStatus	OPEN, REDEEMED or CLOSED.
statusReason	String	Why the status changed.
customData	JSON	Arbitrary key–value pairs.

Allocating it to someone

customerAllocation is how the credit finds its owner. Each entry needs an allocationType and one identifier:

allocationType	Identify with
CUSTOMER	customerId or customerNumber
PERSON	email

"customerAllocation": [
  { "allocationType": "PERSON", "email": "payer@example.com" }
]

Warning

Get the allocation right first time. A credit memo allocated to the wrong customer or the wrong email is visible to the wrong payer. If you are allocating by email, it must be the address the payer actually uses in the payer portal — the payer portal identifies people by email, so a typo creates credit nobody can reach.

Statuses

Status	Meaning
OPEN	Available. The payer can apply it.
REDEEMED	Fully used against one or more payments.
CLOSED	Withdrawn or expired. No longer available.

To withdraw credit you issued by mistake, update it with id and status: "CLOSED", giving a statusReason.

It is an upsert

Pass id to update; omit it to create. The same trap as payment requests applies — if you meant to amend a memo and forget the id, you have issued a second one, and the payer now has twice the credit.

Redeeming it

The payer normally redeems credit themselves in the payer portal. To apply credit from your own integration, pass creditAmount on createPayment alongside amount.

Finding credit memos

query {
  creditMemos(
    orderBy: { field: TIMESTAMP, direction: DESC }
    first: 20
    status: [OPEN]
  ) {
    nodes {
      id
      referenceNumber
      amount
      status
      reason
    }
  }
}

creditMemos also filters on id, startDate / endDate with dateRangeType, and status, and pages with first/after and last/before.