> ## 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.

# Start an ordering session

> Creates or resumes a cart for the given location. The response includes the cart ID or an error message explaining why ordering is unavailable.



## OpenAPI

````yaml https://api.craveup.com/swagger.json post /locations/{locationId}/ordering-sessions
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: <your-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}/ordering-sessions:
    post:
      tags:
        - Ordering Sessions
      summary: Start an ordering session
      description: >-
        Creates or resumes a cart for the given location. The response includes
        the cart ID or an error message explaining why ordering is unavailable.
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
          example: loc_456def
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                marketplaceId:
                  type: string
                  nullable: true
                  example: web
                  description: >-
                    Optional identifier describing the sales channel initiating
                    the session.
                fulfillmentMethod:
                  type: string
                  example: pickup
                  description: >-
                    Fulfillment method requested by the shopper (for example
                    `pickup`, `delivery`).
                existingCartId:
                  type: string
                  nullable: true
                  example: cart_123
                  description: >-
                    Resume an existing cart when provided. If not found, a new
                    cart is created.
                metadata:
                  type: object
                  additionalProperties: true
                  nullable: true
                  example:
                    referrer: homepage
                  description: >-
                    Arbitrary metadata to persist on the cart. Keys must be
                    strings.
                returnUrl:
                  type: string
                  nullable: true
                  example: https://yourapp.com/checkout/success
                  description: >-
                    URL to redirect the shopper after a hosted checkout flow
                    finishes.
              required:
                - fulfillmentMethod
            examples:
              default:
                summary: Start a pickup session
                value:
                  fulfillmentMethod: pickup
                  marketplaceId: web
                  metadata:
                    channel: qr
      responses:
        '201':
          description: Ordering session created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cartId:
                    type: string
                    nullable: true
                    example: cart_123
                    description: ID of the active cart. Null when ordering is unavailable.
                  errorMessage:
                    type: string
                    example: ''
                    description: >-
                      Message describing why ordering is unavailable. Empty
                      string on success.
        '400':
          description: >-
            Request payload failed validation (for example, unsupported
            fulfillment method).
          content:
            application/json:
              schema:
                $ref: f416995b-c862-451d-955a-4847d577cf10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/GenericError'
      security:
        - ApiKeyAuth: []
components:
  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
    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

````