Credit Notes API: Record and Manage Customer Debts

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.

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.

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

string

Name of the customer who owes the balance. Defaults to an empty string if omitted.

number

required

The amount owed, as a positive decimal number.

string

A free-text note describing what the debt is for (e.g. "Weekly groceries — not paid"). Defaults to "".

string

Optional ISO 8601 date by which payment is expected (e.g. "2024-02-15"). If omitted, no due date is set.

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`

integer

Unique ID of the credit note.

integer

ID of the shop that issued the credit note.

string

Display name of the issuing shop.

string

Name of the customer who owes the balance.

string

The outstanding amount, as a decimal string.

string

Free-text note attached to this credit note.

string

Current status of the credit note. One of pending, paid, or cancelled.

string

ISO 8601 due date, if set. May be null.

string

ISO 8601 timestamp of when the credit note was created.

string

ISO 8601 timestamp of the most recent update.

List Credit Notes

Retrieve all credit notes for a shop, optionally filtered by status. GET /api/v1/credit-notes/{shop_id}/

string

Filter by note status. Accepted values: pending, paid, cancelled. Omit to return all statuses.

# 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}/

string

New status for the credit note. Accepted values: pending, paid, cancelled.

string

Updated free-text note. Replaces the existing note text if provided.

# 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

integer

Unique ID of the credit note.

integer

ID of the shop that issued the note.

string

Display name of the issuing shop.

string

Name of the customer who owes the balance.

string

Amount owed, as a decimal string.

string

Descriptive note attached to the record.

string

pending, paid, or cancelled.

string

ISO 8601 due date, or null if not set.

string

ISO 8601 creation timestamp.

string

ISO 8601 timestamp of the last update.

Shops

Products

Sales & Inventory

Public & Misc

Credit Notes API: Record and Manage Customer Debts

Create a Credit Note

Request body

Response — `CreditNoteOut`

List Credit Notes

Update a Credit Note

Status Reference

`CreditNoteOut` Field Reference

​Create a Credit Note

​Request body

​Response — CreditNoteOut

​List Credit Notes

​Update a Credit Note

​Status Reference

​CreditNoteOut Field Reference

Create a Credit Note

Request body

Response — `CreditNoteOut`

List Credit Notes

Update a Credit Note

Status Reference

`CreditNoteOut` Field Reference