openapi: 3.1.0
info:
  title: Grubhub Deliveries Delivery Status API
  description: The Grubhub Deliveries API enables partners to manage delivery logistics and interact with Grubhub's nationwide courier network. It provides delivery status tracking through key states including driver assignment, pickup ready, and out for delivery. Partners can leverage Grubhub Connect, a full-service delivery solution for delivery aggregators, marketplaces, and enterprise merchants to fulfill orders using Grubhub drivers. The API also supports driver communication through proxy phone numbers.
  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
servers:
- url: https://api-third-party-gtm.grubhub.com
  description: Production Server
- url: https://api-third-party-gtm-pp.grubhub.com
  description: Preproduction Server
security:
- hmacAuth: []
tags:
- name: Delivery Status
  description: Endpoints for tracking delivery status, driver information, and estimated arrival times.
paths:
  /pos/v1/merchant/{merchant_long_id}/orders/{order_uuid}/delivery:
    get:
      operationId: getDeliveryStatus
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Delivery Status for an Order
      description: Retrieves the current state of a delivery for an order, including driver contact information, driver arrival ETAs, driver latitude and longitude coordinates, and delivery lifecycle state. Partners can use this to provide real-time delivery tracking to merchants.
      tags:
      - Delivery Status
      parameters:
      - $ref: '#/components/parameters/MerchantLongId'
      - $ref: '#/components/parameters/OrderUuid'
      responses:
        '200':
          description: Current delivery status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delivery'
              examples:
                GetDeliveryStatus200Example:
                  summary: Default getDeliveryStatus 200 response
                  x-microcks-default: true
                  value:
                    order_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    status: PENDING
                    driver:
                      name: Sample Name
                      phone: '+13125550142'
                      delivery_method: CAR
                      latitude: 41.8781
                      longitude: -87.6298
                    pickup_eta: '2026-06-02T18:30:00Z'
                    dropoff_eta: '2026-06-02T18:30:00Z'
                    tracking_url: https://developer.grubhub.com
                    updated_at: '2026-06-02T18:30:00Z'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetDeliveryStatus401Example:
                  summary: Default getDeliveryStatus 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
        '404':
          description: Order or delivery not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetDeliveryStatus404Example:
                  summary: Default getDeliveryStatus 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
components:
  schemas:
    Driver:
      type: object
      description: Information about the assigned delivery driver.
      properties:
        name:
          type: string
          description: The driver's display name.
          example: Sample Name
        phone:
          type: string
          description: The driver's contact phone number.
          example: '+13125550142'
        delivery_method:
          type: string
          description: The method of delivery being used by the driver.
          enum:
          - CAR
          - BIKE
          - WALKING
          example: CAR
        latitude:
          type: number
          format: double
          description: The driver's current latitude coordinate.
          example: 41.8781
        longitude:
          type: number
          format: double
          description: The driver's current longitude coordinate.
          example: -87.6298
    Delivery:
      type: object
      description: The current state of a delivery including driver and tracking details.
      properties:
        order_uuid:
          type: string
          format: uuid
          description: The UUID of the associated order.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status:
          type: string
          description: The current lifecycle status of the delivery.
          enum:
          - PENDING
          - DRIVER_ASSIGNED
          - DRIVER_EN_ROUTE_TO_PICKUP
          - ARRIVED_AT_PICKUP
          - PICKED_UP
          - OUT_FOR_DELIVERY
          - ARRIVED_AT_DROPOFF
          - DELIVERED
          - CANCELLED
          example: PENDING
        driver:
          $ref: '#/components/schemas/Driver'
        pickup_eta:
          type: string
          format: date-time
          description: Estimated time of arrival at the pickup location.
          example: '2026-06-02T18:30:00Z'
        dropoff_eta:
          type: string
          format: date-time
          description: Estimated time of arrival at the delivery location.
          example: '2026-06-02T18:30:00Z'
        tracking_url:
          type: string
          format: uri
          description: A URL providing real-time delivery status updates, courier tracking, courier name, and contact options.
          example: https://developer.grubhub.com
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last delivery status update.
          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
  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
  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.
externalDocs:
  description: Grubhub Deliveries API Documentation
  url: https://developer.grubhub.com/api/deliveries