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

# Checkout (Cart to Order + Payment)

> Converts a cart into an order and initiates payment.
The response includes provider-specific payment data depending on `payment_method`:
- **stripe** — `payment` object with `client_secret` and `payment_intent_id` for Stripe.js
- **tosspayments** — `toss_payment` object with order info for TossPayments SDK
- **manual** — No payment data; admin records payment later




## OpenAPI

````yaml openapi.yaml post /storefront/carts/{id}/checkout
openapi: 3.1.0
info:
  title: Headless Commerce API
  description: >
    Headless Commerce as a Service — REST API specification.


    ## Authentication

    Pass your API key as a Bearer token in every request.

    - **Secret Key** (`sk_live_*`, `sk_test_*`): Server-side. Full access to
    Admin + Storefront APIs.

    - **Publishable Key** (`pk_live_*`, `pk_test_*`): Client-side. Storefront
    API only.


    ## Customer Authentication (Storefront)

    Storefront endpoints that require customer identification
    (/storefront/customers/*, /storefront/orders/*)

    need the `X-Customer-Token` header.

    1. From your backend, call `POST /admin/customers/{id}/token` with an `sk_*`
    key to issue a token

    2. From the frontend, send requests with the `pk_*` key + `X-Customer-Token`
    header


    ## Pagination

    Uses cursor-based pagination.

    - `limit`: Page size (default 20, max 100)

    - `starting_after`: Return results after this ID

    - Response includes `has_more` and `next_cursor`


    ## Money

    All amounts are integers in the smallest currency unit (KRW=won, USD=cents).


    ## Rate Limiting

    All responses include the following headers:

    - `X-RateLimit-Limit`: Max requests per minute (by plan: Free 100, Starter
    500, Pro 2000, Enterprise 10000)

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - Returns `429 Too Many Requests` when exceeded


    ## Idempotency

    Include an `Idempotency-Key` header with payment/order-related POST requests
    to receive the original response for duplicate requests with the same key.

    Recommended for: checkout, refund, and payment creation
  version: 1.0.0
  contact:
    name: Headless Commerce Support
    url: https://headlesscommerce.io
servers:
  - url: https://api.headlesscommerce.io/v1
    description: Production
  - url: https://api.headlesscommerce.io/v1
    description: Test (same URL, test API key)
security:
  - BearerAuth: []
tags:
  - name: Storefront - Products
    description: Browse products for buyers
  - name: Storefront - Cart
    description: Cart management and checkout
  - name: Storefront - Orders
    description: View orders (own orders)
  - name: Storefront - Customers
    description: Customer profile (own profile)
  - name: Storefront - Shipping
    description: View shipping methods
  - name: Admin - Products
    description: Product management
  - name: Admin - Variants
    description: Variant management
  - name: Admin - Categories
    description: Category management
  - name: Admin - Collections
    description: Collection management
  - name: Admin - Inventory
    description: Inventory management
  - name: Admin - Orders
    description: Order management
  - name: Admin - Fulfillments
    description: Fulfillment management
  - name: Admin - Customers
    description: Customer management
  - name: Admin - Discounts
    description: Discount management
  - name: Admin - Shipping Methods
    description: Shipping method management
  - name: Admin - Webhooks
    description: Webhook management
  - name: Admin - Store
    description: Store settings
  - name: Admin - Settings
    description: API keys, organization, and team management
  - name: Admin - Returns
    description: Return management
  - name: Admin - Regions
    description: Region, i18n, and currency rate management
  - name: Admin - Dashboard
    description: Dashboard statistics
  - name: Admin - Logs
    description: API log viewing
  - name: Admin - Uploads
    description: File uploads
  - name: Storefront - Returns
    description: Customer return requests and viewing
  - name: Storefront - Customer Auth
    description: Customer registration and login
  - name: Storefront - Payments
    description: Payment confirmation
  - name: OAuth
    description: OAuth 2.1 Authorization Code flow with PKCE
  - name: Auth
    description: Dashboard user password reset
  - name: Admin - CSV
    description: Bulk CSV import and export
paths:
  /storefront/carts/{id}/checkout:
    post:
      tags:
        - Storefront - Cart
      summary: Checkout (Cart to Order + Payment)
      description: >
        Converts a cart into an order and initiates payment.

        The response includes provider-specific payment data depending on
        `payment_method`:

        - **stripe** — `payment` object with `client_secret` and
        `payment_intent_id` for Stripe.js

        - **tosspayments** — `toss_payment` object with order info for
        TossPayments SDK

        - **manual** — No payment data; admin records payment later
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResult'
        '400':
          $ref: '#/components/responses/ValidationError'
          description: Bad request
        '409':
          $ref: '#/components/responses/ConflictError'
          description: Conflict
components:
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Resource ID
  schemas:
    CheckoutInput:
      type: object
      required:
        - email
        - shipping_address
      properties:
        email:
          type: string
          format: email
          description: |
            Buyer email. Required for Guest Checkout (no customer_id).
            For logged-in customers, the customer email is used if omitted.
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        payment_method:
          type: string
          enum:
            - manual
            - stripe
            - tosspayments
          default: manual
          description: >
            Payment provider to use.

            - `manual` — No online payment. Admin records payment later via
            dashboard.

            - `stripe` — Creates a Stripe PaymentIntent. Returns
            `payment.client_secret` for client-side Stripe.js confirmation.

            - `tosspayments` — Returns `toss_payment` object for client-side
            TossPayments SDK. After client approval, call `POST
            /storefront/payments/confirm`.
        note:
          type: string
          description: Optional note from the buyer
        metadata:
          type: object
          description: Custom key-value data
    CheckoutResult:
      description: |
        Order object with additional payment initialization data.
        Extends the standard Order schema with provider-specific fields.
      allOf:
        - $ref: '#/components/schemas/Order'
        - type: object
          properties:
            payment:
              type: object
              nullable: true
              description: >-
                Stripe payment data. Only present when `payment_method` is
                `stripe`.
              properties:
                client_secret:
                  type: string
                  description: Stripe PaymentIntent client secret for Stripe.js
                payment_intent_id:
                  type: string
                  description: Stripe PaymentIntent ID
            toss_payment:
              type: object
              nullable: true
              description: >-
                TossPayments payment data. Only present when `payment_method` is
                `tosspayments`.
              properties:
                order_id:
                  type: string
                  description: Order ID to pass to TossPayments SDK
                order_name:
                  type: string
                  description: 'Order display name (e.g. ''Order #1234'')'
                amount:
                  type: integer
                  description: Payment amount in smallest currency unit
                currency:
                  type: string
                  description: Currency code (e.g. 'KRW')
                customer_email:
                  type: string
                  description: Customer email for TossPayments receipt
    Address:
      type: object
      properties:
        name:
          type: string
        company:
          type: string
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2
        phone:
          type: string
    Order:
      type: object
      properties:
        id:
          type: string
        number:
          type: integer
        status:
          type: string
          enum:
            - draft
            - pending
            - confirmed
            - processing
            - completed
            - cancelled
        payment_status:
          type: string
          enum:
            - unpaid
            - awaiting_payment
            - partially_paid
            - paid
            - partially_refunded
            - refunded
        fulfillment_status:
          type: string
          enum:
            - unfulfilled
            - partially_fulfilled
            - fulfilled
            - returned
        customer_id:
          type: string
          nullable: true
        email:
          type: string
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        lines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
        subtotal:
          $ref: '#/components/schemas/Money'
        discount_total:
          $ref: '#/components/schemas/Money'
        shipping_total:
          $ref: '#/components/schemas/Money'
        tax_total:
          $ref: '#/components/schemas/Money'
        total:
          $ref: '#/components/schemas/Money'
        refunded_total:
          $ref: '#/components/schemas/Money'
        applied_discounts:
          type: array
          items:
            $ref: '#/components/schemas/AppliedDiscount'
        shipping_method_name:
          type: string
        note:
          type: string
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        fulfillments:
          type: array
          items:
            $ref: '#/components/schemas/Fulfillment'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        cancelled_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            details:
              type: object
    OrderLine:
      type: object
      properties:
        id:
          type: string
        variant_id:
          type: string
        product_id:
          type: string
        product_name:
          type: string
        variant_name:
          type: string
        sku:
          type: string
        image_url:
          type: string
        quantity:
          type: integer
        unit_price:
          $ref: '#/components/schemas/Money'
        line_discount:
          $ref: '#/components/schemas/Money'
        line_total:
          $ref: '#/components/schemas/Money'
        tax_amount:
          $ref: '#/components/schemas/Money'
        fulfilled_quantity:
          type: integer
        refunded_quantity:
          type: integer
    Money:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          description: Smallest currency unit (KRW=won, USD=cents)
        currency:
          type: string
          minLength: 3
          maxLength: 3
    AppliedDiscount:
      type: object
      properties:
        discount_id:
          type: string
        code:
          type: string
          nullable: true
        name:
          type: string
        value_type:
          type: string
          enum:
            - fixed
            - percentage
            - free_shipping
        value:
          type: number
        saved:
          $ref: '#/components/schemas/Money'
    Payment:
      type: object
      properties:
        id:
          type: string
        order_id:
          type: string
        provider:
          type: string
        provider_id:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - cancelled
            - refunded
        created_at:
          type: string
          format: date-time
    Fulfillment:
      type: object
      properties:
        id:
          type: string
        order_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - shipped
            - delivered
            - cancelled
        tracking_number:
          type: string
        tracking_url:
          type: string
        carrier:
          type: string
        lines:
          type: array
          items:
            type: object
            properties:
              order_line_id:
                type: string
              quantity:
                type: integer
        created_at:
          type: string
          format: date-time
        shipped_at:
          type: string
          format: date-time
          nullable: true
        delivered_at:
          type: string
          format: date-time
          nullable: true
    Refund:
      type: object
      properties:
        id:
          type: string
        order_id:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
        reason:
          type: string
        restock:
          type: boolean
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
        lines:
          type: array
          items:
            type: object
            properties:
              order_line_id:
                type: string
              quantity:
                type: integer
        created_at:
          type: string
          format: date-time
  responses:
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ConflictError:
      description: Status conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx'

````