Invoices

Create, send, void and reconcile invoices over the API — or from the dashboard.

Invoices

Invoices can be created in the dashboard (/dashboard/invoices/new) or over the API. Every invoice produces a hosted payment page at https://payments.southbill.com/i/{token} that anyone with the link can pay — no key needed on the customer side.

Base URL https://api.southbill.com · Auth Authorization: Bearer sk_live_… · Scopes invoices:read, invoices:write.

Endpoints

Create and send

curl https://api.southbill.com/v1/invoices \
  -H "Authorization: Bearer $SOUTHBILL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv_9781" \
  -d '{
    "customer": "cus_9f2c41a0b7e34d9a8c15be22",
    "currency": "eur",
    "due_date": "2026-09-30",
    "memo": "Thanks for your business.",
    "auto_send": true,
    "line_items": [
      { "description": "Implementation, September", "quantity": 1, "unit_amount": 120000, "tax_rate": 20 },
      { "description": "Support retainer", "quantity": 3, "unit_amount": 15000, "tax_rate": 20 }
    ]
  }'

const invoice = await fetch("https://api.southbill.com/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOUTHBILL_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "inv_9781",
  },
  body: JSON.stringify({
    customer: "cus_9f2c41a0b7e34d9a8c15be22",
    currency: "eur",
    due_date: "2026-09-30",
    auto_send: true,
    line_items: [
      { description: "Implementation, September", quantity: 1, unit_amount: 120000, tax_rate: 20 },
    ],
  }),
}).then((r) => r.json());

console.log(invoice.hosted_invoice_url);

import os, requests

invoice = requests.post(
    "https://api.southbill.com/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['SOUTHBILL_SECRET_KEY']}",
        "Idempotency-Key": "inv_9781",
    },
    json={
        "customer": "cus_9f2c41a0b7e34d9a8c15be22",
        "currency": "eur",
        "auto_send": True,
        "line_items": [
            {"description": "Implementation, September", "quantity": 1, "unit_amount": 120000, "tax_rate": 20}
        ],
    },
    timeout=30,
).json()

print(invoice["hosted_invoice_url"])

<?php
$ch = curl_init("https://api.southbill.com/v1/invoices");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SOUTHBILL_SECRET_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: inv_9781",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "customer"   => "cus_9f2c41a0b7e34d9a8c15be22",
    "currency"   => "eur",
    "auto_send"  => true,
    "line_items" => [[
      "description" => "Implementation, September",
      "quantity"    => 1,
      "unit_amount" => 120000,
      "tax_rate"    => 20,
    ]],
  ]),
]);
$invoice = json_decode(curl_exec($ch), true);

Response:

{
  "id": "inv_01J…",
  "object": "invoice",
  "livemode": true,
  "number": "SPK-INV-2026-0184",
  "status": "open",
  "currency": "eur",
  "subtotal": 165000,
  "tax": 33000,
  "total": 198000,
  "customer": "cus_9f2c41a0b7e34d9a8c15be22",
  "customer_email": "jane@example.com",
  "due_date": "2026-09-30",
  "hosted_invoice_url": "https://payments.southbill.com/i/9f14c0…",
  "paid_at": null,
  "created": 1756000000,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "li_0",
        "object": "invoice_item",
        "description": "Implementation, September",
        "quantity": 1,
        "unit_amount": 120000,
        "tax_rate": 20,
        "amount": 120000
      }
    ]
  }
}

Request fields

Partial payments

A partial invoice is settled by several payments. Southbill keeps amount_paid and amount_due on the invoice, tracks each instalment separately and moves the invoice through open → partially_paid → paid. Read the plan with GET /v1/invoices/{id}/installments:

{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "…", "sequence": 1, "amount": 66000, "amount_paid": 66000, "currency": "eur", "due_date": "2026-10-01", "status": "paid" },
    { "id": "…", "sequence": 2, "amount": 66000, "amount_paid": 0, "currency": "eur", "due_date": "2026-11-01", "status": "open" }
  ]
}

GET /v1/invoices/{id}/payments returns each booked payment (source: "stripe" for online payments, source: "manual" for payments recorded out of band) with amount, amount_refunded, status and paid_at. A refund on a paid partial invoice moves it back to partially_paid.

Amounts are integers in the smallest currency unit — 120000 = 1 200.00 EUR. Totals are computed server-side from the line items; you cannot set total directly.

Lifecycle

draft ──send──► open ──pays in full──────────────► paid
  │              │
  │              ├──pays part (partial/open)──► partially_paid ──rest paid──► paid
  │              ├──mark_paid──────────────────► paid
  └──void────────┴──void────────────────────────► void

A refund on a paid invoice with an outstanding balance returns it to partially_paid.

Webhooks

Every one of these is also stored in the Events log, so you can replay after downtime.

Rate limits: 300 reads/min and 60 writes/min per key. All writes accept Idempotency-Key.