---
title: "Create Portal Session"
method: POST
path: "/api/billing/portal"
tags: ["billing"]
---

# Create Portal Session

`POST /api/billing/portal`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/billing/portal`
- Auth: API key in header `X-API-Key`

Create a billing portal session for the calling key.

Requires the `X-API-Key` header — the calling key's subscription is
the one that will be managed. The portal lets the user update their
payment method, view invoices, and cancel their subscription.
Requires the key to have an associated billing customer (i.e. has
paid at least once).

## Request body

- PortalRequest: Request body for creating a billing portal session. Authentication is via the `X-API-Key` header. The `api_key` body field is retained for backwards compat; if provided it must match the header value, otherwise the request is rejected.
  - `api_key` string, nullable: Deprecated — set the `X-API-Key` header instead. If provided here it must match the header value.

## Response `200`

Billing portal session URL

- PortalResponse: Response with a billing portal URL.
  - `portal_url` string, required: URL of the billing portal session

## Other responses

- `400`: Key has no active paid subscription
- `401`: Missing or invalid API key
- `403`: Body api_key does not match X-API-Key header
- `404`: API key not found
- `422`: Validation Error
- `503`: Billing portal not configured or not enabled

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)