Credit memos

Endpoint /api2/creditmemo to create a refund credit memo from an invoice or order. Supports online refund (triggers the payment method) or offline (records the refund only), with shipping adjustment and positive/negative differences.

REST JSON Bearer Token New in 2026

Overview

Credit memo is the final step of the order's financial cycle. This page covers refund creation; listing and detailed lookup of credit memos are not yet available in this version (see Roadmap). For shared family rules (pagination, dates, HTTP statuses, items handling), see the main Orders page.

Refund typesonline and offline (default).

Accepted sourcesinvoice_id, invoice_increment_id, order_id, order_increment_id.

Aliases/api2/creditmemo and /api2/creditmemo/create.

Adjustmentsshipping_amount, adjustment_positive, adjustment_negative.

POST/api2/creditmemo

Create a credit memo for refund. For safety, default refund_type is offline — only use online when you intend to trigger the payment method.

RefundCredit memo

invoice_id / invoice_increment_id / order_id / order_increment_id

Identify the source with exactly one of these fields.

refund_type Optional

Accepts online or offline. Default offline.

items Optional

Items to refund. If omitted, refunds available quantities.

shipping_amount Optional

Shipping amount to refund (numeric, in store currency).

adjustment_positive Optional

Extra credit to the customer (numeric).

adjustment_negative Optional

Debit to subtract from the refund (numeric, e.g. cancellation fee).

send_email Optional

When true, sends the credit memo email after saving.

comment Optional

Comment recorded on the credit memo.

Refund by invoice

POST /api2/creditmemo
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_id": 456,
  "refund_type": "offline",
  "send_email": true,
  "comment": "Refund created by integration."
}

Partial refund by order

POST /api2/creditmemo/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "refund_type": "offline",
  "shipping_amount": 0,
  "adjustment_positive": 0,
  "adjustment_negative": 0,
  "items": [
    {"order_item_id": 10, "qty": 1}
  ]
}

Online refund with items and adjustment

POST /api2/creditmemo
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_increment_id": "100000045",
  "refund_type": "online",
  "shipping_amount": 19.90,
  "adjustment_negative": 5.00,
  "items": [
    {"sku": "PRODUCT-001", "qty": 1}
  ],
  "send_email": true,
  "comment": "Partial refund after return."
}

Warning

Credit memos cannot be reverted after creation. With refund_type=online, success depends on the payment method supporting online refunds; otherwise the payment integration will return a native error.

Also accepts the alias POST /api2/creditmemo/create.

Supported usage patterns

Tested and certified combinations for the Creditmemo resource.

Full offline refund by invoicePOST /api2/creditmemo + invoice_id + refund_type=offline

Full online refund by invoicePOST /api2/creditmemo + invoice_id + refund_type=online

Partial refund by orderPOST /api2/creditmemo/create + order_increment_id + items[]

With shipping refundPOST /api2/creditmemo + shipping_amount

With cancellation feePOST /api2/creditmemo + adjustment_negative

With promo creditPOST /api2/creditmemo + adjustment_positive

Integration recommendations

Validate the refundable balance on the invoice before calling — issue GET /api2/invoice?id=... and compare grand_total against already refunded.
For partial refunds, prefer order_item_id over sku — it is more deterministic.
Keep refund_type=offline as the integration default; promote to online only when the commercial policy requires.

Avoid

Triggering refund_type=online without confirming the payment method supports it — the error will surface from the gateway.
Creating credit memos expecting to revert them — the operation is irreversible.
Mixing more than one source identifier (e.g. invoice_id + order_id) in the same payload.

Financial policy

For accounting integrations, record in comment the source ledger reference (return invoice number, ticket ID, etc.). It eases reconciliation later, since the credit memo shows up in the order history and financial reports.

Common errors

Status	Sample body	When it happens
`400`	`{"error": "Invalid item"}`	An `items` entry without `order_item_id`/`sku` or with non-positive `qty`.
`400`	`{"error": "Cannot create credit memo"}`	The invoice or order no longer accepts further refunds (already refunded, canceled etc.).
`400`	`{"error": "Online refund not supported"}`	`refund_type=online` on a payment method that does not support online refunds.
`401`	`{"error": "Unauthorized"}`	Missing `Authorization` or expired token.
`404`	`{"error": "Invoice not found"}`	Unknown `invoice_id` or `invoice_increment_id`.
`404`	`{"error": "Order not found"}`	Unknown `order_id` or `order_increment_id`.
`409`	`{"error": "Conflict on save"}`	Duplicate or deadlock on concurrent writes.
`500`	`{"error": "Payment gateway error"}`	Failure relayed by the payment method during online refund.

Out of current scope

Items not yet covered by this version:

Listing (GET /api2/creditmemo) and detailed lookup (GET /api2/creditmemo?id=...) of credit memos — planned in the roadmap.

Credit memos

Overview

Refund by invoice

Partial refund by order

Online refund with items and adjustment

Warning

Supported usage patterns

Integration recommendations

Recommended

Avoid

Financial policy

Common errors

Out of current scope