Billing portal

The billing portal is a self-service page where your customers manage their subscriptions themselves: renew, change plans, cancel/resume, and view their payment history. The portal and every email it sends carry your brand (name, logo, colors).

The portal requires no Byl account or password — access is granted via temporary session links. Every link expires after a set time, so a leaked link poses no risk.

How portal links reach the customer

There are three paths:

Path	Description
Byl, automatically	Whenever a subscription is created, a renewal is approaching, or a subscription is canceled, Byl emails the customer a portal link. The link stays valid long enough for that action.
From your application	When a signed-in user should reach the portal from a "My subscription" button or similar, create a session with the API below and redirect them to its URL.
In the dashboard	During support (chat, phone), use the Billing portal → Generate link button on the customer detail page to create a link valid for 24 hours and hand it to the customer.

TIP

A customer who opens an expired link is offered the option, right on the portal, to have a fresh link sent to their registered email — a link never fully "dies".

In most cases Byl's automatic emails are enough, so no extra work is required on your side. The session API is only needed when you want to grant access from inside your own application.

Create a session

POST /v1/projects/:project_id/billing-portal/sessions

Parameter	Type	Required	Description
customer_id	Number	true	Customer ID.

A session is valid for 30 minutes after creation. Create a fresh session each time the customer enters the portal — there is no need to store and reuse session URLs.

WARNING

A session link is itself an access credential, so create it only after you have authenticated the user. Send the session-creation request from your server, not from the customer's browser — otherwise your API token would be exposed to the customer.

Example request

BYL_PROJECT_ID="your project ID"
BYL_TOKEN="your API token"

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/billing-portal/sessions \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "customer_id": 12
      }'

Example response (201 Created)

{
  "data": {
    "url": "https://byl.mn/h/billing-portal/Yi7smBukXN3GbRBxTslkMCeDj10CJtqlYi7smBukXN3GbRBxTslkMCeDj10CJtql",
    "expires_at": "2026-07-23T04:40:00.000000Z"
  }
}

Typical flow

User is signed in to your app
  │ clicks "My subscription"
  ▼
Your server calls POST /billing-portal/sessions
  │ the response contains a url
  ▼
Redirect the user to the url

What's in the portal

The portal shows all of the customer's subscriptions in one place:

Action	Description
View status	Plan, price, status, access expiry date, days remaining
Renew	Choose how many periods to renew (monthly plans: 1–12 months, yearly: 1–3 years) and pay via checkout
Change plan	Choose from the project's other recurring prices; the credit for remaining days is deducted from the new total
Cancel / resume	Request cancellation, or reverse it before the period ends
Resubscribe	Start a canceled subscription again
Payment history	Payments from previous billing periods

Actions taken in the portal emit the usual webhook events, so nothing extra is needed to keep your system in sync.

In the future, invoices, receipts, and other customer-related items will also be brought into this portal.

Next steps

• Subscriptions — billing periods, renewals, plan changes
• Customers — get the customer_id required to create a session