grubhub Merchants API

openapi: 3.1.0
info:
  title: Grubhub Deliveries Delivery Status Merchants 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: Merchants
  description: Endpoints for retrieving merchant information and ID mappings.
paths:
  /pos/v1/merchants:
    get:
      operationId: listMerchants
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub List Partner Merchants
      description: Returns the internal and external merchant ID mappings associated with your partner_id. Use this endpoint to discover all Grubhub locations linked to your partner account.
      tags:
      - Merchants
      responses:
        '200':
          description: List of merchant ID mappings
          content:
            application/json:
              schema:
                type: object
                properties:
                  merchants:
                    type: array
                    description: List of merchant ID mappings.
                    items:
                      $ref: '#/components/schemas/MerchantMapping'
              examples:
                ListMerchants200Example:
                  summary: Default listMerchants 200 response
                  x-microcks-default: true
                  value:
                    merchants:
                    - merchant_id: ghm-1234567890
                      external_id: id-1234567890
                      name: Sample Name
                      status: ONLINE
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ListMerchants401Example:
                  summary: Default listMerchants 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_id}:
    get:
      operationId: getMerchant
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Merchant Summary
      description: Returns summary information about a merchant including store details, address, and configuration.
      tags:
      - Merchants
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Merchant summary information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant'
              examples:
                GetMerchant200Example:
                  summary: Default getMerchant 200 response
                  x-microcks-default: true
                  value:
                    merchant_id: ghm-1234567890
                    external_id: id-1234567890
                    name: Sample Name
                    address:
                      street_address: 111 W Washington St
                      city: Chicago
                      state: IL
                      zip: '60602'
                      latitude: 41.8781
                      longitude: -87.6298
                    phone: '+13125550142'
                    status: ONLINE
                    tax_rate: 1.25
                    fulfillment_types:
                    - DELIVERY
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetMerchant401Example:
                  summary: Default getMerchant 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:
                GetMerchant404Example:
                  summary: Default getMerchant 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
components:
  schemas:
    MerchantMapping:
      type: object
      description: Mapping between internal Grubhub merchant IDs and external partner merchant IDs.
      properties:
        merchant_id:
          type: string
          description: The Grubhub internal merchant identifier.
          example: ghm-1234567890
        external_id:
          type: string
          description: The partner's external merchant identifier.
          example: id-1234567890
        name:
          type: string
          description: The merchant's display name.
          example: Sample Name
        status:
          type: string
          description: The current status of the merchant.
          enum:
          - ONLINE
          - OFFLINE
          example: ONLINE
    Address:
      type: object
      description: A physical address.
      properties:
        street_address:
          type: string
          description: The street address line.
          example: 111 W Washington St
        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
    Merchant:
      type: object
      description: Summary information about a merchant on Grubhub.
      properties:
        merchant_id:
          type: string
          description: The Grubhub internal merchant identifier.
          example: ghm-1234567890
        external_id:
          type: string
          description: The partner's external merchant identifier.
          example: id-1234567890
        name:
          type: string
          description: The merchant's display name.
          example: Sample Name
        address:
          $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: The merchant's phone number.
          example: '+13125550142'
        status:
          type: string
          description: The current online/offline status.
          enum:
          - ONLINE
          - OFFLINE
          example: ONLINE
        tax_rate:
          type: number
          format: double
          description: The merchant's applicable tax rate.
          example: 1.25
        fulfillment_types:
          type: array
          description: Supported fulfillment types for this merchant.
          items:
            type: string
            enum:
            - DELIVERY
            - PICKUP
            - CATERING
    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:
    MerchantId:
      name: merchant_id
      in: path
      required: true
      description: The unique identifier for the merchant on Grubhub.
      schema:
        type: string
  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