Last updated

These docs are intended for a developer audience.

Credit memos

A credit memo is a record which describes a certain amount that is owed to a customer for a particular invoice or invoice item.

A credit memo is similar to an invoice. It includes items, taxes, and shipping, but its total is subtracted from the invoice amount. A common use case for a credit memo is to provide a customer with store credit, rather than a refund, if the customer pays more than they owe or returns a product.

For your records, when paid items are returned, specify the particular invoice ID or invoice item IDs which are credited. This is informative only, and has no effect on the application of the credit. For more information, see Credit memo API operations.


issuedCredit memo is created but is not allocated. The full amount of the credit memo is unused.
partially-appliedCredit memo is partially allocated. Some of the credit memo amount is unused.
appliedCredit memo amount is fully allocated.
voidedCredit memo unused amount is set to zero. The credit memo and its allocations cannot be changed.


A credit memo has an amount (unusedAmount), which is used to allocate to transactions, and used to partially or fully pay invoices. The credit memo amount can be allocated in several smaller portions or in one full allocation of the full credit memo amount.

Example: PATCH /credit-memos/{creditMemoId}/.

  "allocations": {
    "invoices": [
        "invoiceId": "invoice-external-id",
        "amount": 404

For partially paid invoices, the allocation can also be reduced or removed. This reduces the received amount of the invoice. For more information on invoice allocations, see Upsert a credit memo, Partially update a credit memo, and Retrieve a credit memo.

Allocating a credit memo to a transaction reduces the credit memo unusedAmount, but it does not affect the transaction itself. This is useful when allocating a refund transaction, to reduce the credit memo unusedAmount by the refund amount. For more information on transaction allocations, see Upsert a credit memo, Partially update a credit memo, and Retrieve a credit memo.

A credit memo can be allocated to transactions of the type refund and payout, and transactions of the type capture and sale that have the status disputed or voided.

Order billing

When an upcoming order invoice is issued, depending on the order settings, it may be scheduled for an auto payment. When auto payment occurs, the invoice retrieves allocations from all credit memos with an unused amount until it is paid or there are no more issued, or partially applied, credit memos.