---
title: "Create a customer self-service portal session"
method: POST
path: "/api/v1/customer-portal/sessions"
tags: ["Billing"]
---

# Create a customer self-service portal session

`POST /api/v1/customer-portal/sessions`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/customer-portal/sessions`
- Auth: API key in header `x-api-key`

Returns a single-use URL valid for one hour. Open it in the customer's browser; it shows their subscriptions, payment history and receipts, and lets them cancel, update the card or pay what is outstanding as your portal settings allow.

## Headers

- `Idempotency-Key` string

## Request body

- CustomerPortalSessionRequest
  - `customerId` string, required
  - `returnUrl` string, uri, required: Absolute https URL the portal's back link goes to.
  - `locale` 'en' | 'de'

## Response `200`

Portal session created

- CustomerPortalSession
  - `id` string, required
  - `object` 'billing_portal_session', required
  - `livemode` boolean
  - `createdAt` string, date-time
  - `customerId` string, required
  - `url` string, uri, required
  - `returnUrl` string, uri, required
  - `expiresAt` string, date-time, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)