ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Storlaunch Docs
⌘K

Invoices

An invoice is a billing artifact: the immutable record of "we charged this customer this amount on this date for this stuff". Invoices fire from two sources:

  1. Subscription cycles — one invoice per period per subscription. Auto-created by the billing cron.
  2. Manual issuance — the merchant generates an invoice (via the dashboard or POST /v1/billing/plugipay-invoice) for a one-off charge.

Invoices are mostly read-only from the API: list, retrieve, export. Settlement happens via the underlying Plugipay flow (when the module is on) or via the locally-issued sessions.

All endpoints require an sk_* key.

Endpoints

Method Path Purpose
GET /v1/payment/invoices List invoices
GET /v1/payment/invoices/:id Retrieve one invoice
GET /v1/payment/invoices/:id/pdf Download the invoice as PDF
GET /v1/payment/invoices/:id/html Render the invoice as HTML (web-ready)
GET /v1/payment/invoices/export.csv CSV bulk export

List

GET /v1/payment/invoices?limit=50&cursor=…&status=…&customerId=…

Cursor-paginated, newest-first. Filters:

Param Description
status draft, open, paid, uncollectible, void.
customerId Restrict to one customer's invoices.
subscriptionId Restrict to one subscription's invoice history.
createdAfter / createdBefore ISO 8601 windows.

Retrieve

GET /v1/payment/invoices/:id

Returns the full invoice with line items, totals, and (when relevant) tax breakdown.

{
  "data": {
    "id": "inv_01HX...",
    "accountId": "acc_01HX...",
    "customerId": "cust_01HX...",
    "subscriptionId": "sub_01HX...",
    "number": "INV-ACME-001042",
    "status": "paid",
    "amount": 250000,
    "currency": "IDR",
    "subtotal": 227273,
    "taxAmount": 22727,
    "lineItems": [
      { "description": "Pro Monthly", "quantity": 1, "unitAmount": 227273, "amount": 227273 }
    ],
    "issuedAt": "2026-05-01T00:00:00Z",
    "dueAt": "2026-05-08T00:00:00Z",
    "paidAt": "2026-05-01T03:14:22Z",
    "voidedAt": null,
    "hostedUrl": "https://pay.plugipay.com/i/inv_01HX...",
    "pdfUrl": "https://storlaunch.forjio.com/api/v1/payment/invoices/inv_01HX.../pdf",
    "metadata": {},
    "createdAt": "2026-05-01T00:00:00Z",
    "updatedAt": "2026-05-01T03:14:22Z"
  },
  "error": null,
  "meta": { "requestId": "req_01HX...", "timestamp": "2026-05-13T10:42:00Z" }
}

PDF / HTML

GET /v1/payment/invoices/:id/pdf
GET /v1/payment/invoices/:id/html

Both endpoints return the file directly (PDF binary or HTML body). Use pdf to email, html to embed in an iframe or dashboard.

CSV export

GET /v1/payment/invoices/export.csv

Same filters as list. Streams a CSV of one row per invoice with columns id, number, status, customerEmail, amount, currency, issuedAt, paidAt. No pagination — the streaming response is bounded by the filter window.

The invoice object

Field Type Nullable Description
id string no inv_ + ULID.
accountId string no Workspace.
customerId string yes Bill-to customer.
subscriptionId string yes Source subscription (when applicable).
number string no Human-readable invoice number.
status enum no draft / open / paid / uncollectible / void.
amount integer no Total, smallest-unit.
currency string no ISO 4217.
subtotal integer no Pre-tax.
taxAmount integer no Tax component.
lineItems array no [{ description, quantity, unitAmount, amount }].
issuedAt string (ISO 8601) no When the invoice was generated.
dueAt string (ISO 8601) yes Payment-deadline.
paidAt string (ISO 8601) yes Payment-settlement time.
voidedAt string (ISO 8601) yes Void time.
hostedUrl string yes Buyer-facing payment page (Plugipay-hosted).
pdfUrl string no The PDF endpoint URL.
metadata object no Free-form.
createdAt / updatedAt string no Timestamps.

Events

Event type Fires on
invoice.created Invoice transitions out of draft to open.
invoice.finalized (Plugipay mode) draft → open finalisation step.
invoice.paid Invoice settles.
invoice.payment_failed A charge attempt against the invoice failed.
invoice.void Invoice was voided.

Invoice events aren't emitted by Storlaunch's outbox. They fire from Plugipay's outbox when the module is on. Subscribe via your Plugipay endpoint or via the cross-product unified endpoint Storlaunch maintains for you (see Webhooks). In legacy mode (no Plugipay module), invoice events are not currently emitted.

Next