Grubhub Orders API

openapi: 3.1.0
info:
  title: Grubhub Orders API
  description: >-
    The Grubhub Orders API allows partners to receive, manage, and update
    order statuses for restaurant orders placed through the Grubhub
    Marketplace. Partners can retrieve individual orders by UUID, list
    orders by status and date range, confirm orders with estimated wait
    times, and update order lifecycle states. New orders are primarily
    received through webhook subscriptions, with polling available as
    a fallback.
  version: '1.0.0'
  x-last-validated: '2026-06-02'
  contact:
    name: Grubhub Developer Support
    url: https://grubhub-developers.zendesk.com/hc/en-us
  termsOfService: https://www.grubhub.com/legal/terms-of-use
externalDocs:
  description: Grubhub Orders API Documentation
  url: https://developer.grubhub.com/api/orders
servers:
- url: https://api-third-party-gtm.grubhub.com
  description: Production Server
- url: https://api-third-party-gtm-pp.grubhub.com
  description: Preproduction Server
tags:
- name: Order Change Requests
  description: >-
    Endpoints for managing order change requests and modifications.
- name: Order Polling
  description: >-
    Endpoints for polling orders across multiple merchants. Webhook
    subscription is the preferred method for receiving new orders.
- name: Order Status
  description: >-
    Endpoints for confirming orders and updating order lifecycle states.
- name: Orders
  description: >-
    Endpoints for retrieving and managing orders placed through the
    Grubhub Marketplace.
