openapi: 3.1.0
info:
  title: Grubhub Deliveries Delivery Status Merchant Onboarding 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: Merchant Onboarding
  description: Endpoints for onboarding merchants to the Grubhub platform, including referrals, activation, and association.
paths:
  /pos/v1/onboarding/referral:
    post:
      operationId: createMerchantReferral
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Create a New Merchant Referral
      description: Sends over the details of a new merchant for onboarding them to Grubhub. This initiates the merchant onboarding process and can significantly reduce the time to get a merchant live on the platform.
      tags:
      - Merchant Onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantReferral'
            examples:
              CreateMerchantReferralRequestExample:
                summary: Default createMerchantReferral request
                x-microcks-default: true
                value:
                  business_name: string
                  address:
                    street_address: 111 W Washington St
                    city: Chicago
                    state: IL
                    zip: '60602'
                  contact:
                    name: Sample Name
                    email: partner@example.com
                    phone: '+13125550142'
                  external_id: id-1234567890
                  cuisine_types:
                  - string
      responses:
        '201':
          description: Merchant referral created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResponse'
              examples:
                CreateMerchantReferral201Example:
                  summary: Default createMerchantReferral 201 response
                  x-microcks-default: true
                  value:
                    referral_id: id-1234567890
                    merchant_id: ghm-1234567890
                    status: PENDING
        '400':
          description: Invalid referral data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CreateMerchantReferral400Example:
                  summary: Default createMerchantReferral 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:
                CreateMerchantReferral401Example:
                  summary: Default createMerchantReferral 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/onboarding/activate:
    post:
      operationId: activateMerchant
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Activate a Merchant
      description: Activates a merchant for integration with the partner, enabling the merchant to receive orders through the partner's system on the Grubhub platform.
      tags:
      - Merchant Onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantActivationRequest'
            examples:
              ActivateMerchantRequestExample:
                summary: Default activateMerchant request
                x-microcks-default: true
                value:
                  merchant_id: ghm-1234567890
      responses:
        '200':
          description: Merchant activated successfully
        '400':
          description: Invalid activation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ActivateMerchant400Example:
                  summary: Default activateMerchant 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:
                ActivateMerchant401Example:
                  summary: Default activateMerchant 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:
                ActivateMerchant404Example:
                  summary: Default activateMerchant 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/onboarding/deactivate:
    post:
      operationId: deactivateMerchant
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Deactivate a Merchant
      description: Validates a merchant and removes its association with the partner. The deactivation request uses partner authentication to identify the calling partner.
      tags:
      - Merchant Onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantDeactivationRequest'
            examples:
              DeactivateMerchantRequestExample:
                summary: Default deactivateMerchant request
                x-microcks-default: true
                value:
                  merchant_id: ghm-1234567890
                  reason: Out of an item.
      responses:
        '200':
          description: Merchant deactivated successfully
        '400':
          description: Invalid deactivation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DeactivateMerchant400Example:
                  summary: Default deactivateMerchant 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:
                DeactivateMerchant401Example:
                  summary: Default deactivateMerchant 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:
                DeactivateMerchant404Example:
                  summary: Default deactivateMerchant 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/onboarding/deactivate/partner:
    post:
      operationId: deactivateMerchantPartner
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Deactivate a Merchant (partner Auth)
      description: Deactivates a merchant using partner-level authentication. Validates the merchant and removes its association with the partner account.
      tags:
      - Merchant Onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantDeactivationRequest'
            examples:
              DeactivateMerchantPartnerRequestExample:
                summary: Default deactivateMerchantPartner request
                x-microcks-default: true
                value:
                  merchant_id: ghm-1234567890
                  reason: Out of an item.
      responses:
        '200':
          description: Merchant deactivated successfully
        '400':
          description: Invalid deactivation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DeactivateMerchantPartner400Example:
                  summary: Default deactivateMerchantPartner 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:
                DeactivateMerchantPartner401Example:
                  summary: Default deactivateMerchantPartner 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:
                DeactivateMerchantPartner404Example:
                  summary: Default deactivateMerchantPartner 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/onboarding/associate:
    post:
      operationId: associateMerchants
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Associate Merchants with Partner
      description: Binds provided merchants to the partner for onboarding. Associates a list of merchant IDs with the partner account, enabling the partner to manage these merchants through the API.
      tags:
      - Merchant Onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantAssociationRequest'
            examples:
              AssociateMerchantsRequestExample:
                summary: Default associateMerchants request
                x-microcks-default: true
                value:
                  merchant_ids:
                  - string
      responses:
        '200':
          description: Merchants associated successfully
        '400':
          description: Invalid association request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                AssociateMerchants400Example:
                  summary: Default associateMerchants 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:
                AssociateMerchants401Example:
                  summary: Default associateMerchants 401 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
components:
  schemas:
    MerchantAssociationRequest:
      type: object
      description: Request to associate merchants with the partner.
      required:
      - merchant_ids
      properties:
        merchant_ids:
          type: array
          description: List of merchant IDs to associate with the partner.
          items:
            type: string
          minItems: 1
    MerchantDeactivationRequest:
      type: object
      description: Request to deactivate a merchant and remove partner association.
      required:
      - merchant_id
      properties:
        merchant_id:
          type: string
          description: The Grubhub merchant identifier to deactivate.
          example: ghm-1234567890
        reason:
          type: string
          description: Reason for deactivating the merchant.
          example: Out of an item.
    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.
          maxLength: 2
          example: IL
        zip:
          type: string
          description: The ZIP code.
          pattern: ^\d{5}(-\d{4})?$
          example: '60602'
    ReferralResponse:
      type: object
      description: Response after successfully creating a merchant referral.
      properties:
        referral_id:
          type: string
          description: The unique identifier for this referral.
          example: id-1234567890
        merchant_id:
          type: string
          description: The assigned Grubhub merchant identifier.
          example: ghm-1234567890
        status:
          type: string
          description: The current status of the referral.
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          example: PENDING
    Contact:
      type: object
      description: Contact information for a merchant.
      properties:
        name:
          type: string
          description: The contact person's name.
          example: Sample Name
        email:
          type: string
          format: email
          description: The contact email address.
          example: partner@example.com
        phone:
          type: string
          description: The contact phone number.
          example: '+13125550142'
    MerchantReferral:
      type: object
      description: Details of a new merchant being referred for onboarding.
      required:
      - business_name
      - address
      - contact
      properties:
        business_name:
          type: string
          description: The name of the merchant's business.
          example: string
        address:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/Contact'
        external_id:
          type: string
          description: The partner's external identifier for this merchant.
          example: id-1234567890
        cuisine_types:
          type: array
          description: Types of cuisine offered by the merchant.
          items:
            type: string
    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
    MerchantActivationRequest:
      type: object
      description: Request to activate a merchant for partner integration.
      required:
      - merchant_id
      properties:
        merchant_id:
          type: string
          description: The Grubhub merchant identifier to activate.
          example: ghm-1234567890
  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