Invoices

How invoices work in Southbill, how customers pay them, and the roadmap for the invoice API.

Invoices

Invoices in Southbill are created in the merchant dashboard (/dashboard/invoices/new). Each invoice generates a public payment link that anyone with the link can pay — no API key needed on the customer side.

A public REST API for create / list / send invoice is on the roadmap. Today you can automate invoice payments through Checkout Sessions and use the dashboard for invoicing.

Anatomy

Field Description
number Auto-generated SPK-INV-YYYY-NNNN.
currency ISO code — locked to the currency of any product line-item you add.
line_items Free-form or imported from your Products catalog. Product-sourced items are locked to Southbill values (price, quantity, VAT, currency).
total_amount Sum incl. VAT. Minimum 2.50 in invoice currency (below that, PSP + Southbill fees can't be covered).
status draft → open → paid / void / uncollectible.
public_token Random token used in the customer-facing URL.

Customer payment flow

  1. Merchant creates the invoice and clicks Send — status becomes open, public_token is minted.
  2. Customer opens https://payments.southbill.com/i/{public_token} (link is emailed automatically).
  3. Opening the link starts a southbill-hosted payment for the invoice, which:
    • creates the payment against the merchant's Southbill account,
    • resolves enabled payment methods for the invoice currency (Klarna, iDEAL, Bancontact, etc. are filtered per currency),
    • applies the merchant's Southbill fees via the shared fee engine.
  4. On success the invoice is marked paid, a receipt is emailed and a invoice.paid webhook is delivered to your endpoints.

Adding products to an invoice

In the New invoice page, click Add from products → pick a product. Southbill will:

  • copy name, description, image, price, currency, VAT from your catalog;
  • lock those fields (marked "From product · locked to Southbill values");
  • lock the invoice currency to the product currency;
  • disable recurring products (recurring billing runs through the Subscriptions API, POST /v1/subscriptions).

Webhooks

Configure your endpoints in Dashboard → Developers → Webhooks.

Event When
invoice.finalized Invoice moves from draft to open (send).
invoice.paid Customer paid successfully.
invoice.payment_failed Payment attempt failed.
invoice.voided Merchant voided an open invoice.

Payload includes id, number, amount_due, amount_paid, currency, customer_email, customer_name, line_items[], metadata.

Fees & minimums

All fees are calculated in EUR (see Fees, currency & minimum amounts). Minimum invoice total is 2.50 in the invoice currency.