# Credit Memos

> Issue and apply credit memos — manage customer credits and refunds.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/credit-memos
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# 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

| Status | Description |
|--------|-------------|
| `draft` | Editable, not yet issued |
| `issued` | Active, available for application |
| `partially_applied` | Some balance applied, remainder still available |
| `applied` | Fully applied to invoices |
| `void` | Cancelled |

## Create a Credit Memo

```bash
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` 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).

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).

Draft memos can be edited with `PUT /api/v1/credit-memos/{credit_memo_id}` and deleted with `DELETE`. `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:

```bash
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:

```bash
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
  }'
```

Applying reduces the invoice's `balance_due` and moves the memo to `partially_applied` or `applied`. To reverse an application, `POST /api/v1/credit-memos/{credit_memo_id}/unapply` with `{"invoice_id": "INVOICE_UUID"}` restores both balances.

## List Credit Memos

```bash
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

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | `draft`, `issued`, `partially_applied`, `applied`, `void` |
| `customer_id` | UUID | Filter by customer |
| `has_remaining_balance` | boolean | Only credits with unapplied balance |
| `search` | string | Match on credit memo number (e.g. `CM-0001`) |
| `cursor` / `limit` | | Standard [pagination](/docs/guides/pagination) |

## Customer Credit Balance

View all credits for a specific customer:

```bash
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"
```

## Void a Credit Memo

```bash
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"}'
```

Voiding reverses any associated journal entries.