Payment links & subscription links

No-code hosted pages for one-off and recurring payments

Payment links & subscription links

Southbill has two kinds of shareable payment pages. Neither requires a website or an integration.

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

Invoice payment links

Every invoice has a hosted payment page. Create the invoice, then share hosted_invoice_url — there is no separate link object.

curl -X POST https://api.southbill.com/v1/invoices \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "currency": "eur",
    "items": [{ "description": "Design retainer", "amount": 45000, "quantity": 1 }]
  }'

The response contains hosted_invoice_url. The page collects the cardholder name and billing address, supports cards, wallets and the local methods enabled on your account, and may request 3-D Secure authentication based on Southbill's risk assessment. See Invoices for line items, due dates, partial payments and refunds.

Subscription links

A subscription link is a hosted page bound to one recurring price. Anyone who opens the URL can subscribe; each subscriber becomes a normal subscription on your account.

Scopes: subscriptions:read to list/retrieve, subscriptions:write to create, update or archive.

Create

POST /v1/subscription_links

curl -X POST https://api.southbill.com/v1/subscription_links \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sublink_20260920_001" \
  -d '{
    "price_id": "price_1A…",
    "headline": "Pro plan",
    "description": "Everything in Pro, billed monthly.",
    "cta_label": "subscribe_now",
    "collect_address": true
  }'

{
  "id": "…",
  "object": "subscription_link",
  "livemode": true,
  "slug": "pro-plan",
  "url": "https://payments.southbill.com/s/pro-plan",
  "active": true,
  "price_id": "price_1A…",
  "amount": 2900,
  "currency": "eur",
  "interval": "month",
  "interval_count": 1
}

Key fields:

• price_id — recurring Stripe price ID. Alternatively pass merchant_price_id (the Southbill price UUID).
• slug — lowercase letters, digits and hyphens, 3–48 chars. Derived from headline when omitted; a taken slug returns 409 slug_taken.
• quantity_mode — fixed (default, with fixed_quantity) or customer (buyer picks, up to max_quantity).
• trial_days_override — overrides the trial of the price, max 730 days.
• collect_address — collect a billing address on the page.
• cta_label — one of continue_to_payment, subscribe_now, subscribe, pay_subscription_now, subscribe_for_amount, start_free_trial, get_started, join_now, confirm_subscription.
• branding_mode — company_name or logo; show_product_image, custom_message and success_url (https) control the rest of the page.

List, retrieve, update, archive

# list (optionally filter by active)
curl "https://api.southbill.com/v1/subscription_links?active=true&limit=20" \
  -H "Authorization: Bearer sk_live_…"

# retrieve by id or slug
curl https://api.southbill.com/v1/subscription_links/pro-plan \
  -H "Authorization: Bearer sk_live_…"

# update (same fields as create, all optional; PATCH behaves identically)
curl -X POST https://api.southbill.com/v1/subscription_links/pro-plan \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "headline": "Pro plan (new)" }'

# archive — stops new subscribers, existing subscriptions keep running
curl -X POST https://api.southbill.com/v1/subscription_links/pro-plan/archive \
  -H "Authorization: Bearer sk_live_…"

Links created through the API appear in the dashboard under Subscription links, and vice versa — they are the same objects.

Events

Subscriptions started from a link emit the normal subscription and invoice events: subscription.created, invoice.payment_succeeded, payment_intent.succeeded. See Events & replay.

Sandbox

Subscription links are live-only. With an sk_test_ key the endpoints return an error — test recurring billing with Subscriptions in the sandbox instead.