Zoey REST API reference · Interactive version: apidocs.zoey.com

Orders

Orders: Credit Memos

REST endpoints for Zoey credit memos (the zoey_sales/creditmemo model introduced with the new CM / store credit work).

A credit memo is a credit issued to a customer and/or company account. It is either sourced from invoice (bill) lines or created standalone, and can then be:

These endpoints aren't tied to an order: a memo belongs to an account and can draw from invoices on several orders. They require admin privileges.

Identifiers

Enumerations

Field Values
state 1 Unapplied · 2 Partially applied · 3 Applied · 4 Canceled
creditmemo_type 1 Items (line-based) · 2 Amount (flat amount, no items)
linked_entity_type 1 Standalone · 2 Invoice (bill)
credit_handling credit (default) · refund_offline · refund_online

Credit memo payload

Every endpoint that returns a credit memo returns the same full payload: header attributes, items[], comments[] and source_entity_links[]. The list endpoint leaves comments out unless include_comments is set.

Errors

Errors use the standard format described in Overview → Errors. For these endpoints:

HTTP When
400 Validation / business-rule failure (bad payload, credit memo can't be canceled, invalid filter, …)
404 Credit memo (or comment) does not exist
500 Internal error. The message is kept generic and details are logged server-side

Customer emails

Defaults differ by action, so set notify_customer explicitly when it matters:

Action notify_customer default
Create, add comment, cancel false
Apply credit to invoices true (it's a payment event)

Deprecated routes

The older /sales2/orders/creditmemo(s) routes under Orders → Credit Memos still work and now create the new credit memo models, but new integrations should use the routes in this folder.

Comments

Add, edit and delete credit memo comments. Each change triggers a QuickBooks re-sync of the memo.

Add

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/comment

Adds a comment to a credit memo and returns the memo's full payload. The change also triggers a QuickBooks re-sync of the memo.

Body

Field Type Default Description
increment_id string — Required. Credit memo increment id
comment string "" Comment text
notify_customer bool false Send the credit memo update email
include_comment bool false Put the comment in the email body
is_visible_on_front bool false Show the comment to the customer in their account

Example request body:

{
    "increment_id": "100000187",
    "comment": "Customer confirmed receipt of the returned units.",
    "notify_customer": true,
    "include_comment": true,
    "is_visible_on_front": true
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "1",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "comments": [
            {
                "comment_id": "96",
                "parent_id": "187",
                "comment": "Credited 2 damaged units from invoice #100000042.",
                "customer_id": null,
                "user_id": "3",
                "is_customer_notified": "0",
                "is_visible_on_front": "1",
                "created_at": "2
... (truncated)

Example response (400 Missing increment_id), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "increment_id is required."
            }
        ]
    }
}

Update

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/comment/update

Edits an existing comment in place and returns the memo's full payload. Only the fields you send are changed, so you can edit the text without touching visibility, or the other way round. No email is sent.

Body

Field Type Description
increment_id string Required. Credit memo increment id
comment_id int Required. Comment to edit, from comments[].comment_id
comment string New text
notify_customer bool Sets the comment's is_customer_notified flag only. Does not send an email
is_visible_on_front bool Show or hide the comment for the customer

Returns 404 Comment does not exist. when the comment isn't on that memo.

Example request body:

{
    "increment_id": "100000187",
    "comment_id": 96,
    "comment": "Corrected: 2 damaged units from invoice #100000042.",
    "is_visible_on_front": false
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "1",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "comments": [
            {
                "comment_id": "96",
                "parent_id": "187",
                "comment": "Credited 2 damaged units from invoice #100000042.",
                "customer_id": null,
                "user_id": "3",
                "is_customer_notified": "0",
                "is_visible_on_front": "1",
                "created_at": "2
... (truncated)

Example response (404 Comment not found), HTTP 404:

{
    "messages": {
        "error": [
            {
                "code": 404,
                "message": "Comment does not exist."
            }
        ]
    }
}

Delete

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/comment/delete

Deletes a comment and returns the memo's full payload.

Body

Field Type Description
increment_id string Required. Credit memo increment id
comment_id int Required. Comment to delete

Example request body:

{
    "increment_id": "100000187",
    "comment_id": 96
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "1",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "source_entity_links": [
            {
                "link_id": "201",
                "creditmemo_id": "187",
                "linked_entity_type": "2",
                "linked_entity_id": "5530",
                "items": [
                    {
                        "item_link_id": "305",
                        "parent_id": "201",
                        "credi
... (truncated)

Apply Credit

Apply available credit memo credit to open invoices.

Apply to an invoice

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/apply

Applies available credit to one or more open invoices. The credit is drawn from the invoice owner's available credit memos (customer and/or company), so you don't name a specific memo.

All invoices in one request share one credit transaction and one email decision.

Body, single invoice

Field Type Default Description
bill_id int — Required. Invoice (bill) id
amount number 0 Amount to apply. 0 applies as much as possible, up to the invoice's remaining balance
notify_customer bool true Send the payment email

Body, several invoices

Field Type Default Description
bills array — Required. [{ "bill_id": 5530, "amount": 25.00 }, …]. A missing or 0 amount applies that invoice's full remaining balance. Each invoice may appear only once
notify_customer bool true Send the payment email

When bills is present, bill_id and amount are ignored.

Response

Field Description
credit_transaction { id, increment_id, base_total, total } for the credit transaction created
summary.total_credit_applied Total applied, in base currency
summary.bills_count Invoices processed
summary.bills_paid_count Invoices that actually received credit. A batch can succeed while some invoice draws nothing
summary.creditmemos_used_count Credit memos drawn from
bills[] { bill_id, increment_id, amount_applied, fully_paid }
creditmemos[] { creditmemo_id, increment_id, amount_used, remaining_credit }
notify_customer Echo of the email decision

The credit transaction records the actor in an internal comment ("Credit applied manually by …").

Example request body:

{
    "bill_id": 5530,
    "amount": 0,
    "notify_customer": true
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "credit_transaction": {
        "id": "812",
        "increment_id": "100000812",
        "base_total": "52.9200",
        "total": "52.9200"
    },
    "summary": {
        "total_credit_applied": "52.9200",
        "bills_count": 1,
        "bills_paid_count": 1,
        "creditmemos_used_count": 1
    },
    "bills": [
        {
            "bill_id": "5530",
            "increment_id": "100000042",
            "amount_applied": 52.92,
            "fully_paid": true
        }
    ],
    "creditmemos": [
        {
            "creditmemo_id": "187",
            "increment_id": "100000187",
            "amount_used": 52.92,
            "remaining_credit": 0
        }
    ],
    "notify_customer": true
}

Example response (400 Missing bill_id), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "bill_id is required."
            }
        ]
    }
}

Example response (400 Non-numeric amount), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "amount must be a number."
            }
        ]
    }
}

Apply to several invoices

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/apply

Batch form of Apply to an invoice: one credit transaction and one email decision cover every invoice in bills. A missing or 0 amount applies that invoice's full remaining balance.

See Apply to an invoice for the full field and response reference.

Example request body:

{
    "bills": [
        {
            "bill_id": 5530,
            "amount": 25
        },
        {
            "bill_id": 5531
        }
    ],
    "notify_customer": false
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "credit_transaction": {
        "id": "813",
        "increment_id": "100000813",
        "base_total": "125.0000",
        "total": "125.0000"
    },
    "summary": {
        "total_credit_applied": "125.0000",
        "bills_count": 2,
        "bills_paid_count": 2,
        "creditmemos_used_count": 2
    },
    "bills": [
        {
            "bill_id": "5530",
            "increment_id": "100000042",
            "amount_applied": 25,
            "fully_paid": false
        },
        {
            "bill_id": "5531",
            "increment_id": "100000043",
            "amount_applied": 100,
            "fully_paid": true
        }
    ],
    "creditmemos": [
        {
            "creditmemo_id": "187",
            "increment_id": "100000187",
            "amount_used": 52.92,
            "remaining_credit": 0
        },
        {
            "creditmemo_id": "190",
            "increment_id": "100000190",
            "amount_used": 72.08,
            "remaining_credit": 77.92
        }
    ],
    "notify_customer": false
}

Example response (400 Duplicate invoice), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "bills lists invoice 5530 more than once."
            }
        ]
    }
}

