Invoicing

Invoicing covers customers and one-off invoices. An invoice starts as a draft you can edit freely, becomes open when you finalize it, and is then payable through a hosted page the customer opens with a public token. For recurring charges, see Recurring. Subscriptions generate invoices through this same resource. Paths are relative to https://api.southpay.io/api/v2.

Authentication and scope

Reads require billing:read, writes require billing:write. Publishable keys are rejected. The two hosted-invoice endpoints are unauthenticated and identified by a public token instead. Idempotency keys are not used anywhere in billing. Retrying a create makes a second record.

Customers

Create a customer

POST /billing/customers. Scope billing:write. Fields go inside a required customer object.

string

required

Must be unique within the store.

string

object

Free-form address object stored as sent and rendered on invoices.

object

Arbitrary key-value pairs.

curl -X POST https://api.southpay.io/api/v2/billing/customers \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "[email protected]",
      "name": "Ana Ferreira",
      "billing_address": { "line1": "Rua Alpha 12", "city": "Lisboa", "country": "PT" }
    }
  }'

{
  "id": "3d4e5f60-7182-4930-a516-273849506172",
  "email": "[email protected]",
  "name": "Ana Ferreira",
  "phone": null,
  "billing_address": { "line1": "Rua Alpha 12", "city": "Lisboa", "country": "PT" },
  "metadata": {},
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z"
}

A duplicate email returns 409 {"error": "A customer with this email already exists"}.

List customers

GET /billing/customers. Scope billing:read. Active customers only, newest first.

string

Case-insensitive substring match on email or name.

integer

default:"1"

integer

default:"25"

Between 1 and 100.

Response 200

{
  "data": [ { "id": "3d4e5f60-…", "email": "[email protected]", "name": "Ana Ferreira", "…": "…" } ],
  "meta": { "total": 1, "page": 1, "per_page": 25, "total_pages": 1 }
}

Retrieve, update and delete

GET /billing/customers/{id}. Scope billing:read. PATCH /billing/customers/{id}. Scope billing:write. Accepts the same fields as create. Returns 200. DELETE /billing/customers/{id}. Scope billing:write. Returns 204 with no body.

Deleting a customer is a soft delete. The record stops appearing in the list and cannot be used on new invoices, but existing invoices keep their customer_id and still resolve the embedded customer object. Nothing is destroyed, and the email is not freed for reuse.

An unknown id returns 404 {"error": "Customer not found"}.

Invoices

Create an invoice

POST /billing/invoices. Scope billing:write. Creates a draft. Fields go inside a required invoice object.

string

required

Must be an active customer in this store.

string

required

Fiat currency for the whole invoice.

object[]

Show line item properties

string

required

integer

required

integer

required

Minor units of currency.

string

ISO 8601 due date.

string

Override the auto-assigned invoice number. Must be unique in the store.

string

The customer’s purchase order reference.

string

amount or percent.

integer

Minor units when discount_type is amount; percentage points when it is percent.

integer

Tax rate in basis points. 2000 is 20%.

string

Shown on the invoice above the footer.

string

Shown at the bottom of the invoice.

object

curl -X POST https://api.southpay.io/api/v2/billing/invoices \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "customer_id": "3d4e5f60-7182-4930-a516-273849506172",
      "currency": "EUR",
      "due_at": "2026-06-11T00:00:00Z",
      "po_number": "PO-4471",
      "tax_rate_bps": 2300,
      "line_items": [
        { "description": "Consulting, May", "quantity": 12, "unit_amount_cents": 9000 }
      ]
    }
  }'

{
  "id": "5f607182-9304-4a51-b627-384950617283",
  "customer_id": "3d4e5f60-7182-4930-a516-273849506172",
  "subscription_id": null,
  "period_key": null,
  "number": 41,
  "formatted_number": "INV-0041",
  "custom_number": null,
  "po_number": "PO-4471",
  "status": "draft",
  "currency": "EUR",
  "public_token": null,
  "subtotal_cents": 108000,
  "discount_type": null,
  "discount_value": null,
  "discount_cents": 0,
  "tax_rate_bps": 2300,
  "tax_cents": 24840,
  "total_cents": 132840,
  "amount_paid_cents": 0,
  "due_at": "2026-06-11T00:00:00.000Z",
  "description": null,
  "notes": null,
  "footer": null,
  "metadata": {},
  "finalized_at": null,
  "voided_at": null,
  "paid_at": null,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z",
  "customer": { "id": "3d4e5f60-…", "email": "[email protected]", "name": "Ana Ferreira" },
  "line_items": [
    {
      "id": "60718293-04a5-4b62-9738-495061728394",
      "description": "Consulting, May",
      "quantity": 12,
      "unit_amount_cents": 9000,
      "amount_cents": 108000,
      "position": 0
    }
  ]
}

Totals always satisfy total_cents = subtotal_cents - discount_cents + tax_cents. Do not compute them yourself; read them back.

Response fields

string

required

draft, open, paid, void or uncollectible. See lifecycle.

integer

required

Sequential per store.

string

required

The display number. Reflects custom_number when one is set.

string | null

The token in the hosted invoice URL. Null while the invoice is a draft.

string | null

Set when the invoice was generated by a subscription cycle.

string | null

Identifies which billing cycle produced the invoice. Deduplicates cycles.

integer

required

How much has been received against this invoice.

object[]

