> ## Documentation Index > Fetch the complete documentation index at: https://alguna.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a customer portal session > Creates a short-lived customer portal session and returns a signed URL the customer can use to access their billing portal. Sessions are single-use per token and expire after a short TTL. ## OpenAPI ````yaml /api-reference/v2/specs/2026-04-01.json post /customer-portal-sessions openapi: 3.1.0 info: title: Alguna Public API version: '2026-04-01' servers: - url: https://api.alguna.io security: - bearerAuth: [] tags: - name: Billing Events and Metrics - name: Credit Notes - name: Credits - name: Customer Portal Sessions - name: Customers - name: Insights - name: Invoices - name: Payments - name: Plans - name: Product Bundles - name: Products - name: Refunds - name: Revenue Schedules - name: Subscription Changes - name: Subscription Versions - name: Subscriptions - name: Wallet Grants - name: Wallets paths: /customer-portal-sessions: post: tags: - Customer Portal Sessions summary: Create a customer portal session description: >- Creates a short-lived customer portal session and returns a signed URL the customer can use to access their billing portal. Sessions are single-use per token and expire after a short TTL. operationId: create-customer-portal-session parameters: - in: header name: Alguna-Version required: true schema: enum: - '2026-04-01' type: string - in: header name: Idempotency-Key schema: description: >- A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation. example: ik_a1b2c3d4e5f6 maxLength: 255 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCustomerPortalSessionRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerPortalSessionResponse' description: Success headers: Idempotency-Key: description: Echo of the idempotency key provided in the request schema: type: string Idempotent-Replayed: description: >- Whether this response was replayed from a previous request (true) or freshly executed (false) schema: type: boolean '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Conflict — a request with this idempotency key is currently being processed '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error components: schemas: CreateCustomerPortalSessionRequest: properties: billing_details_settings: allOf: - $ref: '#/components/schemas/BillingDetailsSettingsRequest' description: >- Settings for the billing details section of the customer portal. When omitted, the organization's defaults apply. nullable: true customer_alias: description: >- Alternative identifier (external ID) for the customer. Used when customer_id is not provided. example: ext_39003209203023902 nullable: true type: string customer_id: description: >- Customer ID the portal session is for. Either customer_id or customer_alias must be provided. example: cust_abc123 nullable: true type: string invoice_list_settings: allOf: - $ref: '#/components/schemas/InvoiceListSettingsRequest' description: >- Settings for the invoice list section of the customer portal. When omitted, the organization's defaults apply. nullable: true plan_overview_settings: allOf: - $ref: '#/components/schemas/PlanOverviewSettingsRequest' description: >- Settings for the plan overview section of the customer portal. When omitted, the organization's defaults apply. nullable: true type: object CustomerPortalSessionResponse: properties: created_at: description: When the session was created example: '2026-04-01T10:00:00Z' format: date-time type: string customer_id: description: Customer ID the session was issued for example: cust_abc123 type: string expires_at: description: >- When the session URL will expire. After this, the customer must be redirected to a freshly created session. example: '2026-04-01T11:00:00Z' format: date-time type: string id: description: Unique identifier for the session example: a8B3kLmQ type: string url: description: Hosted customer portal URL example: https://portal.alguna.io/hs/abc123 type: string required: - created_at - customer_id - expires_at - id - url type: object ErrorResponse: properties: detail: type: string status: format: int64 type: integer required: - status - detail type: object BillingDetailsSettingsRequest: properties: allow_autopay_edit: description: >- Whether the customer can edit autopay settings. Falls back to the organization's default when omitted. nullable: true type: boolean show_section: description: >- Whether the billing details section is shown. Falls back to the organization's default when omitted. nullable: true type: boolean type: object InvoiceListSettingsRequest: properties: show_section: description: >- Whether the invoice list section is shown. Falls back to the organization's default when omitted. nullable: true type: boolean type: object PlanOverviewSettingsRequest: properties: allow_subscription_cancel: description: >- Whether the customer can cancel their subscription. Falls back to the organization's default when omitted. nullable: true type: boolean show_section: description: >- Whether the plan overview section is shown. Falls back to the organization's default when omitted. nullable: true type: boolean type: object securitySchemes: bearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http ````