security:
- hmacAuth: []
paths:
  /pos/v1/merchant/{merchant_long_id}/orders/{order_uuid}:
    get:
      operationId: getOrder
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get a Single Order
      description: >-
        Returns a single order requested by its UUID for the specified
        merchant. Includes complete order details such as items, totals,
        delivery information, and current status.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - $ref: '#/components/parameters/OrderUuid'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                GetOrder200Example:
                  summary: Default getOrder 200 response
                  x-microcks-default: true
                  value:
                    order_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    merchant_id: ghm-1234567890
                    status: PENDING
                    placed_at: '2026-06-02T18:30:00Z'
                    estimated_delivery_at: '2026-06-02T18:30:00Z'
                    fulfillment_type: DELIVERY
                    customer:
                      first_name: Jordan
                      last_name: Rivera
                      phone: '+13125550142'
                    items:
                    - item_id: id-1234567890
                      name: Sample Name
                      quantity: 1
                      price: 9.99
                      modifiers:
                      - name: {}
                        price: {}
                      special_instructions: Leave at the front desk.
                    totals:
                      subtotal: 18.5
                      tax: 1.25
                      delivery_fee: 2.99
                      tip: 3.0
                      total: 25.74
                    delivery_address:
                      street_address: 111 W Washington St
                      apt_suite: Suite 2100
                      city: Chicago
                      state: IL
                      zip: '60602'
                      latitude: 41.8781
                      longitude: -87.6298
                    special_instructions: Leave at the front desk.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetOrder401Example:
                  summary: Default getOrder 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetOrder404Example:
                  summary: Default getOrder 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_long_id}/orders:
    get:
      operationId: listMerchantOrders
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub List Orders for a Merchant
      description: >-
        Returns the list of orders for the requested merchant in a given
        status and date range. Useful for retrieving historical orders
        or checking orders in specific lifecycle states.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - name: status
        in: query
        description: >-
          Filter orders by their current status.
        schema:
          type: string
          enum:
          - PENDING
          - CONFIRMED
          - IN_PROGRESS
          - READY
          - COMPLETED
          - CANCELLED
        example: PENDING
      - name: start_date
        in: query
        description: >-
          Start of the date range filter in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-06-02T18:30:00Z'
      - name: end_date
        in: query
        description: >-
          End of the date range filter in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-06-02T18:30:00Z'
      responses:
        '200':
          description: List of orders matching criteria
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    description: >-
                      List of orders matching the specified criteria.
                    items:
                      $ref: '#/components/schemas/Order'
              examples:
                ListMerchantOrders200Example:
                  summary: Default listMerchantOrders 200 response
                  x-microcks-default: true
                  value:
                    orders:
                    - order_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      merchant_id: ghm-1234567890
                      status: PENDING
                      placed_at: '2026-06-02T18:30:00Z'
                      estimated_delivery_at: '2026-06-02T18:30:00Z'
                      fulfillment_type: DELIVERY
                      customer:
                        first_name: Jordan
                        last_name: Rivera
                        phone: '+13125550142'
                      items:
                      - item_id: {}
                        name: {}
                        quantity: {}
                        price: {}
                        modifiers: {}
                        special_instructions: {}
                      totals:
                        subtotal: 18.5
                        tax: 1.25
                        delivery_fee: 2.99
                        tip: 3.0
                        total: 25.74
                      delivery_address:
                        street_address: 111 W Washington St
                        apt_suite: Suite 2100
                        city: Chicago
                        state: IL
                        zip: '60602'
                        latitude: 41.8781
                        longitude: -87.6298
                      special_instructions: Leave at the front desk.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ListMerchantOrders401Example:
                  summary: Default listMerchantOrders 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Merchant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ListMerchantOrders404Example:
                  summary: Default listMerchantOrders 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/orders/poll:
    get:
      operationId: pollOrders
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Poll Orders Across Merchants
      description: >-
        Returns all orders for a group of merchants in a given state
        within the given time range. This is a fallback mechanism;
        new orders should primarily be received through webhook
        subscriptions rather than periodic polling.
      tags:
      - Order Polling
      parameters:
      - name: status
        in: query
        description: >-
          Filter orders by their current status.
        schema:
          type: string
        example: ACTIVE
      - name: start_date
        in: query
        description: >-
          Start of the date range filter in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-06-02T18:30:00Z'
      - name: end_date
        in: query
        description: >-
          End of the date range filter in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-06-02T18:30:00Z'
      responses:
        '200':
          description: List of orders matching criteria
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    description: >-
                      List of orders matching the specified criteria.
                    items:
                      $ref: '#/components/schemas/Order'
              examples:
                PollOrders200Example:
                  summary: Default pollOrders 200 response
                  x-microcks-default: true
                  value:
                    orders:
                    - order_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      merchant_id: ghm-1234567890
                      status: PENDING
                      placed_at: '2026-06-02T18:30:00Z'
                      estimated_delivery_at: '2026-06-02T18:30:00Z'
                      fulfillment_type: DELIVERY
                      customer:
                        first_name: Jordan
                        last_name: Rivera
                        phone: '+13125550142'
                      items:
                      - item_id: {}
                        name: {}
                        quantity: {}
                        price: {}
                        modifiers: {}
                        special_instructions: {}
                      totals:
                        subtotal: 18.5
                        tax: 1.25
                        delivery_fee: 2.99
                        tip: 3.0
                        total: 25.74
                      delivery_address:
                        street_address: 111 W Washington St
                        apt_suite: Suite 2100
                        city: Chicago
                        state: IL
                        zip: '60602'
                        latitude: 41.8781
                        longitude: -87.6298
                      special_instructions: Leave at the front desk.
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PollOrders401Example:
                  summary: Default pollOrders 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_long_id}/orders/{order_uuid}/confirm:
    post:
      operationId: confirmOrder
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Confirm an Order
      description: >-
        Confirms an order that has been received. All orders that can be
        fulfilled are required to be confirmed. Partners can optionally
        indicate an estimated delivery time using wait_time_in_minutes
        in the request body.
      tags:
      - Order Status
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - $ref: '#/components/parameters/OrderUuid'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderConfirmation'
            examples:
              ConfirmOrderRequestExample:
                summary: Default confirmOrder request
                x-microcks-default: true
                value:
                  wait_time_in_minutes: 15
      responses:
        '200':
          description: Order confirmed successfully
        '400':
          description: Invalid confirmation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ConfirmOrder400Example:
                  summary: Default confirmOrder 400 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ConfirmOrder401Example:
                  summary: Default confirmOrder 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ConfirmOrder404Example:
                  summary: Default confirmOrder 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_long_id}/orders/{order_uuid}/status:
    put:
      operationId: updateOrderStatus
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Update Order Status
      description: >-
        Updates the status of an order through its lifecycle states.
        Partners use this endpoint to mark orders as in progress, ready
        for pickup, out for delivery, or completed.
      tags:
      - Order Status
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - $ref: '#/components/parameters/OrderUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatusUpdate'
            examples:
              UpdateOrderStatusRequestExample:
                summary: Default updateOrderStatus request
                x-microcks-default: true
                value:
                  status: IN_PROGRESS
                  reason: Out of an item.
      responses:
        '200':
          description: Order status updated successfully
        '400':
          description: Invalid status transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrderStatus400Example:
                  summary: Default updateOrderStatus 400 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrderStatus401Example:
                  summary: Default updateOrderStatus 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrderStatus404Example:
                  summary: Default updateOrderStatus 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_long_id}/orders/{order_uuid}/changerequests:
    get:
      operationId: getOrderChangeRequests
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Order Change Requests
      description: >-
        Returns the status of order change requests for a specific order.
        Change requests may include modifications to items, quantities,
        or special instructions.
      tags:
      - Order Change Requests
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - $ref: '#/components/parameters/OrderUuid'
      responses:
        '200':
          description: List of change requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  change_requests:
                    type: array
                    description: >-
                      List of change requests for this order.
                    items:
                      $ref: '#/components/schemas/OrderChangeRequest'
              examples:
                GetOrderChangeRequests200Example:
                  summary: Default getOrderChangeRequests 200 response
                  x-microcks-default: true
                  value:
                    change_requests:
                    - id: id-1234567890
                      status: PENDING
                      type: STANDARD
                      details: string
                      created_at: '2026-06-02T18:30:00Z'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetOrderChangeRequests401Example:
                  summary: Default getOrderChangeRequests 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetOrderChangeRequests404Example:
                  summary: Default getOrderChangeRequests 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
