> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutasib.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit Notes API: Record and Manage Customer Debts

> Create, update, and query credit notes to track what customers owe per shop, with due dates and pending, paid, or cancelled status.

A credit note represents money a customer owes your shop — an informal debt recorded against a name. Instead of tracking these balances in a paper notebook or a separate spreadsheet, Mutasib lets you create, update, and query credit notes digitally, complete with due dates and status tracking.

<Note>
  Credit notes are a **Pro plan** feature. Shops on the Free or Starter plans cannot create or view credit notes. Upgrade your plan in the Mutasib dashboard under **Settings → Subscription**.
</Note>

## Create a Credit Note

Send a `POST` request to create a new credit note for a customer. You must supply an `amount`; all other fields are optional.

**`POST /api/v1/credit-notes/{shop_id}/`**

### Request body

<ParamField path="customer_name" type="string">
  Name of the customer who owes the balance. Defaults to an empty string if omitted.
</ParamField>

<ParamField path="amount" type="number" required>
  The amount owed, as a positive decimal number.
</ParamField>

<ParamField path="note" type="string">
  A free-text note describing what the debt is for (e.g. `"Weekly groceries — not paid"`). Defaults to `""`.
</ParamField>

<ParamField path="due_date" type="string">
  Optional ISO 8601 date by which payment is expected (e.g. `"2024-02-15"`). If omitted, no due date is set.
</ParamField>

```bash theme={null}
curl -X POST https://api.mutasib.com/api/v1/credit-notes/42/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Ahmed Al-Rashid",
    "amount": 87.50,
    "note": "Monthly tab — February",
    "due_date": "2024-02-29"
  }'
```

### Response — `CreditNoteOut`

<ResponseField name="id" type="integer">
  Unique ID of the credit note.
</ResponseField>

<ResponseField name="shop_id" type="integer">
  ID of the shop that issued the credit note.
</ResponseField>

<ResponseField name="shop_name" type="string">
  Display name of the issuing shop.
</ResponseField>

<ResponseField name="customer_name" type="string">
  Name of the customer who owes the balance.
</ResponseField>

<ResponseField name="amount" type="string">
  The outstanding amount, as a decimal string.
</ResponseField>

<ResponseField name="note" type="string">
  Free-text note attached to this credit note.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the credit note. One of `pending`, `paid`, or `cancelled`.
</ResponseField>

<ResponseField name="due_date" type="string">
  ISO 8601 due date, if set. May be `null`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the credit note was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>

***

## List Credit Notes

Retrieve all credit notes for a shop, optionally filtered by status.

**`GET /api/v1/credit-notes/{shop_id}/`**

<ParamField query="status" type="string">
  Filter by note status. Accepted values: `pending`, `paid`, `cancelled`. Omit to return all statuses.
</ParamField>

```bash theme={null}
# All outstanding (unpaid) credit notes
curl "https://api.mutasib.com/api/v1/credit-notes/42/?status=pending" \
  -H "Authorization: Bearer <token>"
```

Returns an array of `CreditNoteOut` objects.

***

## Update a Credit Note

Update the status or note text of an existing credit note. Use this endpoint to mark a balance as paid after a customer settles up, or to cancel a note that was created in error.

**`PATCH /api/v1/credit-notes/{shop_id}/{note_id}/`**

<ParamField path="status" type="string">
  New status for the credit note. Accepted values: `pending`, `paid`, `cancelled`.
</ParamField>

<ParamField path="note" type="string">
  Updated free-text note. Replaces the existing note text if provided.
</ParamField>

```bash theme={null}
# Mark a credit note as paid
curl -X PATCH https://api.mutasib.com/api/v1/credit-notes/42/318/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'
```

Returns the updated `CreditNoteOut` object.

***

## Status Reference

| Status      | Meaning                                      |
| ----------- | -------------------------------------------- |
| `pending`   | The debt is outstanding and not yet settled. |
| `paid`      | The customer has paid the full amount.       |
| `cancelled` | The note was voided and no longer applies.   |

A note can only move from `pending` → `paid` or `pending` → `cancelled`. Once a note is marked `paid` or `cancelled`, it cannot be reverted to `pending`.

***

## `CreditNoteOut` Field Reference

<ResponseField name="id" type="integer">
  Unique ID of the credit note.
</ResponseField>

<ResponseField name="shop_id" type="integer">
  ID of the shop that issued the note.
</ResponseField>

<ResponseField name="shop_name" type="string">
  Display name of the issuing shop.
</ResponseField>

<ResponseField name="customer_name" type="string">
  Name of the customer who owes the balance.
</ResponseField>

<ResponseField name="amount" type="string">
  Amount owed, as a decimal string.
</ResponseField>

<ResponseField name="note" type="string">
  Descriptive note attached to the record.
</ResponseField>

<ResponseField name="status" type="string">
  `pending`, `paid`, or `cancelled`.
</ResponseField>

<ResponseField name="due_date" type="string">
  ISO 8601 due date, or `null` if not set.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the last update.
</ResponseField>