Subscriptions

Recurring billing on your Southbill account

Subscriptions

Create recurring subscriptions for customers using a recurring price from your catalog. Subscriptions run on your connected Southbill account; Southbill deducts the platform fee automatically from each renewal invoice.

Base URL: https://api.southbill.com/v1 Auth: Authorization: Bearer sk_live_…

Prerequisites

1. Create a product and a recurring price (see Products and Prices — prices are created with POST /v1/products/{product_id}/prices; there is no top-level /v1/prices endpoint).
2. The price must have recurring.interval set (day, week, month, year).

Create a subscription

POST /v1/subscriptions

curl -X POST https://api.southbill.com/v1/subscriptions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub_20260718_001" \
  -d '{
    "price_id": "price_1Tu…",
    "customer_name":  "Jane Doe",
    "customer_email": "jane@example.com",
    "quantity": 1,
    "trial_days": 14,
    "metadata": { "plan": "pro" }
  }'

Body

Response

{
  "id": "sub_1Tu…",
  "object": "subscription",
  "status": "incomplete",
  "customer": "cus_1Tu…",
  "price_id": "price_1Tu…",
  "quantity": 1,
  "currency": "EUR",
  "amount": 1990,
  "current_period_start": 1735689600,
  "current_period_end":   1738368000,
  "latest_invoice": "in_1Tu…",
  "client_secret": "pi_1Tu…_secret_…",
  "trial_end": null,
  "created": 1735689600
}

customer in the response is your Southbill customer id when you passed one; otherwise it is the id created for this subscription. Processor ids are never returned here.

A subscription.created event is emitted immediately when the subscription is created, before the first payment.

Completing an incomplete subscription

The subscription starts as incomplete. There is no /v1/payment_intents endpoint — confirm the returned client_secret in the browser:

<script src="https://southbill.com/southbill.js"></script>
<script>
  const sb = southbill("pk_live_…");
  await sb.confirmPayment({
    client_secret: "pi_1Tu…_secret_…",
    return_url: "https://your-shop.com/thanks"
  });
</script>

intent_type tells you what the secret belongs to: payment (first invoice is charged now) or setup (trial — only the card is stored). After confirmation the status becomes active (or trialing) and subscription.updated plus the invoice.* events fire.

Embedded (on-site) subscription checkout

The endpoint above returns a client_secret for a custom SDK confirmation. If you instead want Southbill's hosted card form rendered inline on your page, create the session through the Checkout Sessions endpoint with mode: "subscription":

curl -X POST https://api.southbill.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "subscription",
    "line_items": [{ "price_id": "price_1Tu…" }],
    "customer_email": "jane@example.com",
    "success_url": "https://your-shop.com/thanks",
    "cancel_url":  "https://your-shop.com/cart"
  }'

The response returns checkout_url, embed_url and client_secret for the same session. To keep it on your site, mount embed_url in an iframe — or southbill.checkout({ mode: 'embed', mount: '#southbill-checkout' }). To redirect the buyer away, send them to checkout_url.

There is no ui_mode field — every session is always both hosted and embeddable. For subscriptions the behaviour is identical to one-time: redirect = hosted, embed_url = on-site.

Confirm the subscription server-side via the invoice.paid / subscription.created webhook rather than the browser event.

Retrieve

GET /v1/subscriptions/{id}

List

GET /v1/subscriptions?limit=20

Returns up to 100 subscriptions ordered by creation date (newest first).

Cancel

POST /v1/subscriptions/{id}/cancel

curl -X POST https://api.southbill.com/v1/subscriptions/sub_1Tu…/cancel \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel_sub_1Tu_20260718" \
  -d '{ "at_period_end": true }'

Status model

Fees

Recurring invoices carry a platform fee computed from your plan and payment method. Fees are settled in EUR and deducted per invoice — same rules as one-off Checkout Sessions. See Fees, currency & minimum amounts.

Idempotency

Send Idempotency-Key: <your-key> on POST /v1/subscriptions and POST /v1/subscriptions/{id}/cancel. Keys are scoped to (merchant_id, method, path) and expire after 24 hours.

• Same key + same body → original response replayed verbatim.
• Same key + different body → 409 Conflict with type: "idempotency_error", code: "idempotency_key_reused". See Error reference.

Errors

Webhooks

Listen for these events (see Event reference for payloads):

• subscription.created / updated / deleted
• customer.subscription.trial_will_end — fires 3 days before the trial ends
• invoice.payment_succeeded — renewal charged
• invoice.payment_failed — dunning stage advanced (notice → warning → final)