> ## 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. # Create or resume an ordering session ## OpenAPI ````yaml /generated/storefront.openapi.json post /locations/{locationId}/ordering-sessions openapi: 3.0.3 info: title: Crave Storefront API version: 2.0.0 description: >- Direct public Storefront API. Anonymous catalog reads require no API key. Protected resources use purpose-limited cart, checkout, receipt, or customer credentials. contact: name: Crave Support email: hello@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: Sandbox Storefront API security: [] tags: - name: Merchants - name: Locations - name: Ordering Sessions - name: Menus - name: Products - name: Analytics - name: Carts - name: Checkout - name: Cart Items - name: Discounts - name: Loyalty - name: Customer Authentication - name: Customers - name: Orders paths: /locations/{locationId}/ordering-sessions: post: tags: - Ordering Sessions summary: Create or resume an ordering session operationId: storefrontStartOrderingSession parameters: - name: locationId in: path required: true schema: type: string minLength: 1 maxLength: 128 - name: Idempotency-Key in: header required: true description: Caller-stable key reused only for retries of this exact request. schema: type: string minLength: 16 maxLength: 128 pattern: ^[A-Za-z0-9._:-]{16,128}$ - name: If-Match in: header required: false description: Required when existingCartId is present. schema: type: string pattern: ^(?:W/)?"cart-(?:0|[1-9][0-9]*)"$ requestBody: required: true content: application/json: schema: type: object properties: marketplaceId: type: string minLength: 1 maxLength: 128 fulfillmentMethod: type: string enum: - takeout - table_side - room_service - delivery existingCartId: nullable: true type: string pattern: ^[a-f\d]{24}$ channel: type: string enum: - qr - web - kiosk - app - pos - unknown metadata: type: object additionalProperties: {} returnUrl: type: string maxLength: 2048 format: uri required: - fulfillmentMethod additionalProperties: false responses: '200': description: Created or resumed ordering session. content: application/json: schema: type: object properties: cart: type: object properties: id: type: string minLength: 1 maxLength: 128 locationId: type: string minLength: 1 maxLength: 128 merchantId: type: string minLength: 1 maxLength: 128 status: type: string enum: - OPEN - LOCKED - COMPLETED - EXPIRED lockedAt: nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ revision: type: integer minimum: 0 maximum: 9007199254740991 expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ restaurantDisplayName: type: string fulfilmentMethod: type: string enum: - takeout - table_side - room_service - delivery fulfillmentIdentifier: type: string metadata: type: object additionalProperties: {} pickupType: type: string enum: - ASAP - LATER orderDate: type: string orderTime: type: string currency: type: string enum: - usd - gbp - aed - aud subTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ subTotalFormatted: type: string discountTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ discountTotalFormatted: type: string waiterTipTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ waiterTipTotalFormatted: type: string taxTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ taxTotalFormatted: type: string taxAndFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ taxAndFeeTotalFormatted: type: string serviceFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeTotalFormatted: type: string paymentProcessingFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeTotalFormatted: type: string applicationFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ applicationFeeTotalFormatted: type: string netSalesTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ netSalesTotalFormatted: type: string fulfillmentMethodFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeTotalFormatted: type: string orderTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ orderTotalFormatted: type: string orderTotalWithServiceFee: type: string pattern: ^-?\d+(?:\.\d+)?$ orderTotalWithServiceFeeFormatted: type: string orderTotalWithServiceFeeAmount: type: integer minimum: 0 maximum: 9007199254740991 enterpriseFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ enterpriseFeeTotalFormatted: type: string subTotalWithoutDiscount: type: string pattern: ^-?\d+(?:\.\d+)?$ subTotalWithoutDiscountFormatted: type: string discountCode: type: string statementDescriptor: type: string totalQuantity: type: integer minimum: 0 maximum: 9007199254740991 items: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 128 productId: type: string minLength: 1 maxLength: 128 name: type: string description: type: string imageUrl: type: string price: type: string pattern: ^-?\d+(?:\.\d+)?$ priceFormatted: type: string quantity: type: integer minimum: 0 maximum: 9007199254740991 total: type: string pattern: ^-?\d+(?:\.\d+)?$ totalFormatted: type: string discount: type: string pattern: ^-?\d+(?:\.\d+)?$ discountFormatted: type: string categoryId: nullable: true type: string minLength: 1 maxLength: 128 specialInstructions: type: string itemUnavailableAction: type: string enum: - remove_item - cancel_entire_order selections: type: array items: {} product: type: object properties: id: type: string minLength: 1 maxLength: 128 name: type: string price: type: string pattern: ^-?\d+(?:\.\d+)?$ required: - id required: - id - productId - name - description - imageUrl - price - priceFormatted - quantity - total - totalFormatted - discount - discountFormatted - categoryId - itemUnavailableAction - selections additionalProperties: {} fees: type: object properties: enterpriseFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ enterpriseFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ taxRate: type: string pattern: ^-?\d+(?:\.\d+)?$ tipRate: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ required: - enterpriseFeeRate - enterpriseFeeFix - serviceFeeRate - serviceFeeFix - taxRate - tipRate - fulfillmentMethodFeeFix - fulfillmentMethodFeeRate - paymentProcessingFeeRate - paymentProcessingFeeFix additionalProperties: false deliveryInfo: nullable: true type: object properties: addressString: type: string addressData: type: object properties: street: type: string minLength: 1 streetOptional: default: '' type: string city: type: string minLength: 1 state: type: string minLength: 1 zipCode: type: string minLength: 1 country: type: string enum: - United States - United Arab Emirates - Australia - United Kingdom lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 required: - street - city - state - zipCode - country - lat - lng additionalProperties: false required: - addressString - addressData additionalProperties: {} tableServiceInfo: nullable: true type: object properties: tableNumber: type: string additionalProperties: {} roomServiceInfo: nullable: true type: object properties: lastName: type: string roomNumber: type: string additionalProperties: {} required: - id - locationId - merchantId - status - revision - expiresAt - restaurantDisplayName - fulfilmentMethod - fulfillmentIdentifier - pickupType - orderDate - orderTime - currency - subTotal - subTotalFormatted - discountTotal - discountTotalFormatted - waiterTipTotal - waiterTipTotalFormatted - taxTotal - taxTotalFormatted - taxAndFeeTotal - taxAndFeeTotalFormatted - serviceFeeTotal - serviceFeeTotalFormatted - paymentProcessingFeeTotal - paymentProcessingFeeTotalFormatted - applicationFeeTotal - applicationFeeTotalFormatted - netSalesTotal - netSalesTotalFormatted - fulfillmentMethodFeeTotal - fulfillmentMethodFeeTotalFormatted - orderTotal - orderTotalFormatted - orderTotalWithServiceFee - orderTotalWithServiceFeeFormatted - orderTotalWithServiceFeeAmount - enterpriseFeeTotal - enterpriseFeeTotalFormatted - subTotalWithoutDiscount - subTotalWithoutDiscountFormatted - statementDescriptor - totalQuantity - items - fees additionalProperties: false cartAccessToken: type: string required: - cart additionalProperties: false headers: ETag: description: >- Current resource revision tag. Send it in If-Match before mutation. schema: type: string Cache-Control: schema: type: string example: private, no-store '201': description: Created or resumed ordering session. content: application/json: schema: type: object properties: cart: type: object properties: id: type: string minLength: 1 maxLength: 128 locationId: type: string minLength: 1 maxLength: 128 merchantId: type: string minLength: 1 maxLength: 128 status: type: string enum: - OPEN - LOCKED - COMPLETED - EXPIRED lockedAt: nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ revision: type: integer minimum: 0 maximum: 9007199254740991 expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ restaurantDisplayName: type: string fulfilmentMethod: type: string enum: - takeout - table_side - room_service - delivery fulfillmentIdentifier: type: string metadata: type: object additionalProperties: {} pickupType: type: string enum: - ASAP - LATER orderDate: type: string orderTime: type: string currency: type: string enum: - usd - gbp - aed - aud subTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ subTotalFormatted: type: string discountTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ discountTotalFormatted: type: string waiterTipTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ waiterTipTotalFormatted: type: string taxTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ taxTotalFormatted: type: string taxAndFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ taxAndFeeTotalFormatted: type: string serviceFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeTotalFormatted: type: string paymentProcessingFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeTotalFormatted: type: string applicationFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ applicationFeeTotalFormatted: type: string netSalesTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ netSalesTotalFormatted: type: string fulfillmentMethodFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeTotalFormatted: type: string orderTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ orderTotalFormatted: type: string orderTotalWithServiceFee: type: string pattern: ^-?\d+(?:\.\d+)?$ orderTotalWithServiceFeeFormatted: type: string orderTotalWithServiceFeeAmount: type: integer minimum: 0 maximum: 9007199254740991 enterpriseFeeTotal: type: string pattern: ^-?\d+(?:\.\d+)?$ enterpriseFeeTotalFormatted: type: string subTotalWithoutDiscount: type: string pattern: ^-?\d+(?:\.\d+)?$ subTotalWithoutDiscountFormatted: type: string discountCode: type: string statementDescriptor: type: string totalQuantity: type: integer minimum: 0 maximum: 9007199254740991 items: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 128 productId: type: string minLength: 1 maxLength: 128 name: type: string description: type: string imageUrl: type: string price: type: string pattern: ^-?\d+(?:\.\d+)?$ priceFormatted: type: string quantity: type: integer minimum: 0 maximum: 9007199254740991 total: type: string pattern: ^-?\d+(?:\.\d+)?$ totalFormatted: type: string discount: type: string pattern: ^-?\d+(?:\.\d+)?$ discountFormatted: type: string categoryId: nullable: true type: string minLength: 1 maxLength: 128 specialInstructions: type: string itemUnavailableAction: type: string enum: - remove_item - cancel_entire_order selections: type: array items: {} product: type: object properties: id: type: string minLength: 1 maxLength: 128 name: type: string price: type: string pattern: ^-?\d+(?:\.\d+)?$ required: - id required: - id - productId - name - description - imageUrl - price - priceFormatted - quantity - total - totalFormatted - discount - discountFormatted - categoryId - itemUnavailableAction - selections additionalProperties: {} fees: type: object properties: enterpriseFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ enterpriseFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ serviceFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ taxRate: type: string pattern: ^-?\d+(?:\.\d+)?$ tipRate: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ fulfillmentMethodFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeRate: type: string pattern: ^-?\d+(?:\.\d+)?$ paymentProcessingFeeFix: type: string pattern: ^-?\d+(?:\.\d+)?$ required: - enterpriseFeeRate - enterpriseFeeFix - serviceFeeRate - serviceFeeFix - taxRate - tipRate - fulfillmentMethodFeeFix - fulfillmentMethodFeeRate - paymentProcessingFeeRate - paymentProcessingFeeFix additionalProperties: false deliveryInfo: nullable: true type: object properties: addressString: type: string addressData: type: object properties: street: type: string minLength: 1 streetOptional: default: '' type: string city: type: string minLength: 1 state: type: string minLength: 1 zipCode: type: string minLength: 1 country: type: string enum: - United States - United Arab Emirates - Australia - United Kingdom lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 required: - street - city - state - zipCode - country - lat - lng additionalProperties: false required: - addressString - addressData additionalProperties: {} tableServiceInfo: nullable: true type: object properties: tableNumber: type: string additionalProperties: {} roomServiceInfo: nullable: true type: object properties: lastName: type: string roomNumber: type: string additionalProperties: {} required: - id - locationId - merchantId - status - revision - expiresAt - restaurantDisplayName - fulfilmentMethod - fulfillmentIdentifier - pickupType - orderDate - orderTime - currency - subTotal - subTotalFormatted - discountTotal - discountTotalFormatted - waiterTipTotal - waiterTipTotalFormatted - taxTotal - taxTotalFormatted - taxAndFeeTotal - taxAndFeeTotalFormatted - serviceFeeTotal - serviceFeeTotalFormatted - paymentProcessingFeeTotal - paymentProcessingFeeTotalFormatted - applicationFeeTotal - applicationFeeTotalFormatted - netSalesTotal - netSalesTotalFormatted - fulfillmentMethodFeeTotal - fulfillmentMethodFeeTotalFormatted - orderTotal - orderTotalFormatted - orderTotalWithServiceFee - orderTotalWithServiceFeeFormatted - orderTotalWithServiceFeeAmount - enterpriseFeeTotal - enterpriseFeeTotalFormatted - subTotalWithoutDiscount - subTotalWithoutDiscountFormatted - statementDescriptor - totalQuantity - items - fees additionalProperties: false cartAccessToken: type: string required: - cart additionalProperties: false headers: ETag: description: >- Current resource revision tag. Send it in If-Match before mutation. schema: type: string Cache-Control: schema: type: string example: private, no-store '400': description: The request is invalid. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '401': description: Authentication or capability authorization is required. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '403': description: The authenticated principal does not own this resource. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '404': description: The requested resource was not found. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '409': description: The idempotency key or resource revision conflicts. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '428': description: A current If-Match resource revision is required. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '429': description: The request was rate limited. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '500': description: An unexpected error occurred. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' '503': description: A required dependency is temporarily unavailable. headers: X-Request-Id: description: Opaque request identifier for support and telemetry correlation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/CommerceErrorEnvelope' security: - {} - StorefrontCartCapability: [] - StorefrontCustomerAuth: [] - StorefrontCartCapability: [] StorefrontCustomerAuth: [] components: schemas: CommerceErrorEnvelope: type: object properties: code: anyOf: - type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - RATE_LIMITED - CART_CONFLICT - RESOURCE_CONFLICT - CART_IMMUTABLE - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_IN_PROGRESS - DEPENDENCY_UNAVAILABLE - INTERNAL_ERROR - type: string minLength: 1 message: type: string minLength: 1 requestId: type: string minLength: 8 details: type: object additionalProperties: {} required: - code - message - requestId additionalProperties: false securitySchemes: StorefrontCartCapability: type: apiKey in: header name: X-Cart-Token description: Purpose-limited capability returned for a guest cart. StorefrontCustomerAuth: type: http scheme: bearer bearerFormat: JWT description: Merchant-bound customer session JWT returned by OTP verification. ````