> ## 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. # Exchange a hosted-checkout handoff > Consumes the short-lived fragment handoff and rotates the cart capability into the hosted checkout origin. The response carries the verified merchant slug needed for customer authentication on the shared checkout host. Exact retries with the same Idempotency-Key replay the response; a different key is rejected after consumption. ## OpenAPI ````yaml https://api.craveup.com/swagger.json post /locations/{locationId}/carts/{cartId}/checkout-handoffs/exchange 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/exchange: post: tags: - Carts summary: Exchange a hosted-checkout handoff description: >- Consumes the short-lived fragment handoff and rotates the cart capability into the hosted checkout origin. The response carries the verified merchant slug needed for customer authentication on the shared checkout host. Exact retries with the same Idempotency-Key replay the response; a different key is rejected after consumption. 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: '200': description: Checkout handoff exchanged. content: application/json: schema: $ref: '#/components/schemas/CheckoutHandoffExchangeResponse' '401': $ref: '#/components/responses/Unauthorized' '409': description: The handoff was already consumed or can no longer be used. security: - StorefrontCheckoutHandoff: [] components: schemas: CheckoutHandoffExchangeResponse: type: object properties: cart: $ref: '#/components/schemas/StorefrontCart' cartAccessToken: type: string description: >- Checkout-origin cart capability. Store it in tab-scoped storage and send it only as X-Cart-Token. merchantSlug: type: string description: >- Verified merchant slug for customer authentication on a shared hosted-checkout origin. required: - cart - cartAccessToken - merchantSlug additionalProperties: false StorefrontCart: type: object properties: id: type: string example: cart_123 locationId: type: string example: loc_456def status: type: string example: OPEN lockedAt: type: string nullable: true format: date-time example: null description: >- Timestamp when the cart was locked for checkout. Null while the cart is editable. discountCode: type: string nullable: true example: SAVE10 currency: type: string example: usd fulfilmentMethod: type: string example: pickup description: >- Current fulfillment method for the cart. Note: the API responds with the UK spelling `fulfilmentMethod`; when updating a cart send `fulfillmentMethod` in the request body. statementDescriptor: type: string nullable: true example: CRAVE*Downtown Pizza Co description: Descriptor that appears on the shopper’s card statement. pickupType: type: string example: ASAP orderDate: type: string example: '2024-11-12' orderTime: type: string example: '18:30' totalQuantity: type: integer example: 3 subTotal: type: string example: '3600' subTotalFormatted: type: string example: $36.00 discountTotal: type: string example: '0.00' discountTotalFormatted: type: string example: $0.00 waiterTipTotal: type: string example: '540' waiterTipTotalFormatted: type: string example: $5.40 taxTotal: type: string example: '280' taxTotalFormatted: type: string example: $2.80 taxAndFeeTotal: type: string example: '320' taxAndFeeTotalFormatted: type: string example: $3.20 serviceFeeTotal: type: string example: '120' serviceFeeTotalFormatted: type: string example: $1.20 paymentProcessingFeeTotal: type: string example: '40' paymentProcessingFeeTotalFormatted: type: string example: $0.40 applicationFeeTotal: type: string example: '0.00' applicationFeeTotalFormatted: type: string example: $0.00 netSalesTotal: type: string example: '3600' netSalesTotalFormatted: type: string example: $36.00 fulfillmentMethodFeeTotal: type: string example: '0.00' fulfillmentMethodFeeTotalFormatted: type: string example: $0.00 orderTotalWithServiceFee: type: string example: '4460' orderTotalWithServiceFeeFormatted: type: string example: $44.60 orderTotalWithServiceFeeAmount: type: number example: 4460 description: Order total with fees converted into the smallest currency unit. orderTotal: type: string example: '4040' orderTotalFormatted: type: string example: $40.40 enterpriseFeeTotal: type: string example: '0.00' enterpriseFeeTotalFormatted: type: string example: $0.00 subTotalWithoutDiscount: type: string example: '3600' subTotalWithoutDiscountFormatted: type: string example: $36.00 restaurantDisplayName: type: string example: Downtown Pizza Co deliveryInfo: type: object nullable: true properties: addressString: type: string example: 123 Market Street, San Francisco, CA 94105 addressData: type: object additionalProperties: true tableServiceInfo: type: object nullable: true properties: tableNumber: type: string example: A5 roomServiceInfo: type: object nullable: true properties: lastName: type: string example: Smith roomNumber: type: string example: '1203' fees: type: object properties: enterpriseFeeRate: type: string example: '0.0000' enterpriseFeeFix: type: string example: '0.00' serviceFeeRate: type: string example: '0.0250' serviceFeeFix: type: string example: '0.00' taxRate: type: string example: '0.0775' tipRate: type: string example: '0.0000' fulfillmentMethodFeeFix: type: string example: '0.00' fulfillmentMethodFeeRate: type: string example: '0.0000' paymentProcessingFeeRate: type: string example: '0.0290' paymentProcessingFeeFix: type: string example: '0.30' metadata: type: object nullable: true additionalProperties: true fulfillmentIdentifier: type: string nullable: true example: null additionalProperties: true 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: StorefrontCheckoutHandoff: type: apiKey in: header name: X-Checkout-Handoff description: >- Short-lived one-time handoff read from the hosted checkout URL fragment and removed from browser history before exchange. ````