# 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.

| Link | What it charges | Created via |
| --- | --- | --- |
| Invoice payment link (paylink) | One-off amount of a single invoice | Dashboard → Invoices, or `POST /v1/invoices` |
| Subscription link | Recurring price, subscribed by anyone who opens it | Dashboard → Subscription links, or `POST /v1/subscription_links` |

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.

```bash
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](/docs/api/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`

```bash
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
  }'
```

```json
{
  "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

```bash
# 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](/docs/api/events).

## Sandbox

Subscription links are **live-only**. With an `sk_test_` key the endpoints return an error — test recurring billing with [Subscriptions](/docs/api/subscriptions) in the sandbox instead.