Invoices

Invoices let you issue, send, and manage customer invoices programmatically. Each invoice generates a hosted payment link and can be sent automatically by email. It is linked to a Customer and can contain one or more product line items.

The standard flow is: create an invoice (draft) → finalize → send by email → wait for payment (paid).

Lifecycle

draft→open→paid / void / uncollectible

Status	Meaning	Available action
`draft`	Draft — editable, not sent.	`/finalize/` to move to open.
`open`	Finalized — payment link active.	`/send/`, `/pay/`, `/void/`.
`paid`	Settled — payment received.	No action available.
`void`	Canceled — link disabled.	Create a new Invoice.
`uncollectible`	Declared uncollectible.	Manual action only.

Endpoints

Méthode	Endpoint	Description
POST	`/invoices/`	Create an invoice (draft status)
GET	`/invoices/`	List invoices
GET	`/invoices/{id}/`	Retrieve an invoice
PATCH	`/invoices/{id}/`	Update a draft invoice
POST	`/invoices/{id}/finalize/`	Finalize (draft → open)
POST	`/invoices/{id}/send/`	Send by email to the Customer
POST	`/invoices/{id}/void/`	Cancel an open invoice
POST	`/invoices/{id}/pay/`	Mark as paid manually

Is this introduction clear?

Object schema

ResponseInvoice object

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "open",
  "customer": "cust_xxxxxxxx",
  "customer_email": "client@email.com",
  "currency": "XAF",
  "subtotal": 50000,
  "tax_amount": 0,
  "discount_amount": 0,
  "total": 50000,
  "amount_paid": 0,
  "amount_remaining": 50000,
  "due_date": "2026-04-01",
  "description": "Consulting invoice — March 2026",
  "footer": "Thank you for your business.",
  "payment_url": "https://pay.sangho.ga/i/inv_xxxx",
  "pdf_url": "https://api.sangho.ga/v1/invoices/inv_xxxx/pdf/",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Strategic consulting",
      "quantity": 2,
      "unit_amount": 25000,
      "amount": 50000
    }
  ],
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Create an Invoice

Creates an invoice with draft status. At this stage, it is fully editable. No email is sent and no payment link is active.

POSTRequest body

customerRequis

stringcust_...

ID of the Customer the invoice is addressed to. The Customer’s email and name will be used on the PDF invoice and in the email sent.

line_itemsRequis

array[object]

Invoice line items. Each line contains either a product or a free-form amount, a quantity, and a price.

Each item must contain: product (ID of an existing Product) or description + unit_amount for a free-form line. quantity is a positive integer (default: 1). VAT is calculated automatically based on your App’s configuration.

currencyOptionnel

stringISO 4217défaut :App currency

Currency code for the invoice. By default, your App’s main currency is used.

due_dateOptionnel

stringYYYY-MM-DDdéfaut :+30 daysex :2026-04-01

Payment due date. Displayed on the PDF invoice and in the email sent.

If not provided, the due date is set to 30 days after the finalization date (not the creation date). Once the due date has passed, the invoice stays open — Sangho does not send automatic reminders. You can implement reminders via the invoice.payment_overdue webhooks.

descriptionOptionnel

string

Subject or description of the invoice. Appears in the header of the PDF invoice and in the email.

footerOptionnel

string

Footer text for the PDF invoice. Useful for legal notices, IBAN, payment terms.

Max 500 characters. Displayed only on the PDF — not on the online payment page.

metadataOptionnel

object

Free-form data — purchase order reference, contract number, etc.

Finalize, Send, Cancel

Finalize (/finalize/): locks the invoice and generates the payment link. The invoice moves to open. The line items and the total amount can no longer be modified.

Send (/send/): sends the invoice by email to the Customer with the payment link and the PDF attached. Can be called multiple times (manual reminder).

Finalize + Send in a single operation

You can call /finalize/ followed immediately by /send/. Or pass auto_send: true in the body of /finalize/ to trigger the send automatically upon finalization.

Cancel (/void/): permanently invalidates the invoice. The payment link is disabled. Irreversible — create a new Invoice if needed.

Is the Invoices lifecycle clear?

Create and send an invoice

bash

# 1. Create (draft)
curl -X POST https://api.sangho.ga/v1/invoices/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxxxxxxx",
    "currency": "XAF",
    "due_date": "2026-04-15",
    "description": "Consulting services — April 2026",
    "footer": "Payment due within 30 days. IBAN: GA00 0000 0000.",
    "line_items": [
      { "product": "prod_xxx", "quantity": 2 },
      { "description": "Travel expenses", "unit_amount": 5000, "quantity": 1 }
    ]
  }'


# 2. Finalize
curl -X POST https://api.sangho.ga/v1/invoices/inv_xxx/finalize/ \
  -H "Authorization: Bearer sk_prod_xxxx"


# 3. Send by email
curl -X POST https://api.sangho.ga/v1/invoices/inv_xxx/send/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response201 Created — Draft

The invoice is created in draft. No email is sent, no active link. Editable via PATCH.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "draft",
  "customer": "cust_xxxxxxxx",
  "total": 55000,
  "currency": "XAF",
  "due_date": "2026-04-15",
  "payment_url": null,
  "pdf_url": null,
  "created_at": "2026-03-15T09:00:00Z"
}

Response200 OK — Finalized (open)

The invoice is locked. The payment link is active. Send /send/ to notify the customer.

Once finalized, the line_items and total amount can no longer be modified. Create a new Invoice if there is an error.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "status": "open",
  "total": 55000,
  "payment_url": "https://pay.sangho.ga/i/inv_xxxx",
  "pdf_url": "https://api.sangho.ga/v1/invoices/inv_xxxx/pdf/",
  "updated_at": "2026-03-15T09:05:00Z"
}