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

# Retrieve a checkout session

> Re-hydrate a signed session. An expired token returns 200 with `status=EXPIRED`.



## OpenAPI

````yaml /v3-beta/api-reference/openapi.yaml get /v3/checkout/sessions/{id}
openapi: 3.1.0
info:
  title: Suby.fi Merchant API
  version: 3.0.0-beta
  description: >
    The **v3** public merchant API for Suby.fi. RESTful (plural,
    resource-oriented

    endpoints under the `/v3` prefix). Authenticate every request

    with your secret API key in the `X-Suby-Api-Key` header.


    - `sk_live_…` keys operate in **production** (real funds).

    - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards,
      Base Sepolia crypto, no real money). The environment is derived from the
      key prefix.

    All monetary amounts are **integer cents** (except `priceCents` on some

    read shapes, which is a string) — token amounts are strings in the smallest

    unit (sats / lamports / wei). Fees are basis points.
  contact:
    email: dev@suby.fi
    url: https://suby.fi
servers:
  - url: https://api.beta.suby.fi
    description: Production + sandbox (environment selected by API key prefix)
security:
  - ApiKeyAuth: []
tags:
  - name: Products
    description: Manage your product catalog (one-time and recurring).
  - name: Checkout
    description: >-
      Hosted checkout — signed session tokens (`cs_…`) plus branding and
      appearance settings.
  - name: Payments
    description: >-
      Create, capture, void, and retrieve one-time & off-session payments (card,
      APM, and crypto).
  - name: Subscriptions
    description: Start and cancel recurring subscriptions.
  - name: Customers
    description: First-class customer records with billing address.
  - name: Payment Methods
    description: >-
      Save a payment method to a customer and manage saved instruments for
      off-session charges.
  - name: Webhook Endpoints
    description: Register outbound webhook destinations and rotate signing secrets.
  - name: Analytics
    description: Org-wide revenue analytics.
  - name: Health
    description: Unauthenticated liveness probe.
paths:
  /v3/checkout/sessions/{id}:
    get:
      tags:
        - Checkout
      summary: Retrieve a checkout session
      description: >-
        Re-hydrate a signed session. An expired token returns 200 with
        `status=EXPIRED`.
      operationId: getCheckoutSession
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: cs_abc123
      responses:
        '200':
          description: Checkout session
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/CheckoutSession'
        '400':
          description: Invalid signature (`CHECKOUT_SESSION_INVALID_SIGNATURE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          description: Endpoint-specific payload.
    CheckoutSession:
      type: object
      properties:
        id:
          type: string
          example: cs_abc123
        organizationId:
          type: string
        mode:
          type: string
          enum:
            - payment
            - subscription
        productId:
          type: string
          nullable: true
        lineItems:
          type: array
          nullable: true
          items:
            type: object
            properties:
              productId:
                type: string
              quantity:
                type: integer
              adjustable:
                type: boolean
              min:
                type: integer
              max:
                type: integer
        amount:
          type: integer
          nullable: true
        currency:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        allowPromo:
          type: boolean
        customerId:
          type: string
          nullable: true
        customerEmail:
          type: string
          nullable: true
        customerFirstName:
          type: string
          nullable: true
        customerLastName:
          type: string
          nullable: true
        successUrl:
          type: string
          nullable: true
        cancelUrl:
          type: string
          nullable: true
        discountCode:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        customFields:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/CustomField'
        status:
          type: string
          enum:
            - OPEN
            - EXPIRED
            - COMPLETED
        url:
          type: string
          description: Hosted checkout page — redirect the customer here.
        expiresAt:
          type: integer
          description: Epoch milliseconds.
        createdAt:
          type: integer
          description: Epoch milliseconds.
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          example: Resource not found
        data:
          description: Optional error detail.
    CustomField:
      type: object
      required:
        - key
        - label
        - type
      properties:
        key:
          type: string
          maxLength: 50
          pattern: ^[a-z0-9_]+$
          description: Response-map key.
        label:
          type: string
          maxLength: 100
        type:
          type: string
          enum:
            - input
            - select
            - checkbox
        required:
          type: boolean
        placeholder:
          type: string
          maxLength: 200
        options:
          type: array
          description: Required (≥1) when `type=select`.
          items:
            type: object
            required:
              - value
              - label
            properties:
              value:
                type: string
                maxLength: 100
              label:
                type: string
                maxLength: 100
        validation:
          type: object
          description: '`type=input` only — client-side regex.'
          properties:
            regex:
              type: string
              maxLength: 500
            errorMessage:
              type: string
              maxLength: 200
        defaultValue:
          type: string
          maxLength: 500
          description: Merchant pre-fill (editable).
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: UNAUTHORIZED
            message: Invalid or missing API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: NOT_FOUND
            message: Resource not found
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Suby-Api-Key
      description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox).

````