Create a portal session

In this guide you’ll create a customer portal session for a customer and redirect them to it. By the end, a customer who clicks “Manage subscription” in your app lands in the portal already signed in, with no second login. Create a session at the moment the customer asks for it. Sessions are short-lived, so a URL minted ahead of time and stored is usually dead by the time it’s used. Always mint a fresh one per request.

Prerequisites

An API key with the customers:write scope. See Permissions.
The customer’s customer_id, prefixed cust_. See Manage customers.

Steps

Create the session

Call POST /v1/customers/{customer_id}/portal-sessions. There is no request body: what the customer can do in the portal comes from your portal settings, not from this call.

curl -X POST https://sandbox-api.bachs.io/v1/customers/cust_1a2b3c4d5e6f/portal-sessions \
  -H "Authorization: Bearer $BACHS_API_KEY"

const session = await bachs.customerPortal.createSession("cust_1a2b3c4d5e6f");

session = bachs.customer_portal.create_session("cust_1a2b3c4d5e6f")

{
  "id": "psn_9f2c4a7b1d3e",
  "url": "https://portal.bachs.io/s/6Yc0nQpR2vX1sK7fLbA9tE"
}

Field	Type	Description
`id`	string	The session identifier, prefixed `psn_`. Use it to correlate a session with your own logs. It is not a credential and cannot be exchanged for access.
`url`	string	The URL that opens the portal as this customer. It carries the session credential, so it works on any device.

Redirect the customer

Send the customer to url and nothing else.

// customerId belongs to the signed-in user, looked up on your server
const { url } = await bachs.customerPortal.createSession(customerId);
return Response.redirect(url, 303);

# customer_id belongs to the signed-in user, looked up on your server
session = bachs.customer_portal.create_session(customer_id)
return redirect(session.url, code=303)  # Flask; use your framework's redirect

const res = await fetch(
  `https://sandbox-api.bachs.io/v1/customers/${customerId}/portal-sessions`,
  { method: "POST", headers: { Authorization: `Bearer ${process.env.BACHS_API_KEY}` } }
);

const { url } = await res.json();
return Response.redirect(url, 303);

The URL signs the customer in, so don’t log it or store it.

React to what they do

The customer’s session is now theirs. Anything they change emits the same webhook as the equivalent API call: customer.subscription.updated on a plan change or scheduled cancellation, customer.subscription.deleted on a cancellation, invoice.paid when a recovery payment succeeds.There is no redirect back to you unless you’ve set a return URL in your portal settings, and the customer may close the tab at any point. Treat webhooks as the only reliable signal that something changed.

Errors

Status	`error_code`	Cause	Resolution
`401`	`UNAUTHORIZED`	Missing or invalid API key.	Send a valid key in the `Authorization` header. See Authentication.
`403`	`FORBIDDEN`	The key lacks the `customers:write` scope.	Issue a key with the scope, or add it to the existing key.
`404`	`NOT_FOUND`	No customer with that ID on your account.	Check the `customer_id`, including that it isn’t a customer from your other environment. Sandbox and live customers are separate.
`429`	`TOO_MANY_REQUESTS`	You’ve exceeded your rate limit.	Back off and retry. No session was created.
`500`	`INTERNAL_SERVER_ERROR`	Unexpected failure.	Retry once. If it persists, contact support with the response body.
`503`	`SERVICE_UNAVAILABLE`	The portal can’t issue sessions right now.	Retry once. If it keeps failing, the portal isn’t configured for this environment, so contact support rather than retrying in a loop.

Next steps

Customer portal covers what the portal does and how to configure what customers can change.
Manage customers shows how to create and look up the customer_id this endpoint needs.
Webhooks explains how to receive the events a portal action emits.

Get Started

Payouts

Virtual accounts

Products & pricing

Subscriptions

Customer portal

Payments

Dashboard

Developer Portal

SDKs

CLI

For You and Your Customers

Create a portal session

Prerequisites

Steps

Errors

Next steps

​Prerequisites

​Steps

​Errors

​Next steps

Prerequisites

Steps

Errors

Next steps