Get

GET https://container-url.zoeysite.com/api/rest/sales2/creditmemo?id=100000187

Returns one credit memo by increment id, including its credit amounts (applied_credit_balance, reserved_credit_balance, available_credit_balance), items[], comments[] and source_entity_links[].

Query parameters

Param Required Description
id yes The credit memo increment id (e.g. 100000187)

Returns 404 when no credit memo has that increment id.

Query parameters:

NameExampleNotes
id100000187Credit memo increment id

Example response (200 OK), HTTP 200:

{
    "creditmemo_id": "187",
    "store_id": "1",
    "increment_id": "100000187",
    "company_id": "37",
    "customer_id": "15",
    "state": "2",
    "creditmemo_type": "1",
    "memo_amount": "0.0000",
    "base_memo_amount": "0.0000",
    "subtotal": "49.0000",
    "base_subtotal": "49.0000",
    "discount_amount": "0.0000",
    "base_discount_amount": "0.0000",
    "tax_amount": "3.9200",
    "base_tax_amount": "3.9200",
    "shipping_amount": "0.0000",
    "base_shipping_amount": "0.0000",
    "fee_amount": "0.0000",
    "payment_surcharge_amount": "0.0000",
    "adjustment_amount": "0.0000",
    "grand_total": "52.9200",
    "base_grand_total": "52.9200",
    "global_currency_code": "USD",
    "base_currency_code": "USD",
    "store_currency_code": "USD",
    "base_to_global_rate": "1.0000",
    "base_to_store_rate": "1.0000",
    "created_at": "2026-09-30 14:02:11",
    "updated_at": "2026-09-30 14:02:11",
    "applied_credit_balance": "20.0000",
    "reserved_credit_balance": "5.0000",
    "available_credit_balance": "32.9200",
    "items": [
        {
            "item_id": "412",
            "parent_id": "187",
            "parent_item_id": null,
            "product_id": "2231",
            "product_type": "simple",
            "sku": "WIDGET-BLU-12",
            "name": "Blue Widget (12 pack)",
            "description": null,
            "product_options": null,
            "qty": "2.0000",
            "price": "24.5000",
            "base_price": "24.5000",
            "discount_amount": "0.0000",
            "base_discount_amount": "0.0000",
            "tax_amount": "3.9200",
            "base_tax_amount": "3.9200",
            "subtotal": "49.0000",
            "base_subtotal": "49.0000",
            "row_total": "49.0000",
            "base_row_total": "49.0000",
            "is_taxable": "1",
            "back_to_stock": "1",
            "location_id": "1",
            "created_at": "2026-09-30 14:02:11"
        }
    ],
    "comments": [
        {
            "comment_id": "96",
            "parent_id": "187",
            "comment": "Credited 2 damaged units from invoice #100000042.",
            "customer_id": null,
            "user_id": "3",
            "is_customer_notified": "0",
            "is_visible_on_front": "1",
            "created_at": "2026-09-30 14:02:11",
            "updated_at": "2026-09-30 14:02:11"
        }
    ],
    "source_entity_links": [
        {
            "link_id": "201",
            "creditmemo_id": 
... (truncated)

Example response (404 Not found), HTTP 404:

{
    "messages": {
        "error": [
            {
                "code": 404,
                "message": "Credit memo does not exist."
            }
        ]
    }
}

Get All

GET https://container-url.zoeysite.com/api/rest/sales2/creditmemos?limit=20&page=1&order[created_at]=desc

Returns a filtered, paginated list of credit memos.

Query parameters

Param Description
limit Page size. Pagination only applies when limit is set
page Page number (1-based), used with limit
order[<field>] Sort direction, asc or desc. For example order[created_at]=desc
include_comments 1 to include each memo's comments[] (left out by default)
<field> Any filter field below, as a plain equality match, e.g. state=1
<field>[<op>] Collection condition operators, e.g. created_at[from]=2026-09-01, state[in][]=1&state[in][]=2, grand_total[gt]=100

Filters can also be nested under filters[...]. When you do that, put include_comments inside it too (filters[include_comments]=1).

Filterable fields

Credit memo columns: increment_id, store_id, state, creditmemo_type, subtotal, discount_amount, tax_amount, shipping_amount, fee_amount, payment_surcharge_amount, adjustment_amount, grand_total, created_at, updated_at, plus creditmemo_id (mapped to entity_id).

Joined fields: company_id, company_name, customer_id, customer_email, customer_firstname, customer_lastname, customer_name, store_name, guest_email, linked_entity_type, linked_entity_id, linked_bill_id, linked_invoices, linked_credit_transactions, linked_refund_transactions, applied_credit_balance, reserved_credit_balance, available_credit_balance.

linked_invoices, linked_credit_transactions and linked_refund_transactions are comma lists per memo, so a plain value on those fields does a contains match. For example linked_invoices=100000042 finds every memo linked to that invoice.

An unknown field or malformed condition returns 400 Invalid filter.

Query parameters:

NameExampleNotes
limit20Page size
page1Page number (with limit)
order[created_at]descSort field and direction
company_id37Filter: owning company
state[in][]1Filter: Unapplied
state[in][]2Filter: Partially applied
linked_invoices100000042Filter: linked to invoice (contains)
created_at[from]2026-09-01Filter: created on/after
include_comments1Include comments[] per memo

Example response (200 OK), HTTP 200:

[
    {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "2",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "applied_credit_balance": "20.0000",
        "reserved_credit_balance": "5.0000",
        "available_credit_balance": "32.9200",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "source_entity_links": [
            {
                "link_id": "201",
                "creditmemo_id": "187",
                "linked_entity_type": "2",
                "linked_entity_id": "5530",
                "items": [
                    {
                   
... (truncated)

Example response (400 Invalid filter), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "Invalid filter."
            }
        ]
    }
}

Create (from invoice lines)

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo

Creates a new credit memo and returns its full payload.

Body

Field Type Default Description
creditmemo_data object — Required. The credit memo, see below
comment string — Optional comment stored on the memo
notify_customer bool false Email the customer. For a refund handling this sends the refund receipt instead of the credit memo email
include_comment bool false Put comment in the email body. Has no effect on visibility
is_visible_on_front bool false Show comment to the customer in their account

creditmemo_data

Field Description
customer_id / company_id The account the credit belongs to. At least one is required, unless a linked invoice supplies the owner. A guest (ownerless) memo is allowed only together with a refund handling
store_id Defaults to the store of the source invoice, or the default store
creditmemo_type 1 Items (default) or 2 Amount. An Amount memo may not include items or a fee_amount
memo_amount Credit amount for an Amount memo
shipping_amount, tax_amount, discount_amount, payment_surcharge_amount, fee_amount Header amounts. fee_amount is for Items memos only
adjustment_amount Adjustment applied to the total. A memo whose grand total nets to 0 is created already Applied
created_at Optional credit memo date. It may not be later than today in the store's timezone
items[] Credit lines, see below
source_entity_links[] Optional { "linked_entity_type": 2, "linked_entity_id": <bill_id> } rows. If omitted they are derived from items[]
credit_handling credit (default), refund_offline or refund_online. An unknown value is rejected; it never falls back to credit
refund { "method_code", "method_code_comment" }. Only allowed with refund_offline, where method_code must be an offline payment method

items[]

Each line must be one of these two kinds:

Optional on either kind: qty (always units, never packages), back_to_stock (return the quantity to inventory), location_id (inventory location) and ignore_packaging (bool, deliberately break a sold package).

Ignored fields

The server always creates a new memo. creditmemo_id, entity_id, increment_id, state, key and qty_entered_in_packages are ignored on the header, and so are item_id, entity_id and parent_id on items.

Response

{ success, creditmemo, notify_customer }, plus a refund object when a refund handling was used:

Field Description
refund.increment_id Refund transaction increment id
refund.capture_case online / offline
refund.method_code, refund.method_code_comment How the refund was paid
refund.total, refund.base_total Refunded amount
refund.payment_increment_id The payment refunded. null for a ledger-only refund, e.g. when the source invoice was paid by credit

A refund failure, including a gateway decline, saves nothing. If the memo is saved but building the full response fails, the response is still success: true with only the increment ids, so the client must not retry in that case.

Example request body:

{
    "creditmemo_data": {
        "credit_handling": "credit",
        "items": [
            {
                "unique_item_id": "2_5530_9912",
                "qty": 2,
                "back_to_stock": true,
                "location_id": 1
            }
        ]
    },
    "comment": "Credited 2 damaged units.",
    "notify_customer": false,
    "include_comment": false,
    "is_visible_on_front": true
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "1",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "comments": [
            {
                "comment_id": "96",
                "parent_id": "187",
                "comment": "Credited 2 damaged units from invoice #100000042.",
                "customer_id": null,
                "user_id": "3",
                "is_customer_notified": "0",
                "is_visible_on_front": "1",
                "created_at": "2
... (truncated)

Example response (400 Partial invoice reference), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "An invoice-referencing credit memo item requires linked_entity_type, linked_entity_id and linked_entity_item_id together."
            }
        ]
    }
}

Example response (400 Missing creditmemo_data), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "creditmemo_data is required."
            }
        ]
    }
}