Present on retrieve, create, update and the action endpoints. amount_cents is quantity * unit_amount_cents; position is the display order.

List invoices

GET /billing/invoices. Scope billing:read. Newest first.

string

draft, open, paid, void or uncollectible.

string

Only invoices generated by one subscription.

integer

default:"1"

integer

default:"25"

Between 1 and 100.

Returns the {data, meta} envelope.

Retrieve and update

GET /billing/invoices/{id}. Scope billing:read. Includes line_items. PATCH /billing/invoices/{id}. Scope billing:write. Draft only. Accepts currency, due_at, description, metadata, all the enhancement fields, and line_items. Sending line_items replaces the whole set. Editing an open invoice returns 422 {"error": "Only draft invoices can be edited"}.

Finalize

POST /billing/invoices/{id}/finalize. Scope billing:write. No body. Moves draft to open, stamps finalized_at, assigns public_token, and emits invoice.finalized. Line items and totals are locked from here.

Status	Body	Cause
`422`	`{"error": "Cannot finalize a open invoice"}`	Already finalized, or in a terminal state.
`422`	`{"error": "Invoice has no payable amount"}`	`total_cents` is zero or negative.

Send

POST /billing/invoices/{id}/send. Scope billing:write. No body. Emails the hosted invoice link to the customer. The invoice must be open and the customer must have an email.

Status	Body	Cause
`422`	`{"error": "Only finalized invoices can be sent"}`	Still a draft, or terminal.
`422`	`{"error": "Customer has no email"}`	Nothing to send to.

Void

POST /billing/invoices/{id}/void. Scope billing:write. No body. Cancels a draft or open invoice, stamps voided_at, and emits invoice.voided. Voiding an already-void invoice is a 200 no-op. A paid invoice returns 422 {"error": "Cannot void a paid invoice"}. Refund the underlying payment instead.

Mark uncollectible

POST /billing/invoices/{id}/mark_uncollectible. Scope billing:write. No body. Writes off an open invoice you have given up collecting. It stays on the books, unlike a void.

This endpoint never errors. Called on a draft, paid or void invoice it returns 200 with the invoice unchanged. A 200 is not confirmation that the status changed. Read status on the response.

Delete

DELETE /billing/invoices/{id}. Scope billing:write. Draft only, and a genuine hard delete: the row and its line items are removed. Returns 204 with no body. An open invoice returns 422 {"error": "Only draft invoices can be deleted"}. Void it instead.

Invoice lifecycle

Status	Terminal	Meaning
`draft`	No	Editable and deletable. Not visible to the customer.
`open`	No	Finalized and payable. Locked.
`paid`	Yes	Paid in full.
`void`	Yes	Canceled.
`uncollectible`	Yes	Written off.

Allowed transitions: draft to open or void; open to paid, void or uncollectible. Nothing leaves a terminal state. Three webhook events fire here: invoice.finalized, invoice.paid and invoice.voided. There is no event for a draft being created or for uncollectible. Billing events carry the full invoice object in data.object, unlike payment events, which carry a small envelope. Billing events also do not fan out to platform accounts.

Hosted invoice page

Two unauthenticated endpoints back the page the customer opens. They are keyed on public_token, not on the invoice id, and require no credential. Send the customer the URL and do not proxy these yourself. GET /billing/invoice/{token} returns the invoice as the customer sees it: public_token, number, formatted_number, po_number, status, currency, subtotal_cents, discount_cents, tax_cents, total_cents, due_at, description, notes, footer, amount_paid_cents, merchant_name, customer{name, email}, line_items[], and payment, which is a checkout object or null if no payment has been started. POST /billing/invoice/{token}/payment_intent creates the crypto payment intent for the invoice and returns the same body with payment populated. A draft invoice returns 404 {"error": "Invoice not found"} on both, since drafts have no token. A non-payable invoice returns 422 on the second.

Errors

Status	Body	Cause
`404`	`{"error": "Invoice not found"}`	Unknown id or token.
`404`	`{"error": "Customer not found"}`	Unknown customer id on a customer route.
`422`	`{"error": "Customer not found"}`	Unknown `customer_id` on invoice create. Note this is `422`, not `404`.
`422`	`{"error": "Customer is not active"}`	The customer was soft-deleted.
`422`	`{"error": "Invoice number is already taken"}`	Duplicate `custom_number`.
`409`	`{"error": "A customer with this email already exists"}`	Duplicate email.
`422`	`{"errors": ["Currency can't be blank"]}`	Model validation failure. Note the plural array envelope.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Authentication and scope

Customers

Create a customer

List customers

Retrieve, update and delete

Invoices

Create an invoice

Response fields

List invoices

Retrieve and update

Finalize

Send

Void

Mark uncollectible

Delete

Invoice lifecycle

Hosted invoice page

Errors

​Authentication and scope

​Customers

​Create a customer

​List customers

​Retrieve, update and delete

​Invoices

​Create an invoice

​Response fields

​List invoices

​Retrieve and update

​Finalize

​Send

​Void

​Mark uncollectible

​Delete

​Invoice lifecycle

​Hosted invoice page

​Errors

Authentication and scope

Customers

Create a customer

List customers

Retrieve, update and delete

Invoices

Create an invoice

Response fields

List invoices

Retrieve and update

Finalize

Send

Void

Mark uncollectible

Delete

Invoice lifecycle

Hosted invoice page

Errors