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

# Create a checkout session

> Generate a short-lived JWT token and hosted checkout URL for a draft order. Use the token with the Tilta JS SDK or redirect the buyer to the URL.

Once you have created a draft order, use this endpoint to generate a checkout session that lets the buyer complete the order details – including selecting a payment term and confirming the purchase amount – within Tilta's hosted checkout UI. The response provides both a short-lived JWT token (for embedding the checkout flow via the Tilta JS SDK) and a pre-built hosted URL (for a full-page redirect). The session is scoped to the specific draft order and expires shortly after creation, so generate it only when you are ready to redirect the buyer.

<Note>
  Checkout sessions are single-use and short-lived. Do not cache the `token` or `url` across page loads – call this endpoint
  fresh each time a buyer is about to enter the checkout flow.
</Note>

<Tip>
  When using the hosted URL redirect approach, listen for the `ORDER.CONFIRMED` webhook event to know when the buyer has
  completed the draft order and it is ready for invoicing.
</Tip>


## OpenAPI

````yaml POST /v1/orders/{external_id}/sessions/checkout
openapi: 3.0.0
info:
  version: 0.0.1
  title: Tilta API
  description: Tilta API documentation
servers:
  - url: https://api.tilta.io
    description: Tilta Production API
  - url: https://api.tilta-sandbox.io
    description: Tilta Sandbox API
security: []
paths:
  /v1/orders/{external_id}/sessions/checkout:
    post:
      tags:
        - Orders
      summary: Create an order checkout session
      description: >-
        Creates a checkout session for a specific order.

        Returns a short-lived JWT token and a pre-built hosted checkout URL. Use
        the token to initialise the Tilta JS SDK web element, or redirect the
        buyer to the URL to use the hosted checkout UI. Only draft orders are
        eligible for a checkout session.
      parameters:
        - schema:
            type: string
            maxLength: 100
            pattern: ^[a-zA-Z0-9-_]+$
            description: Unique identifier of an order.
          required: true
          description: Unique identifier of an order.
          name: external_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                success_url:
                  type: string
                  format: uri
                error_url:
                  type: string
                  format: uri
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  url:
                    type: string
                required:
                  - token
                  - url
                description: >-
                  JWT token and hosted checkout URL to authenticate a buyer in
                  the order checkout flow. The token is valid for 2h.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestSchema'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorizedRequestSchema'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderNotFoundSchema'
      security:
        - bearerAuth: []
components:
  schemas:
    badRequestSchema:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: BAD_REQUEST
        error:
          type: string
          description: Error message for debugging purposes
          example: Request validation failed. 1 issue found.
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Issue code
                example: INVALID_TYPE
              path:
                type: string
                description: Issue path starting with body, params, querystring, or headers
                example: body.registered_at
              message:
                type: string
                description: Issue message for debugging purposes
                example: Invalid type
            required:
              - code
              - path
              - message
          description: List of issues
          example:
            - code: INVALID_TYPE
              path: body.registered_at
              message: Invalid type
      required:
        - code
        - error
        - issues
      description: Bad Request, see error message for details.
      example:
        code: BAD_REQUEST
        error: Request validation failed. 1 issue found.
        issues:
          - code: INVALID_TYPE
            path: body.registered_at
            message: Invalid type
    unauthorizedRequestSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: Unauthorized
        code:
          type: string
          description: Error code.
          example: UNAUTHORIZED
      required:
        - error
        - code
      description: Unauthorized Request.
      example:
        error: Unauthorized
        code: UNAUTHORIZED
    orderNotFoundSchema:
      type: object
      properties:
        error:
          type: string
          description: Error details.
          example: No Entity found
        code:
          type: string
          description: Error code.
          example: NOT_FOUND
      required:
        - error
        - code
      description: Order not found
      example:
        error: No Entity found
        code: NOT_FOUND
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Tilta API key, sent as `Bearer <key>`.

````