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

# Prepare hosted checkout

> Creates an idempotent, short-lived checkout handoff for a guest cart. The returned URL carries only an exchange secret in its fragment and invalidates any previously prepared handoff for the cart.



## OpenAPI

````yaml https://api.craveup.com/swagger.json post /locations/{locationId}/carts/{cartId}/checkout-handoffs
openapi: 3.0.0
info:
  title: Crave API v2.0
  version: 2.0.0
  description: >

    ## Public storefront authorization

    Published merchant, location, menu, and product reads are anonymous.
    Starting an ordering session

    returns a cart capability; send it only in the `X-Cart-Token` header for
    that cart. Cart-scoped

    analytics requires that capability or the owning customer JWT. Mutations
    also require `If-Match`

    and `Idempotency-Key` headers. Customer resources use the session JWT
    returned

    by the merchant-bound OTP flow. Before cross-origin hosted checkout, create
    and exchange a short-lived

    handoff; the cart capability itself never enters a URL. Provider secrets and
    private integration API

    keys must stay server-side.
  contact:
    name: Crave Support
    email: support@craveup.com
servers:
  - url: https://api.craveup.com/api/v1/storefront
    description: Production Storefront API
  - url: https://dev-api-43233223.craveup.com/api/v1/storefront
    description: Staging Storefront API
security: []
tags:
  - name: Merchants
    description: Retrieve merchant metadata and enabled storefront locations.
  - name: Locations
    description: Access individual location information and configuration.
  - name: Ordering Sessions
    description: Create or resume ordering sessions and carts for a location.
  - name: Menus
    description: Fetch menu bundles, categories, and popular products for a location.
  - name: Products
    description: Request detailed storefront product data including modifiers.
  - name: Carts
    description: Manage cart state, totals, and cross-sell recommendations.
  - name: Customers
    description: Handle storefront customer authentication, profiles, and sessions.
paths:
  /locations/{locationId}/carts/{cartId}/checkout-handoffs:
    post:
      tags:
        - Carts
      summary: Prepare hosted checkout
      description: >-
        Creates an idempotent, short-lived checkout handoff for a guest cart.
        The returned URL carries only an exchange secret in its fragment and
        invalidates any previously prepared handoff for the cart.
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
        - name: cartId
          in: path
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Checkout handoff prepared.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutHandoffPrepareResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The authenticated customer cart cannot become a guest handoff.
        '409':
          description: The cart or handoff is no longer mutable.
      security:
        - StorefrontCartCapability: []
components:
  schemas:
    CheckoutHandoffPrepareResponse:
      type: object
      properties:
        checkoutUrl:
          type: string
          format: uri
          description: >-
            Short-lived hosted checkout URL. The fragment contains an
            exchange-only handoff, never the cart capability.
        expiresAt:
          type: string
          format: date-time
      required:
        - checkoutUrl
        - expiresAt
      additionalProperties: false
  responses:
    Unauthorized:
      description: Unauthorized - API key is missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Unauthorized access
              code:
                type: string
                example: UNAUTHORIZED
  securitySchemes:
    StorefrontCartCapability:
      type: apiKey
      in: header
      name: X-Cart-Token
      description: >-
        Purpose-limited capability returned when an ordering session creates a
        cart.

````