Customer portal
The Customer portal entity in Billing.
The Customer portal is a hosted, white-label page where a customer can update payment methods, change plans, view invoices, and cancel subscriptions without leaving the merchant brand. There are two pieces: the portal config (customer-portal-config) — a per-merchant policy for what's enabled and how cancellations behave — and the access flow (customer-portal/access/*) — magic-link-based authentication that mints a session for one specific customer.
Lifecycle
- Configure the portal via
PATCH /customer-portal-config— toggle features (payment_methods_enabled,subscriptions_enabled,cancellations_enabled), pickcancellation_mode(immediatelyorend_of_period), setallow_plan_switch, restrictsubscription_product_ids, and supply areturn_url. - Request a link by calling
POST /customer-portal/access/request-linkwith the customer'semail,company_id, and adestination(home,payment_methods, orbilling_information). The platform emails the customer a magic link. - Customer clicks the link, which lands on the hosted portal and calls
POST /customer-portal/access/consumeto exchange the token for a portal session. - In-portal actions — payment-method add/remove, subscription cancel, plan switch, invoice download — all execute against the portal-scoped session, not your API key.
- Customer signs out or the session expires; sign-out is
POST /customer-portal/access/sign-out.
Relationships
The portal acts on the same Customer, Subscription, and Invoice records as the merchant API. Cancellations applied through the portal honor cancellation_mode and cancellation_proration_enabled, and may attach a retention_coupon_id automatically if configured. The portal is also the recommended payment_failed_custom_link_url target for Dunning config so customers can fix failed payments themselves.
Fields that matter
payment_methods_enabled+accepted_payment_methods(string[]) — gate which instruments customers can add (e.g. card, bank account) and whether the section appears at all.subscriptions_enabled+allow_plan_switch+allow_quantity_updates— control the self-serve subscription management surface; restrict the catalog withsubscription_product_ids.cancellations_enabled+cancellation_mode(immediately|end_of_period) +cancellation_proration_enabled— define the cancel UX.cancellation_reasons_enabled+cancellation_reasons(string[]) collect a structured reason;retention_coupon_idoffers a discount during the cancel flow.subscription_proration_behavior(none|prorate|full_difference) +subscription_charge_timing(immediately|period_end) — billing semantics for plan changes initiated from the portal.return_url(string | null) — where the portal sends the customer when they exit; used by the post-cancellation and post-update flows.portal_header+custom_domain_id— branding overrides for the hosted page.