Checkout and portal
Two surfaces your customers use directly, and neither needs them to have a login with you.
A checkout link sells a plan: a public URL a buyer opens, fills in, and subscribes through. A portal link is for someone who already is a customer: they see their subscriptions, invoices and wallet, and can do a controlled set of things without emailing you.
Checkout links
A link points at one plan and carries a slug, which is what appears in the URL. Everything else configures what the buyer is asked for.
What to collect
collect_address, collect_phone and collect_vat_id decide the form. Ask for
the least you need: an address is required to calculate tax correctly
for a business, and a VAT ID is what unlocks reverse charge, but a phone number
usually just costs you conversions.
What to assume
The default_* fields pre-set what the resulting subscription
is created with: billing timing, payment terms, preferred provider, wallet mode
and currency. A buyer never sees these; they decide what the subscription looks
like once it exists.
Consent
consent_config controls the agreement the buyer is shown and must accept.
Whatever it records is attached to the resulting subscription, which is what you
will want when somebody later asks what exactly was agreed.
The customer portal
The portal is the same idea from the other end: an existing customer, a tokenised link, no account.
POST /v1/customers/{id}/portal-links mints the link. /v1/portal-settings
controls what the portal exposes, org-wide, in two groups.
What is visible
show_subscriptions, show_invoices, show_wallets, show_payment_methods,
show_billing_settings.
What is permitted
allow_invoice_pay, allow_wallet_topup, allow_add_payment_method,
allow_cancel_subscription.
The split matters. Showing invoices without allowing payment is a perfectly reasonable read-only portal. Allowing cancellation is the one to think about hardest, because it is the only setting here that loses you revenue without a conversation.
These settings are organisation-wide
Portal settings are not per customer. Turning on allow_cancel_subscription
turns it on for everybody who has a portal link.
Both links are public
A checkout link and a portal link are both URLs that work without authentication. That is the point, and it has consequences:
- Treat the link as the credential. Anyone holding it has the access it grants. A portal link shows real billing data.
- Send them to the person, not to a channel. A link in a shared inbox is a link everyone in that inbox holds.
- They can be replaced. If one is exposed, mint a new link and the old one stops being useful.
The same reasoning applies to a quote's public token, which is why it has an explicit rotate endpoint.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Checkout Links | /v1/checkout-links |
| Slug | slug, the public URL segment |
| Collect address / phone / VAT | collect_address, collect_phone, collect_vat_id |
| portal visibility toggles | show_* on /v1/portal-settings |
| portal permission toggles | allow_* on /v1/portal-settings |
| a customer's portal link | POST /customers/{id}/portal-links |
Where these go next
- Checkout creates a subscription using the link's defaults, exactly as if you had created it yourself.
- The portal reduces support load, but only for what you permit; everything else still comes to you.
- Quotes are the third public surface, for deals that need a signature rather than a checkout.
Reference
| Topic | When you need it |
|---|---|
| Plans | What a checkout link sells |
| Quotes | The signature-based alternative to checkout |
| Wallets | What allow_wallet_topup exposes |
| Checkout links API | Every field on a link |