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

# Customer Portal Session

> Create a new customer portal session for billing management



## OpenAPI

````yaml POST /billing/session
openapi: 3.1.0
info:
  title: Clink API
  description: >-
    Official API documentation for Clink's payment processing platform. This API
    enables merchants to create and manage payment sessions, handle
    subscriptions, and process transactions.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com/api/
security:
  - ApiKeyAuth: []
paths:
  /billing/session:
    post:
      description: Create a new customer portal session for billing management
      parameters:
        - $ref: '#/components/parameters/TimestampHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPortalCreateReq'
            examples:
              example:
                summary: Create a customer portal session
                value:
                  customerId: cus_xxxxx
              customSubscriptionUpgrade:
                summary: >-
                  Create a session with custom subscription upgrade and
                  downgrade products
                value:
                  customerId: cus_xxxxx
                  subscriptionUpdateProductIds:
                    - prd_001
                    - prd_002
      responses:
        '200':
          description: Customer portal session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPortalCreateRes'
components:
  parameters:
    TimestampHeader:
      name: X-Timestamp
      in: header
      required: true
      description: >-
        Current timestamp in milliseconds since Unix epoch (required for request
        signing)
      schema:
        type: string
        example: '1783513683000'
  schemas:
    CustomerPortalCreateReq:
      description: Parameters required to initialize a customer portal session
      required:
        - customerId
      type: object
      properties:
        customerId:
          type: string
          description: Existing customer's unique identifier
        returnUrl:
          type: string
          description: Redirect URL when customer click on 'Return to Merchant'
        subscriptionUpdateProductIds:
          type: array
          description: >-
            Product IDs allowed for subscription upgrades or downgrades in this
            customer portal session. When omitted or empty, this session does
            not restrict eligible products. Blank or invalid product IDs are
            rejected.
          items:
            type: string
            example: prd_001
          example:
            - prd_001
            - prd_002
    CustomerPortalCreateRes:
      type: object
      description: Response object returned when creating a new checkout session
      properties:
        code:
          type: integer
          description: >-
            HTTP status code indicating the request result (200 for success, 4xx
            for client errors, 5xx for server errors)
          format: int32
          example: 200
        msg:
          type: string
          description: >-
            Human-readable message describing the result ('success' for
            successful operations, error details for failures)
          example: success
        data:
          $ref: '#/components/schemas/CustomerPortalSessionVo'
          description: Customer Portal session details when successfully created
    CustomerPortalSessionVo:
      type: object
      properties:
        url:
          type: string
          description: The magic link for customer to access the portal
          example: https://uat-portal.clinkbill.com/session/eyJ0eXAiOffsssxxxxxx
        expiresAt:
          type: integer
          description: Link expiry time
          format: int64
          example: 1755152165726
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your secret API key obtained from the Clink dashboard (Developers
        section)

````