openapi: 3.1.0
info:
  title: MealMe Food Ordering Carts Orders API
  version: 4.1.0
  description: 'MealMe provides a food and grocery ordering API for menus, inventory, and

    order placement at over one million restaurants and grocery stores in the

    United States and Canada. The API covers store and product search, store

    lookup, inventory/menu retrieval, product details, cart creation and

    management, order creation and finalization, payment methods, MealMe

    Connect accounts, customer support chat, order tracking webhooks, places

    search, and geocoding. Every menu item and grocery product returned

    includes real-time availability, prices, and customizations or modifiers.

    The current reference is version 4.1.0.


    Paths in this specification mirror the documented MealMe endpoints under

    https://api.mealme.ai (for example `/search/store/v3`, `/cart/create`,

    and `/order/order/v4`). Authentication uses an API key passed in the

    Authorization header.

    '
  contact:
    name: MealMe API Reference
    url: https://docs.mealme.ai/reference
servers:
- url: https://api.mealme.ai
  description: MealMe production API
security:
- apiKeyHeader: []
tags:
- name: Orders
  description: Order creation, finalization, and history.
paths:
  /order/order/v4:
    post:
      tags:
      - Orders
      operationId: createOrder
      summary: Create an Order
      description: 'Create an order from a list of items. When place_order is false the

        response returns a finalizable quote; when true the order is placed.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
            examples:
              CreateOrderRequestExample:
                summary: Default createOrder request
                x-microcks-default: true
                value:
                  place_order: false
                  order_id: ord_8f2a1c9b
                  items:
                  - product_id: prod_5a3e9d12
                    quantity: 1
                    product_marked_price: 1299
                    selected_options: []
                    notes: Leave at the front desk
                  pickup: false
                  scheduled_id: id_7b2c4e
                  driver_tip_cents: 1299
                  pickup_tip_cents: 1299
                  user_latitude: 37.7786357
                  user_longitude: -122.3918135
                  user_street_num: '188'
                  user_street_name: King Street
                  user_apt_num: example
                  user_city: San Francisco
                  user_state: CA
                  user_country: US
                  user_zipcode: '94107'
                  user_dropoff_notes: Leave at the front desk
                  user_pickup_notes: Leave at the front desk
                  user_name: Steve Jobs
                  user_email: diner@example.com
                  user_phone: 14155550123
                  user_id: user_abc123
                  payment_method_id: id_7b2c4e
                  charge_user: false
                  include_final_quote: false
                  disable_sms: false
                  customer_order_id: id_7b2c4e
                  metadata: {}
                  tracking_link: https://example.com/webhook
      responses:
        '200':
          description: Order created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                CreateOrder200Example:
                  summary: Default createOrder 200 response
                  x-microcks-default: true
                  value:
                    order_id: ord_8f2a1c9b
                    cart_id: kQ8vZEd-UnW_gZu6c4iO
                    status: unplaced
                    total: 1299
        '202':
          description: Order accepted.
        '400':
          description: Input Validation Error
        '401':
          description: Missing Authorization
        '406':
          description: Not Acceptable
        '422':
          description: Unprocessable Entity
        '504':
          description: Gateway Timeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /order/finalize:
    post:
      tags:
      - Orders
      operationId: finalizeOrder
      summary: Finalize an Order
      description: Finalize a previously created order quote (place_order=false).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - order_id
              properties:
                order_id:
                  type: string
            examples:
              FinalizeOrderRequestExample:
                summary: Default finalizeOrder request
                x-microcks-default: true
                value:
                  order_id: ord_8f2a1c9b
      responses:
        '200':
          description: Order finalized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                FinalizeOrder200Example:
                  summary: Default finalizeOrder 200 response
                  x-microcks-default: true
                  value:
                    order_id: ord_8f2a1c9b
                    cart_id: kQ8vZEd-UnW_gZu6c4iO
                    status: unplaced
                    total: 1299
        '400':
          description: Input Validation Error
        '401':
          description: Missing Authorization
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /account/orders:
    get:
      tags:
      - Orders
      operationId: getOrders
      summary: Get Orders
      description: Retrieve account orders with optional filters.
      parameters:
      - in: query
        name: order_id
        schema:
          type: string
        example: ord_8f2a1c9b
      - in: query
        name: start_date
        schema:
          type: string
        example: example
      - in: query
        name: end_date
        schema:
          type: string
        example: example
      - in: query
        name: status
        schema:
          type: string
        example: completed
      - in: query
        name: favorited
        schema:
          type: boolean
        example: false
      - in: query
        name: user_id
        schema:
          type: string
        example: user_abc123
      - in: query
        name: include_order_count
        schema:
          type: boolean
        example: false
      - in: query
        name: page
        schema:
          type: integer
          default: 0
        example: 0
      responses:
        '200':
          description: Orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
              examples:
                GetOrders200Example:
                  summary: Default getOrders 200 response
                  x-microcks-default: true
                  value:
                  - order_id: ord_8f2a1c9b
                    cart_id: kQ8vZEd-UnW_gZu6c4iO
                    status: unplaced
                    total: 1299
        '401':
          description: Missing Authorization
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CartItem:
      type: object
      required:
      - product_id
      properties:
        product_id:
          type: string
          description: Product identifier from a search or inventory result.
          example: prod_5a3e9d12
        quantity:
          type: integer
          minimum: 1
          default: 1
          example: 1
        product_marked_price:
          type: integer
          description: Marked price in cents.
          example: 1299
        selected_options:
          type: array
          description: Selected product customizations and modifiers.
          items:
            type: object
          example: []
        notes:
          type: string
          description: Special instructions for the store.
          example: Leave at the front desk
    OrderRequest:
      type: object
      required:
      - items
      - pickup
      - user_name
      - user_email
      - user_phone
      - user_id
      properties:
        place_order:
          type: boolean
          description: When false, returns a finalizable quote rather than placing.
          example: false
        order_id:
          type: string
          example: ord_8f2a1c9b
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        pickup:
          type: boolean
          example: false
        scheduled_id:
          type: string
          example: id_7b2c4e
        driver_tip_cents:
          type: integer
          example: 1299
        pickup_tip_cents:
          type: integer
          example: 1299
        user_latitude:
          type: number
          example: 37.7786357
        user_longitude:
          type: number
          example: -122.3918135
        user_street_num:
          type: string
          example: '188'
        user_street_name:
          type: string
          example: King Street
        user_apt_num:
          type: string
          example: example
        user_city:
          type: string
          example: San Francisco
        user_state:
          type: string
          example: CA
        user_country:
          type: string
          enum:
          - US
          - CA
          example: US
        user_zipcode:
          type: string
          example: '94107'
        user_dropoff_notes:
          type: string
          example: Leave at the front desk
        user_pickup_notes:
          type: string
          example: Leave at the front desk
        user_name:
          type: string
          example: Steve Jobs
        user_email:
          type: string
          format: email
          example: diner@example.com
        user_phone:
          type: integer
          example: 14155550123
        user_id:
          type: string
          example: user_abc123
        payment_method_id:
          type: string
          example: id_7b2c4e
        charge_user:
          type: boolean
          example: false
        include_final_quote:
          type: boolean
          example: false
        disable_sms:
          type: boolean
          example: false
        customer_order_id:
          type: string
          example: id_7b2c4e
        metadata:
          type: object
          example: {}
        tracking_link:
          type: string
          example: https://example.com/webhook
    Order:
      type: object
      properties:
        order_id:
          type: string
          example: ord_8f2a1c9b
        cart_id:
          type: string
          example: kQ8vZEd-UnW_gZu6c4iO
        status:
          type: string
          enum:
          - unplaced
          - awaiting_confirmation
          - in_progress
          - canceled
          - completed
          example: unplaced
        total:
          type: integer
          description: Total in cents.
          example: 1299
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: API key issued by MealMe, passed in the Authorization header.