Endpoints

Everything the App API exposes today.

The App API is how your app reads and writes the merchant's data. Paths below are relative to the base URL — /payments means https://api.southbill.com/v1/app/payments. Payments, payouts, invoices, subscriptions and analytics are read-only. The Store surface (products, prices, options, values, variants, files, orders) also supports writes with the products:write, files:write and orders:write scopes — no merchant secret key is needed, the installation's sbat_live_… / sbat_test_… token is enough. Unsupported methods return 405 method_not_allowed.

Write requests should send an Idempotency-Key header; a repeated key returns the original result instead of creating a second object.

Base URL: https://api.southbill.com/v1/app · Auth: Authorization: Bearer sbat_live_… (see Authentication).

Endpoints

Store write endpoints

Subscription links

Subscription links are only available on live installations; the merchant and store are always taken from the installation, never from the request body.

Ownership is always derived from the access token, never from ids in the body: an app can only touch the store it was installed on, in the environment of its token.

Field-by-field descriptions of every response are in Objects & fields.

Query parameters

Unknown query parameters are ignored, not rejected. There are no date-range filters in v1 — page by offset and stop at the first object older than your cursor.

Pagination

curl "https://api.southbill.com/v1/app/payments?limit=50&offset=100" \
  -H "Authorization: Bearer sbat_live_…"

async function* allPayments(accessToken) {
  for (let offset = 0; ; offset += 50) {
    const res = await fetch(
      `https://api.southbill.com/v1/app/payments?limit=50&offset=${offset}`,
      { headers: { Authorization: `Bearer ${accessToken}` } },
    );
    const page = await res.json();
    yield* page.data;
    if (!page.has_more) return;
  }
}

def all_payments(access_token):
    offset = 0
    while True:
        page = requests.get(
            "https://api.southbill.com/v1/app/payments",
            params={"limit": 50, "offset": offset},
            headers={"Authorization": f"Bearer {access_token}"},
            timeout=30,
        ).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        offset += 50

<?php
$offset = 0;
do {
    $ch = curl_init("https://api.southbill.com/v1/app/payments?limit=50&offset={$offset}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer {$accessToken}"],
    ]);
    $page = json_decode(curl_exec($ch), true);
    foreach ($page["data"] as $payment) {
        // handle $payment
    }
    $offset += 50;
} while ($page["has_more"]);

{ "object": "list", "data": [ … ], "has_more": true }

Lists are sorted newest first and carry no total count. Iterate until has_more is false. New objects arrive while you page, so for exports read the first page frequently rather than deep-paging a moving list.

Test vs live

The token decides the data source: a sandbox token reads your environment's simulated data, a live token reads the merchant's real data. Field names differ between the two — see the table at the top of Objects & fields.

Amounts and timestamps

Amounts are integer minor units with a lowercase ISO currency: { "amount": 2500, "currency": "eur" } is €25.00. Never use floats. Timestamps are unix seconds (UTC integers) — including arrival_date, issue_date and due_date, which are midnight UTC of the respective day. See Objects & fields.

Errors

{ "error": { "type": "insufficient_scope", "message": "Missing required scope: payments:read" } }

See Error & status codes.