---
title: "Open Billing Portal"
method: POST
path: "/v1/organizations/billing/portal"
tags: ["Organization Billing"]
---

# Open Billing Portal

`POST /v1/organizations/billing/portal`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/organizations/billing/portal`
- Auth: HTTP bearer

Open the Stripe customer billing portal.

This is the correct destination for a "Manage subscription" action: the
portal lets an existing customer update their card, view/download invoices,
and change or cancel their plan. It is NOT the same as POST /subscribe —
re-running /subscribe for an existing subscriber starts a brand-new checkout
instead of managing the current one.

Requires an existing Stripe customer. Orgs that have never started billing
have nothing to manage, so they get an actionable 400 pointing at /subscribe.

## Request body

- BillingPortalRequest: Request to open the Stripe customer billing portal.
  - `return_url` string, nullable: URL Stripe redirects back to when the customer leaves the portal

## Response `200`

Successful Response

- BillingPortalResponse: Response with the Stripe-hosted billing portal URL. The portal lets an existing customer update their card, view invoices, and change or cancel their subscription — distinct from /subscribe, which starts a NEW checkout (re-running checkout for an existing subscriber is wrong).
  - `portal_url` string, required: Stripe-hosted billing portal URL (redirect the user here)
  - `session_id` string, required: Stripe billing portal session ID

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/organizations/billing/portal/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)