> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Credit Notes
> Reduce what a customer owes on an issued invoice, or record a credit that later refunds them, without rewriting the invoice
A credit note is the document that corrects an issued invoice. It reduces what the customer owes — or, if the invoice is already paid, records the amount you are returning to them — while leaving the original invoice intact for the audit trail. Use one for overcharges, service credits, partial cancellations, or price adjustments after the fact. Voiding is for withdrawing an invoice entirely; a credit note is for adjusting it.
A credit note starts as a `draft`, then is **applied** to finalize it. Applying to an unpaid invoice reduces the balance due; applying to a paid invoice optionally triggers a [refund](/docs/invoices/refunds) to the original payment or a [wallet](/docs/credits/wallets). See [How Alguna Works](/docs/concepts/how-alguna-works) for where corrections sit in the lifecycle.
***
## When to use one
| Scenario | Effect |
| - | - |
| Billing error on an unpaid invoice | Apply a credit note; `amount_remaining` drops |
| Service credit after an incident | Credit the affected lines; the customer pays less |
| Partial cancellation of a paid invoice | Credit the unused units and refund them |
| Full refund of a paid invoice | Credit everything and refund to the original payment |
| Goodwill balance for future use | Credit and refund to a wallet |
***
## Statuses
| `status` | Meaning |
| - | - |
| `draft` | Created, line items editable, nothing applied yet |
| `applied` | Finalized and applied against the invoice or customer. Cannot be modified. |
| `pending_refund` | Applied to a paid invoice with a refund requested; the refund is in flight |
| `void` | Withdrawn |
***
## Credit an invoice
The simplest path: `POST /invoices/{id}/credit-notes` creates a draft that credits invoice lines at exactly the prices and tax they were billed with — no re-calculation. Omit `line_items` to credit everything still uncredited; pass them to credit specific lines by the `quantity` of units (fractional allowed). See [Credit an invoice](/docs/api-reference/v2/2026-04-01/credit-notes/credit-an-invoice).
```bash cURL theme={null}
curl -X POST https://api.alguna.io/invoices/inv_abc123/credit-notes \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01" \
-H "Content-Type: application/json" \
-d '{
"line_items": [
{ "invoice_line_item_id": "li_xyz789", "quantity": "2" }
]
}'
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.alguna.io/invoices/inv_abc123/credit-notes",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
"Content-Type": "application/json",
},
json={"line_items": [{"invoice_line_item_id": "li_xyz789", "quantity": "2"}]},
timeout=10,
)
response.raise_for_status()
credit_note = response.json()
print(credit_note["id"], credit_note["status"], credit_note["total"])
```
```typescript TypeScript theme={null}
const creditNote = await alguna.creditNotes.createFromInvoice("inv_abc123", {
line_items: [{ invoice_line_item_id: "li_xyz789", quantity: "2" }],
});
```
Every line here must reference an invoice line. Each invoice line's `amount_including_tax` in `GET /invoices/{id}` is what a full credit of that line returns.
***
## Create a credit note with your own lines
`POST /credit-notes` builds a draft from lines you specify. Link it to an invoice with `invoice_id`, or give a `customer_id` for a credit not tied to a specific invoice. A line either credits an invoice line (`invoice_line_item_id` + `quantity`, reusing its price and tax) or prices something new (`description`, `quantity`, tax-exclusive `unit_price`; tax is calculated on top). See [Create a credit note](/docs/api-reference/v2/2026-04-01/credit-notes/create-a-credit-note).
```bash cURL theme={null}
curl -X POST https://api.alguna.io/credit-notes \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": "inv_abc123",
"description": "Service credit - March outage",
"line_items": [
{ "description": "SLA credit", "quantity": "1", "unit_price": "250.00" }
]
}'
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.alguna.io/credit-notes",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
"Content-Type": "application/json",
},
json={
"invoice_id": "inv_abc123",
"description": "Service credit - March outage",
"line_items": [{"description": "SLA credit", "quantity": "1", "unit_price": "250.00"}],
},
timeout=10,
)
response.raise_for_status()
print(response.json()["id"])
```
```typescript TypeScript theme={null}
const creditNote = await alguna.creditNotes.create({
invoice_id: "inv_abc123",
description: "Service credit - March outage",
line_items: [{ description: "SLA credit", quantity: "1", unit_price: "250.00" }],
});
```
Pre-payment credit notes — against an invoice that is `issued` or `overdue` — are supported for Alguna-issued invoices. Linked paid invoices are supported too.
***
## Apply a credit note
Applying finalizes the draft. `do_refund` is required: `false` for an unpaid invoice (the balance is reduced) or when you want a paid invoice credited without money moving; `true` to refund a paid invoice, with `refund_destination` of `original_payment` or `wallet` (plus `wallet_id`). See [Apply a credit note](/docs/api-reference/v2/2026-04-01/credit-notes/apply-a-credit-note).
```bash cURL theme={null}
curl -X POST https://api.alguna.io/credit-notes/cn_abc123/apply \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01" \
-H "Content-Type: application/json" \
-d '{ "do_refund": true, "refund_destination": "original_payment" }'
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.alguna.io/credit-notes/cn_abc123/apply",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
"Content-Type": "application/json",
},
json={"do_refund": True, "refund_destination": "original_payment"},
timeout=10,
)
response.raise_for_status()
credit_note = response.json()
print(credit_note["status"], credit_note.get("last_refund_id"))
```
```typescript TypeScript theme={null}
await alguna.creditNotes.apply("cn_abc123", {
do_refund: true,
refund_destination: "original_payment",
});
```
Once applied, a credit note cannot be modified or un-applied. Review the draft first — `GET /credit-notes/{id}` returns its `line_items`, `subtotal`, `tax`, and `total`.
### Who can apply one
Two controls govern who can credit an invoice. The draft stage separates creating a credit note from applying it, so someone other than the author can review the lines and amounts while nothing has moved yet. Role permissions decide who may do either: **Manage credit notes** covers creating and applying, **View credit notes** is read-only, and roles are configured under **Settings → Admin → Users → Custom roles**. Every application is recorded under **Settings → Logs → Audit log** with the user who made it.
### Create and apply in one call
Set `apply: true` on `POST /credit-notes` to create and apply synchronously. To refund as well, add `refund: { "destination": "original_payment" }`; this requires a linked invoice that is paid. If applying fails, the credit note is left in `draft` and the error names it so you can apply it separately.
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.alguna.io/credit-notes",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
"Content-Type": "application/json",
},
json={
"invoice_id": "inv_abc123",
"line_items": [{"invoice_line_item_id": "li_xyz789", "quantity": "1"}],
"apply": True,
"refund": {"destination": "original_payment"},
},
timeout=10,
)
response.raise_for_status()
print(response.json()["status"]) # "applied" or "pending_refund"
```
***
## Read credit notes
`GET /credit-notes?customer_id=…` lists a customer's credit notes (`customer_id` is required); `GET /credit-notes/{id}` returns one. Useful fields:
| Field | Meaning |
| - | - |
| `invoice_id` | The credited invoice, if any |
| `external_reference` | Customer-facing credit note number |
| `apply_date`, `void_date` | When it was applied or voided |
| `last_refund_id`, `last_refund_date` | The most recent [refund](/docs/invoices/refunds) it triggered |
| `is_pdf_available` | Whether a PDF has been rendered |
| `accounting_*`, `sync_enabled` | Its counterpart in a connected accounting system |
| `merchant_id` | Inherited from the credited invoice when issued for a [merchant](/docs/concepts/how-alguna-works) |
***
## In the dashboard
1. Open the invoice under **Invoices** and choose **Create Credit Note** from its actions.
2. Pick the lines and quantities to credit, or add a custom line. The credit note is created as a `draft`.
3. Open the draft and choose **Apply Credit Note**. For a paid invoice you choose where the money goes: **Refund to payment method**, **Refund offline** (you return the money yourself and record it), **Apply to wallet**, or **Create and apply to a new wallet**.
4. Optionally send the customer the credit note email.
All credit notes are listed under **Invoices → Credit Notes**, filterable by status, date, and customer.
***
## Next steps
What a refund is, its statuses, and when to create one directly.
Refund to a prepaid balance instead of the original payment.
Invoice statuses and organization settings.
Full request and response reference.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.