components:
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        HMAC-based authentication. Every request must include X-GH-PARTNER-KEY
        and an Authorization header with MAC authentication details.
  parameters:
    MerchantLongId:
      name: merchant_long_id
      in: path
      required: true
      description: >-
        The long-form unique identifier for the merchant on Grubhub.
      schema:
        type: string
    OrderUuid:
      name: order_uuid
      in: path
      required: true
      description: >-
        The UUID of the order.
      schema:
        type: string
        format: uuid
  schemas:
    Order:
      type: object
      description: >-
        A complete order placed through the Grubhub Marketplace.
      properties:
        order_uuid:
          type: string
          format: uuid
          description: >-
            The unique identifier for the order.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        merchant_id:
          type: string
          description: >-
            The merchant identifier this order was placed with.
          example: ghm-1234567890
        status:
          type: string
          description: >-
            The current lifecycle status of the order.
          enum:
          - PENDING
          - CONFIRMED
          - IN_PROGRESS
          - READY
          - OUT_FOR_DELIVERY
          - COMPLETED
          - CANCELLED
          example: PENDING
        placed_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the order was placed.
          example: '2026-06-02T18:30:00Z'
        estimated_delivery_at:
          type: string
          format: date-time
          description: >-
            The estimated delivery time for the order.
          example: '2026-06-02T18:30:00Z'
        fulfillment_type:
          type: string
          description: >-
            The type of fulfillment for this order.
          enum:
          - DELIVERY
          - PICKUP
          example: DELIVERY
        customer:
          $ref: '#/components/schemas/Customer'
        items:
          type: array
          description: >-
            The items included in this order.
          items:
            $ref: '#/components/schemas/OrderItem'
        totals:
          $ref: '#/components/schemas/OrderTotals'
        delivery_address:
          $ref: '#/components/schemas/Address'
        special_instructions:
          type: string
          description: >-
            Special instructions provided by the customer.
          example: Leave at the front desk.
    Customer:
      type: object
      description: >-
        Customer information associated with an order.
      properties:
        first_name:
          type: string
          description: >-
            The customer's first name.
          example: Jordan
        last_name:
          type: string
          description: >-
            The customer's last name.
          example: Rivera
        phone:
          type: string
          description: >-
            The customer's phone number.
          example: '+13125550142'
    OrderItem:
      type: object
      description: >-
        An individual item within an order.
      properties:
        item_id:
          type: string
          description: >-
            The unique identifier for the menu item.
          example: id-1234567890
        name:
          type: string
          description: >-
            The display name of the item.
          example: Sample Name
        quantity:
          type: integer
          description: >-
            The quantity ordered.
          minimum: 1
          example: 1
        price:
          type: number
          format: double
          description: >-
            The unit price of the item.
          example: 9.99
        modifiers:
          type: array
          description: >-
            Modifiers applied to this item.
          items:
            type: object
            properties:
              name:
                type: string
                description: >-
                  The name of the modifier.
              price:
                type: number
                format: double
                description: >-
                  The additional price for this modifier.
        special_instructions:
          type: string
          description: >-
            Item-level special instructions.
          example: Leave at the front desk.
    OrderTotals:
      type: object
      description: >-
        Financial totals for an order.
      properties:
        subtotal:
          type: number
          format: double
          description: >-
            The subtotal before taxes and fees.
          example: 18.5
        tax:
          type: number
          format: double
          description: >-
            The tax amount.
          example: 1.25
        delivery_fee:
          type: number
          format: double
          description: >-
            The delivery fee charged.
          example: 2.99
        tip:
          type: number
          format: double
          description: >-
            The tip amount.
          example: 3.0
        total:
          type: number
          format: double
          description: >-
            The total amount for the order.
          example: 25.74
    Address:
      type: object
      description: >-
        A physical address.
      properties:
        street_address:
          type: string
          description: >-
            The street address line.
          example: 111 W Washington St
        apt_suite:
          type: string
          description: >-
            Apartment or suite number.
          example: Suite 2100
        city:
          type: string
          description: >-
            The city name.
          example: Chicago
        state:
          type: string
          description: >-
            The state abbreviation.
          example: IL
        zip:
          type: string
          description: >-
            The ZIP code.
          example: '60602'
        latitude:
          type: number
          format: double
          description: >-
            The latitude coordinate.
          example: 41.8781
        longitude:
          type: number
          format: double
          description: >-
            The longitude coordinate.
          example: -87.6298
    OrderConfirmation:
      type: object
      description: >-
        Payload for confirming an order, with optional wait time estimate.
      properties:
        wait_time_in_minutes:
          type: integer
          description: >-
            Estimated number of minutes until the order will be ready
            for delivery or pickup.
          minimum: 1
          example: 15
    OrderStatusUpdate:
      type: object
      description: >-
        Payload for updating an order's lifecycle status.
      required:
      - status
      properties:
        status:
          type: string
          description: >-
            The new status for the order.
          enum:
          - IN_PROGRESS
          - READY
          - OUT_FOR_DELIVERY
          - COMPLETED
          - CANCELLED
          example: IN_PROGRESS
        reason:
          type: string
          description: >-
            Reason for the status change, particularly relevant for
            cancellations.
          example: Out of an item.
    OrderChangeRequest:
      type: object
      description: >-
        A change request for an existing order.
      properties:
        id:
          type: string
          description: >-
            The unique identifier for the change request.
          example: id-1234567890
        status:
          type: string
          description: >-
            The current status of the change request.
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          example: PENDING
        type:
          type: string
          description: >-
            The type of change being requested.
          example: STANDARD
        details:
          type: string
          description: >-
            Details about the requested change.
          example: string
        created_at:
          type: string
          format: date-time
          description: >-
            When the change request was created.
          example: '2026-06-02T18:30:00Z'
    Error:
      type: object
      description: >-
        Standard error response from the Grubhub API.
      properties:
        error:
          type: string
          description: >-
            Error type identifier.
          example: invalid_request
        message:
          type: string
          description: >-
            Human-readable error description.
          example: Operation completed successfully.
        status:
          type: integer
          description: >-
            HTTP status code.
          example: 0