# Carts Shopping cart creation, item management, pricing, and checkout. ## Create a new cart - [POST /carts](https://tote.redocly.app/online-ordering/spec/openapi/carts/createcart.md): Creates an empty cart for the specified location. The cart is initialized with ACTIVE status and zero totals. Items are added via POST /carts/{cart_id}/items. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Get cart details - [GET /carts/{cart_id}](https://tote.redocly.app/online-ordering/spec/openapi/carts/getcart.md): Retrieves the current state of a cart, including all items, computed totals, and status. Returns the cart with server-computed subtotal, total_tax, total_discount, and total. ## Abandon a cart - [DELETE /carts/{cart_id}](https://tote.redocly.app/online-ordering/spec/openapi/carts/deletecart.md): Marks a cart as ABANDONED. This is a soft delete -- the cart data is retained but can no longer be modified or checked out. Only ACTIVE carts can be abandoned. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Update cart properties - [PATCH /carts/{cart_id}](https://tote.redocly.app/online-ordering/spec/openapi/carts/updatecart.md): Partially updates a cart's properties. Currently supports updating the customer_id field. The cart must be in ACTIVE status. Customer identity: Setting customer_id enables the server to apply member-specific pricing on the next /calculate call. Setting customer_id to null reverts to anonymous pricing. After changing customer_id, re-calculate prices -- previous pricing may be stale. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. ## Add an item to the cart - [POST /carts/{cart_id}/items](https://tote.redocly.app/online-ordering/spec/openapi/carts/addcartitem.md): Adds a menu item with optional modifier selections to the cart. The server validates that the menu item exists, is available, and that modifier selections satisfy the min_selections/max_selections constraints of each modifier group. Age-restricted items can be added freely. The cart's age_verification_required flag will be set to true, and the consumer will be informed that verification is required at pickup or delivery. The response includes the updated cart with recalculated totals. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Update a cart item - [PUT /carts/{cart_id}/items/{item_id}](https://tote.redocly.app/online-ordering/spec/openapi/carts/updatecartitem.md): Updates the quantity and/or modifier selections of an existing cart item. The full CartItemRequest must be provided (this is a full replacement, not a patch). The server re-validates modifier constraints against the current menu. The response includes the updated cart with recalculated totals. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Remove an item from the cart - [DELETE /carts/{cart_id}/items/{item_id}](https://tote.redocly.app/online-ordering/spec/openapi/carts/removecartitem.md): Removes a specific item from the cart. The response includes the updated cart with recalculated totals. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Calculate cart prices - [POST /carts/{cart_id}/calculate](https://tote.redocly.app/online-ordering/spec/openapi/carts/calculatecart.md): Returns an itemized price breakdown for the cart without creating or modifying an order. This is a read-only preview -- it computes prices at request time based on the current menu, tax configuration, and applicable discounts. Important: Prices may change between calculate and checkout if the menu or tax configuration is updated. Always call calculate immediately before checkout to show the customer the most accurate total. This endpoint is analogous to Square's CalculateOrder and Toast's /prices endpoint. ## Check out a cart - [POST /carts/{cart_id}/checkout](https://tote.redocly.app/online-ordering/spec/openapi/carts/checkoutcart.md): Converts an ACTIVE cart into an order. The cart must have at least one item and a handoff mode must be available (either stored on the cart via PUT /carts/{cart_id}/handoff, or provided as an override in the request body). Validation performed at checkout: - Cart is in ACTIVE status - Cart has at least one item - All items are still available in the current menu - Modifier selections satisfy group constraints (min/max) - Handoff mode exists (stored on cart OR provided in request body) Age verification: If the cart contains age-restricted items, checkout succeeds but the response includes age_verification_required: true and an age_verification_notice explaining that the consumer will be verified at pickup or delivery. Price changes: If expected_total is provided and the current total differs, the server returns 409 Conflict. Omit expected_total to accept the current price. After successful checkout, the cart status changes to CHECKED_OUT and can no longer be modified. The created order is returned with status PENDING. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. If the cart has already been checked out with the same idempotency key, the original order is returned. ## Set or update the cart's handoff mode - [PUT /carts/{cart_id}/handoff](https://tote.redocly.app/online-ordering/spec/openapi/carts/setcarthandoff.md): Sets how the customer wants to receive their order. The handoff mode is stored on the cart and used at checkout. Can be called multiple times to change the mode before checkout (e.g., customer switches from PICKUP to DELIVERY). The response returns the updated cart with the stored handoff mode. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## Apply a promo code to a cart - [POST /carts/{cart_id}/promo-codes](https://tote.redocly.app/online-ordering/spec/openapi/carts/applypromocode.md): Applies a promo code to the cart. The server validates the code, checks eligibility (expiry, minimum order amount, applicable items), and applies the discount. Returns the updated Cart with the promo in the promo_codes array and the discount reflected in totals. One promo at a time: Only one promo code can be active on a cart. If a promo code is already applied, the server returns 409 Conflict. Remove the existing code first via DELETE /carts/{cart_id}/promo-codes/{code}. Case-insensitive: Codes are case-insensitive on input. "summer25" and "SUMMER25" are treated identically. The code is always returned as uppercase. Discount visibility: The promo discount appears in the PriceCalculation discounts array as a DiscountLineItem with source: PROMO_CODE. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached. ## List promo codes on a cart - [GET /carts/{cart_id}/promo-codes](https://tote.redocly.app/online-ordering/spec/openapi/carts/listpromocodes.md): Returns the promo codes currently applied to the cart. This information is also included in the Cart response, but this endpoint is useful for checking promo status without fetching the full cart. ## Validate a promo code without applying - [GET /carts/{cart_id}/promo-codes/validate](https://tote.redocly.app/online-ordering/spec/openapi/carts/validatepromocode.md): Checks if a promo code is valid for this cart without applying it. Returns a discount preview (estimated amount, description, applicable items) for valid codes, or a rejection reason and message for invalid codes. Use this endpoint to show the customer what discount they would receive before they commit to applying the code. Note: The discount preview is an estimate. The actual discount is computed when the code is applied via POST /carts/{cart_id}/promo-codes. ## Remove a promo code from a cart - [DELETE /carts/{cart_id}/promo-codes/{code}](https://tote.redocly.app/online-ordering/spec/openapi/carts/removepromocode.md): Removes the specified promo code from the cart. The associated discount is removed and totals are recalculated. Returns the updated Cart with the promo removed from promo_codes and the discount removed from totals. The code path parameter is case-insensitive -- the server normalizes it before matching. Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached.