Credit Notes

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 to the original payment or a wallet. See 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.

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" }
    ]
  }'

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"])

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.

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" }
    ]
  }'

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"])

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.

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

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

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.

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

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

In the dashboard

Open the invoice under Invoices and choose Create Credit Note from its actions.
Pick the lines and quantities to credit, or add a custom line. The credit note is created as a draft.
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.
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

Refunds

What a refund is, its statuses, and when to create one directly.

Wallets

Refund to a prepaid balance instead of the original payment.

Invoicing Configuration

Invoice statuses and organization settings.

Credit Notes API

Full request and response reference.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

When to use one

Statuses

Credit an invoice

Create a credit note with your own lines

Apply a credit note

Create and apply in one call

Read credit notes

In the dashboard

Next steps

Refunds

Wallets

Invoicing Configuration

Credit Notes API

​When to use one

​Statuses

​Credit an invoice

​Create a credit note with your own lines

​Apply a credit note

​Create and apply in one call

​Read credit notes

​In the dashboard

​Next steps

Refunds

Wallets

Invoicing Configuration

Credit Notes API

When to use one

Statuses

Credit an invoice

Create a credit note with your own lines

Apply a credit note

Create and apply in one call

Read credit notes

In the dashboard

Next steps