> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a portal session

> Creates a new customer portal session, returning a token and URL to redirect the customer to their billing portal.

<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json post /portal/session/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Transactions
    description: >-
      Charges, refunds, disputes, and other financial movements for the
      authenticated organization.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
  - name: Orders
    description: Completed and resolved orders for the authenticated organization.
  - name: Order Events
    description: Timeline events for a specific order.
  - name: Webhooks
    description: Delivery logs for webhook events sent to your configured endpoints.
  - name: Checkout Sessions
    description: Merchant-side view of checkout sessions created by customers.
  - name: Checkout Session Events
    description: Timeline events for a specific checkout session.
paths:
  /portal/session/:
    post:
      tags:
        - Portal
      summary: Create a portal session
      description: >-
        Creates a new customer portal session, returning a token and URL to
        redirect the customer to their billing portal.
      operationId: createPortalSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePortalSessionRequest'
      responses:
        '200':
          description: Portal Session Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePortalSessionResponse'
              example:
                token: >-
                  cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275
                email: geo@example.com
                customerPortalUrl: https://www.kelviq.com/portal/aphelo/
        '401':
          description: Unauthorized — missing or invalid API key
      security:
        - bearerAuth: []
components:
  schemas:
    CreatePortalSessionRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          description: >-
            The unique identifier of the customer for whom the portal session is
            being created.
          example: cust_789
    CreatePortalSessionResponse:
      type: object
      properties:
        token:
          type: string
          description: The session token for authenticating the customer portal session.
          example: >-
            cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275
        email:
          type: string
          format: email
          description: The email address of the customer.
          example: geo@example.com
        customerPortalUrl:
          type: string
          format: url
          description: >-
            The `customerPortalUrl` field contains the customer’s billing portal
            URL. This URL alone does not authenticate the customer session. To
            generate a signed portal link, append the `token` value from the
            same response as a query parameter using the following format:


            `${customerPortalUrl}?token=${token}`


            Example response:


            ```json

            {
              "token": "cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275",
              "email": "geo@example.com",
              "customerPortalUrl": "https://www.kelviq.com/portal/aphelo/"
            }

            ```


            Generated signed portal link:


            `https://www.kelviq.com/portal/aphelo/?token=cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275`


            The generated URL can be safely shared with the customer to provide
            direct access to their billing portal session.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````