---
title: "Open a Stripe Billing Portal session"
method: POST
path: "/billing/portal"
tags: ["Billing"]
---

# Open a Stripe Billing Portal session

`POST /billing/portal`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/billing/portal`
- Auth: HTTP bearer

Opens the Stripe Billing Portal (invoices, the card, cancellation) for the caller's workspace. Requires `billing:manage` (owners and admins) and a Stripe customer (a completed checkout). `flow` deep-links into one task: `payment_method_update` (the "update your card" link of a payment failure email) or `subscription_cancel`.

## Request body

- object
  - `return_url` string, uri, required
  - `flow` 'payment_method_update' | 'subscription_cancel'

## Response `200`

Portal session

- object
  - `id` string
  - `url` string, uri

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)