Create (standalone product)

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo

Standalone Items memo: credits a product that isn't tied to an invoice line. The owner (customer_id and/or company_id) is required and the price comes from the product's final price.

See Create (from invoice lines) for the full field reference.

Example request body:

{
    "creditmemo_data": {
        "company_id": 37,
        "customer_id": 15,
        "creditmemo_type": 1,
        "items": [
            {
                "product_id": 2231,
                "qty": 1,
                "back_to_stock": false
            }
        ]
    },
    "comment": "Goodwill credit for a replacement unit."
}

Create (flat amount)

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo

Amount memo (creditmemo_type: 2): a flat credit of memo_amount with no line items. items and fee_amount are rejected on this type.

See Create (from invoice lines) for the full field reference.

Example request body:

{
    "creditmemo_data": {
        "company_id": 37,
        "customer_id": 15,
        "creditmemo_type": 2,
        "memo_amount": 150,
        "created_at": "2026-09-30"
    },
    "comment": "Pricing adjustment for September.",
    "notify_customer": true,
    "include_comment": true,
    "is_visible_on_front": true
}

Example response (400 Items on Amount memo), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "AMOUNT-type credit memo cannot include an items list."
            }
        ]
    }
}

Create + offline refund

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo

Creates the memo and immediately pays all of its credit out as an offline refund in the same step. refund.method_code must be an offline payment method. notify_customer sends the refund receipt.

For a gateway refund use credit_handling: refund_online and leave out refund (sending it is rejected).

See Create (from invoice lines) for the full field reference.

Example request body:

{
    "creditmemo_data": {
        "credit_handling": "refund_offline",
        "refund": {
            "method_code": "checkmo",
            "method_code_comment": "Check #4471"
        },
        "items": [
            {
                "linked_entity_type": 2,
                "linked_entity_id": 5530,
                "linked_entity_item_id": 9912,
                "qty": 1
            }
        ]
    },
    "comment": "Refunded by check.",
    "notify_customer": true
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "188",
        "store_id": "1",
        "increment_id": "100000188",
        "company_id": "37",
        "customer_id": "15",
        "state": "3",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "comments": [
            {
                "comment_id": "96",
                "parent_id": "187",
                "comment": "Credited 2 damaged units from invoice #100000042.",
                "customer_id": null,
                "user_id": "3",
                "is_customer_notified": "0",
                "is_visible_on_front": "1",
                "created_at": "2
... (truncated)

Example response (400 Refund details on non-offline handling), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "refund details apply to credit_handling refund_offline only."
            }
        ]
    }
}

Example response (400 Unknown handling), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "Unknown credit handling."
            }
        ]
    }
}

Cancel

POST https://container-url.zoeysite.com/api/rest/sales2/creditmemo/100000187/cancel

