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

# Create checkout session

> Create a new checkout session. Supports two modes: subscription (start a recurring plan) and credit_bundle (one-time credit pack purchase). Pass the returned checkout_session_token to the @lavapayments/checkout SDK to open the checkout flow.

<Tip>
  For `checkout_mode: "subscription"`, `customer_id` is optional:

  * Omit it for logged-out/new customers (checkout collects identity and creates a customer)
  * Include it for logged-in/returning customers (checkout reuses the existing customer)
</Tip>

```json New customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "plan_id": "sub_plan_id"
}
```

```json Returning customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "plan_id": "sub_plan_id",
  "customer_id": "conn_existing_customer_id"
}
```


## OpenAPI

````yaml /openapi.json post /checkout_sessions
openapi: 3.0.0
info:
  title: Lava API
  description: >-
    Lava API enables businesses to implement usage-based billing for AI
    services. This API allows tracking, managing, and billing for third-party AI
    API usage through a forwarding system.
  version: 1.0.0
  contact:
    name: Lava support
    url: https://www.lava.so/contact
servers:
  - url: https://api.lava.so/v1/
    description: Lava API v1
security: []
tags:
  - name: Authentication
  - name: Core Endpoints
  - name: Models
  - name: Services
  - name: Requests
  - name: Wallet
  - name: Payment Methods
  - name: Spend Keys
  - name: Usage
  - name: Checkout Sessions
  - name: Customers
  - name: Plans
  - name: Subscriptions
  - name: Meters
  - name: Webhooks
  - name: Secret Keys
  - name: Credit Bundles
  - name: Gateway Settings
  - name: Skills
  - name: News Data
  - name: Search
  - name: Enrich
paths:
  /checkout_sessions:
    post:
      tags:
        - Checkout Sessions
      summary: Create checkout session
      description: >-
        Create a new checkout session. Supports two modes: subscription (start a
        recurring plan) and credit_bundle (one-time credit pack purchase). Pass
        the returned checkout_session_token to the @lavapayments/checkout SDK to
        open the checkout flow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutSession'
      responses:
        '200':
          description: Checkout session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSession'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                body_json_parse_error:
                  summary: Invalid JSON in request body
                  value:
                    error:
                      message: >-
                        Request body contains invalid JSON. Please check your
                        request body syntax and ensure it's properly formatted.
                      code: body_json_parse_error
                      status: 400
                body_schema_validation_failed:
                  summary: Invalid request body schema
                  value:
                    error:
                      message: >-
                        Request body doesn't match the required schema. Please
                        refer to the API documentation for the correct
                        structure.
                      code: body_schema_validation_failed
                      status: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_header_missing:
                  summary: Authorization header missing
                  value:
                    error:
                      message: >-
                        Authorization header is required. Please include an
                        'Authorization' header with your request.
                      code: auth_header_missing
                      status: 401
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rest_internal_server_error:
                  summary: Internal server error
                  value:
                    error:
                      message: >-
                        An internal server error occurred while processing your
                        request.
                      code: rest_internal_server_error
                      status: 500
      security:
        - Auth: []
components:
  schemas:
    CreateCheckoutSession:
      type: object
      properties:
        checkout_mode:
          type: string
          example: subscription
          enum:
            - subscription
            - credit_bundle
          description: >-
            Checkout mode: 'subscription' creates a recurring subscription
            checkout, 'credit_bundle' purchases a credit pack for an existing
            subscriber
        origin_url:
          type: string
          format: uri
          example: https://your-app.example.com/
          description: Origin url where the checkout will be opened
        customer_id:
          type: string
          example: con_test_01EXAMPLE00000000000000001
          description: >-
            Required for credit_bundle mode. Optional for subscription mode —
            omit for new customers (checkout collects identity and creates a
            customer) or include for returning customers (reuses the existing
            customer).
        plan_id:
          type: string
          example: sc_123
          description: >-
            Required when checkout_mode is 'subscription' - identifies the plan
            to use
        credit_bundle_id:
          type: string
          example: cb_abc123
          description: >-
            Required when checkout_mode is 'credit_bundle' - identifies the
            credit bundle to purchase
      required:
        - origin_url
        - checkout_mode
    CheckoutSession:
      type: object
      properties:
        checkout_session_id:
          type: string
          example: cs_test_01EXAMPLE00000000000000001
          description: Unique identifier for the checkout session
        checkout_session_token:
          type: string
          example: >-
            eyJzZWNyZXQiOiJjc3NfdGVzdF9leGFtcGxlX3NlY3JldCIsImJhc2UiOiJodHRwczovL2NoZWNrb3V0LmV4YW1wbGUuY29tLyJ9
          description: >-
            Opaque token for the @lavapayments/checkout SDK. Pass this to open()
            to launch the checkout flow.
        checkout_mode:
          type: string
          example: subscription
          enum:
            - subscription
            - credit_bundle
          description: >-
            Checkout mode: 'subscription' creates a recurring subscription
            checkout, 'credit_bundle' purchases a credit pack for an existing
            subscriber
        origin_url:
          type: string
          example: https://your-app.example.com/
          description: Origin url where the checkout will be opened
        customer_id:
          type: string
          example: con_test_01EXAMPLE00000000000000001
          description: >-
            Identifier for the customer (only available after checkout
            completion)
        plan_id:
          type: string
          example: sc_123
          description: Identifier for the plan (only available for subscription mode)
        created_at:
          type: string
          format: date-time
          example: '2023-05-15T08:30:00Z'
          description: ISO 8601 timestamp when the checkout session was created
        completed_at:
          type: string
          format: date-time
          example: '2023-05-15T08:35:42Z'
          description: If completed, ISO 8601 timestamp when the checkout was completed
      required:
        - checkout_session_id
        - checkout_session_token
        - checkout_mode
        - origin_url
        - created_at
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message describing what went wrong
              example: Invalid authentication credentials
            code:
              type: string
              description: Machine-readable error code describing what went wrong
              example: forward_token_json_invalid
            status:
              type: integer
              description: HTTP status code of the error
              example: 400
            issues:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      type: string
                    description: Path to the field that caused the validation error
                  message:
                    type: string
                    description: Error message describing the validation issue
                required:
                  - path
                  - message
              description: >-
                Optional array of specific validation issues with their paths
                and messages
              example:
                - path:
                    - model
                  message: 'Missing required field: model'
                - path:
                    - messages
                    - '0'
                    - content
                  message: Invalid message content format
          required:
            - message
            - code
            - status
      required:
        - error
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication used for standard API calls. Format: 'Bearer
        YOUR_API_KEY'

````