> ## 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. # Add item to cart > Appends a product to the cart, merging with existing items when the configuration matches. ## OpenAPI ````yaml https://api.craveup.com/swagger.json post /locations/{locationId}/carts/{cartId}/cart-item openapi: 3.0.0 info: title: Crave API v2.0 version: 2.0.0 description: > ## 🔑 Generate an API Key Every request to the Storefront API must include an API key. 1. Sign in to the [Crave Business Manager](https://partners.craveup.com). 2. Open **Settings → Developer → API Keys**. 3. Click **Generate Key**, give it a descriptive name (for example, `storefront-sdk-staging`), and confirm. 4. Copy the key immediately—once you leave the page it cannot be viewed again. Add the key to each request header: ```http GET /merchant/crave-collective Host: api.craveup.com X-API-Key: ``` ### Best practices - Store keys in environment variables or a secrets manager; never commit them to source control. - Use separate keys for staging and production so they can be rotated independently. - If a key is exposed, revoke it from the dashboard and generate a fresh one right away. contact: name: Crave Support email: support@craveup.com servers: - url: https://api.craveup.com/api/v1 description: Production Storefront API - url: https://dev-api-43233223.craveup.com/api/v1 description: Staging Storefront API security: - ApiKeyAuth: [] 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}/cart-item: post: tags: - Carts summary: Add item to cart description: >- Appends a product to the cart, merging with existing items when the configuration matches. parameters: - name: locationId in: path required: true schema: type: string example: loc_456def - name: cartId in: path required: true schema: type: string example: cart_123 requestBody: required: true content: application/json: schema: type: object properties: productId: type: string example: prod_margherita quantity: type: integer minimum: 1 example: 2 specialInstructions: type: string nullable: true example: Extra crispy itemUnavailableAction: type: string description: Behavior when the item becomes unavailable. enum: - remove_item - cancel_entire_order example: remove_item selections: type: array description: Selected modifier groups and options. items: type: object properties: groupId: type: string example: mod_group_crust selectedOptions: type: array items: type: object properties: optionId: type: string example: mod_option_thin quantity: type: integer example: 1 children: type: array items: type: object properties: groupId: type: string selectedOptions: type: array items: type: object properties: optionId: type: string quantity: type: integer nullable: true required: - optionId - quantity required: - groupId - selectedOptions categoryId: type: string nullable: true example: cat_pizzas required: - productId - quantity - itemUnavailableAction - selections responses: '200': description: Item added successfully. content: application/json: schema: $ref: '#/components/schemas/StorefrontCartUpsertResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/GenericError' security: - ApiKeyAuth: [] components: schemas: StorefrontCartUpsertResponse: type: object properties: cartId: type: string example: cart_123 cart: $ref: '#/components/schemas/StorefrontCart' required: - cartId - cart description: Response structure returned after adding or updating items in a cart. 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 checkoutUrl: type: string nullable: true fulfillmentIdentifier: type: string nullable: true example: null additionalProperties: true responses: BadRequest: description: Bad Request - The request was invalid or cannot be served. content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Invalid input parameters code: type: string example: BAD_REQUEST data: type: object example: {} 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 GenericError: description: Generic Error - An unexpected error occurred. content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: An unexpected error occurred code: type: string example: GENERIC_ERROR securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API Key required to authenticate requests ````