Cancels a credit memo and returns its full payload, with state now 4 (Canceled).

Only an Unapplied memo (state: 1) can be canceled. Anything else returns 400 Credit memo cannot be canceled. Canceling releases any reservations the memo holds and moves them onto the account's remaining available credit memos.

Path

:incrementId is the credit memo increment id.

Body (optional)

Field Type Default Description
notify_customer bool false Send the cancellation email
comment string "" Comment stored on the memo with the cancellation

Example request body:

{
    "notify_customer": false,
    "comment": "Issued in error."
}

Example response (200 OK), HTTP 200:

{
    "success": true,
    "creditmemo": {
        "creditmemo_id": "187",
        "store_id": "1",
        "increment_id": "100000187",
        "company_id": "37",
        "customer_id": "15",
        "state": "4",
        "creditmemo_type": "1",
        "memo_amount": "0.0000",
        "base_memo_amount": "0.0000",
        "subtotal": "49.0000",
        "base_subtotal": "49.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "tax_amount": "3.9200",
        "base_tax_amount": "3.9200",
        "shipping_amount": "0.0000",
        "base_shipping_amount": "0.0000",
        "fee_amount": "0.0000",
        "payment_surcharge_amount": "0.0000",
        "adjustment_amount": "0.0000",
        "grand_total": "52.9200",
        "base_grand_total": "52.9200",
        "global_currency_code": "USD",
        "base_currency_code": "USD",
        "store_currency_code": "USD",
        "base_to_global_rate": "1.0000",
        "base_to_store_rate": "1.0000",
        "created_at": "2026-09-30 14:02:11",
        "updated_at": "2026-09-30 14:02:11",
        "items": [
            {
                "item_id": "412",
                "parent_id": "187",
                "parent_item_id": null,
                "product_id": "2231",
                "product_type": "simple",
                "sku": "WIDGET-BLU-12",
                "name": "Blue Widget (12 pack)",
                "description": null,
                "product_options": null,
                "qty": "2.0000",
                "price": "24.5000",
                "base_price": "24.5000",
                "discount_amount": "0.0000",
                "base_discount_amount": "0.0000",
                "tax_amount": "3.9200",
                "base_tax_amount": "3.9200",
                "subtotal": "49.0000",
                "base_subtotal": "49.0000",
                "row_total": "49.0000",
                "base_row_total": "49.0000",
                "is_taxable": "1",
                "back_to_stock": "1",
                "location_id": "1",
                "created_at": "2026-09-30 14:02:11"
            }
        ],
        "comments": [
            {
                "comment_id": "96",
                "parent_id": "187",
                "comment": "Credited 2 damaged units from invoice #100000042.",
                "customer_id": null,
                "user_id": "3",
                "is_customer_notified": "0",
                "is_visible_on_front": "1",
                "created_at": "2
... (truncated)

Example response (400 Not cancelable), HTTP 400:

{
    "messages": {
        "error": [
            {
                "code": 400,
                "message": "Credit memo cannot be canceled."
            }
        ]
    }
}