Skip to main content

Invoices

Beta

Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.

What it is for​

Every successful payment produces an invoice, every refund a credit note, in your name and with your legal mentions (the invoicing block of your payment account). You have nothing to generate: you read them, download them, and make them available to your customers.

1. List and read invoices​

curl -s "https://billing-api.dev.stackngo.fr/v1/invoices?customer_id=cus_01J9ZR1A2B3C4D5E6F7G" \
  -H "Authorization: Bearer $TOKEN"
{
  "data": [
    {
      "id": "inv_01J9ZS3E…",
      "kind": "invoice",
      "number": "ACME-2026-000042",
      "status": "paid",
      "issue_date": "2026-11-01",
      "period_start": "2026-10-01",
      "period_end": "2026-10-31",
      "currency": "EUR",
      "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G",
      "payment_id": "pay_01J9ZS3D…",
      "lines": [ "…" ],
      "totals": { "subtotal": "76.50", "tax": "15.30", "total": "91.80", "taxes": [ "…" ] },
      "pdf_ready": true,
      "pdf_sha256": "9f2c…"
    }
  ],
  "next_cursor": "…"
}

Filters: customer_id, kind (invoice or credit_note), limit, cursor.

2. Download the PDF​

curl -s -o ACME-2026-000042.pdf \
  https://billing-api.dev.stackngo.fr/v1/invoices/inv_01J9ZS3E…/pdf \
  -H "Authorization: Bearer $TOKEN"

What you get​

  • A Factur-X PDF: a human-readable PDF/A-3 that embeds the structured XML file (CII) readable by accounting software. EN16931 profile (complete, recommended) or BASIC, depending on invoicing.facturxProfile.
  • The mentions of your account: legal name, legal form, SIREN, SIRET, VAT number, RCS, share capital, address, payment terms, late penalties, free mentions; and those of your customer (name, address, SIREN and VAT number if provided).
  • Detailed VAT per category and rate.
  • A fingerprint pdf_sha256: the PDF is produced once and never changes.

3. Open the customer portal​

Rather than sending every PDF, give your customer a link to their portal: their invoices and credit notes, their subscriptions and their payment method, which they can replace.

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/portal-links \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G", "return_url": "https://shop.acme.example/compte", "ttl_seconds": 3600 }'
{ "url": "https://pay.dev.stackngo.fr/acme/…", "expires_at": "2026-10-08T11:40:00Z" }

The link is signed and time-limited (ttl_seconds from 300 s to 24 h): generate it when your customer clicks "My invoices" in your application, and redirect them.

What you can expect​

  • Continuous numbering, without gaps, in the form <numberPrefix>-<year>-<number>; credit notes have their own series. With numberingReset: yearly, the series restarts at 1 every year.
  • An issued invoice is unalterable: any correction goes through a credit note.
  • Changing your invoicing block only affects the following invoices.
  • Invoices and credit notes are kept for 10 years.
  • You receive invoice.finalized for every invoice or credit note issued: the right moment to send the invoice to your customer.

Not available yet​

  • Transmission to e-invoicing platforms (PDP) for mandatory e-invoicing: download your Factur-X invoices and send them yourself.
  • Several currencies in one invoice.

If it does not work​

What you seeCauseFix
409 on …/pdf, pdf_ready: falsethe PDF is being produced, right after the paymentretry a few seconds later, or wait for invoice.finalized
404identifier of an invoice of another account, or typocheck the identifier (inv_…)
Legal mention missing or wronginvoicing block incomplete when the invoice was issuedfix invoicing; for an invoice already issued, issue a credit note and invoice again
The customer sees "link expired" on the portalttl_seconds exceededgenerate a new link at each visit

See also Payments troubleshooting.

See also​