Credit Memos

Credit memos represent credits issued to customers, reducing the amount they owe. They can be applied to outstanding invoices or held as a balance on the customer's account.

Credit Memo Status Flow

Flow: draft → issued → partially_applied → applied; a draft or issued memo can be voided.

Create a Credit Memo

curl -X POST "https://api.ondayzero.com/api/v1/credit-memos" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUSTOMER_UUID",
    "amount_cents": 15000,
    "reason": "returned_goods"
  }'

amount_cents (must be greater than 0) is in cents. 15000 = $150.00. reason must be one of the supported enum values (returned_goods, damaged_goods, service_issue, pricing_error, billing_adjustment, goodwill, duplicate_charge, other — the default).

The response data is the new memo in draft status:

{
  "success": true,
  "data": {
    "id": "019ab37c-c301-7000-8000-000000000001",
    "customer_id": "019ab37c-c057-7000-8000-000000000001",
    "number": "CM-001",
    "status": "draft",
    "currency": "USD",
    "amount": 15000,
    "amount_in_dollars": 150.0,
    "amount_applied": 0,
    "amount_remaining": 15000,
    "issue_date": "2026-10-14",
    "reason": "returned_goods",
    "reason_display": "Returned Goods",
    "can_be_applied": false,
    "can_be_voided": true,
    "can_be_deleted": true,
    "has_applications": false
  }
}

Optional fields: invoice_id (the original invoice being credited), description, internal_notes, issue_date (defaults to today), line_items ([{description, quantity, unit_price_cents, amount_cents, variant_id}] for itemised credits) and restocking_fee_cents (a fee withheld on a return, recognised as income — the gross reversal is amount_cents + fee).

GET /api/v1/credit-memos/{credit_memo_id} returns the memo with its applications. The response shows each amount in cents and in dollars (amount, amount_applied, amount_remaining and their _in_dollars twins), plus number (for example CM-001), reason_display, voided_at / voided_reason, and the flags can_be_applied, can_be_voided, can_be_deleted and has_applications.

Only draft memos can be edited with PUT /api/v1/credit-memos/{credit_memo_id} (same fields as create, all optional). DELETE removes a draft or void memo (a voided memo's journal entries are deleted with it); a memo that has had credit applied cannot be deleted. POST /api/v1/credit-memos/suggest asks the AI which recent returns or disputes might warrant a credit.

Issue a Credit Memo

Draft credit memos must be issued before they can be applied. Issuing posts the journal entry that reduces accounts receivable and, for line items that carry a variant_id, restocks that inventory. If the memo was created with an invoice_id, issuing also applies it to that invoice automatically (up to the lesser of the memo balance and the invoice's balance due), unless the invoice is already paid or belongs to a different customer.

curl -X POST "https://api.ondayzero.com/api/v1/credit-memos/{credit_memo_id}/issue" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Apply to an Invoice

Apply a credit memo (partially or fully) to an outstanding invoice:

curl -X POST "https://api.ondayzero.com/api/v1/credit-memos/{credit_memo_id}/apply" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "INVOICE_UUID",
    "amount_cents": 10000
  }'

The memo must be issued or partially_applied with a remaining balance, the invoice must belong to the same customer and not already be paid, and amount_cents cannot exceed either the memo's remaining balance or the invoice's balance due (each returns 400). Applying reduces the invoice's balance_due and moves the memo to partially_applied or applied; the invoice becomes partially_paid, or manual_paid once the credit covers the whole balance. To reverse an application, POST /api/v1/credit-memos/{credit_memo_id}/unapply with {"invoice_id": "INVOICE_UUID"} removes the application(s) linking the two, restores both balances and recomputes the invoice status. No reversing journal entry is posted. The response has amount_unapplied, applications_removed, credit_memo_status, amount_remaining and invoice_status.

List Credit Memos

curl "https://api.ondayzero.com/api/v1/credit-memos?status=issued&customer_id=CUSTOMER_UUID" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Filter Parameters

Customer Credit Balance

View the credits still available for a specific customer (memos with an unapplied balance):

curl "https://api.ondayzero.com/api/v1/credit-memos/customers/{customer_id}/credits" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

The response has total_credits_available (cents), credit_memos_count and the credit_memos themselves.

Void a Credit Memo

curl -X POST "https://api.ondayzero.com/api/v1/credit-memos/{credit_memo_id}/void" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Issued in error"}'

Only draft and issued memos can be voided; once any credit has been applied (partially_applied or applied), unapply it first. reason is required. Voiding an issued memo posts a reversing journal entry and reverses any inventory restock; voiding a draft has no accounting effect.

MCP Tools

Regent and MCP clients can drive the same flow; every write asks for your approval first (see MCP Server).

Errors

All of these are 400 (validation_error) unless noted; branch on the code, not the message.