grubhub Schedules API

openapi: 3.1.0
info:
  title: Grubhub Deliveries Delivery Status Schedules 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: Schedules
  description: Endpoints for retrieving and managing merchant operating hours for delivery, pickup, and catering.
paths:
  /pos/v1/merchant/{merchant_id}/schedules/delivery:
    get:
      operationId: getDeliverySchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Delivery Schedule
      description: Returns the full weekly delivery hours for a merchant. The schedule defines the hours per day of the week that the merchant can accept delivery orders.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Weekly delivery schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklySchedule'
              examples:
                GetDeliverySchedule200Example:
                  summary: Default getDeliverySchedule 200 response
                  x-microcks-default: true
                  value:
                    monday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    tuesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    wednesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    thursday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    friday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    saturday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    sunday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetDeliverySchedule401Example:
                  summary: Default getDeliverySchedule 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:
                GetDeliverySchedule404Example:
                  summary: Default getDeliverySchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
    put:
      operationId: updateDeliverySchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Update Delivery Schedule
      description: Creates or updates the weekly delivery schedule for a merchant, specifying the hours per day of the week that the merchant can accept delivery orders. If a schedule does not exist, one will be created.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeeklySchedule'
            examples:
              UpdateDeliveryScheduleRequestExample:
                summary: Default updateDeliverySchedule request
                x-microcks-default: true
                value:
                  monday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  tuesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  wednesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  thursday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  friday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  saturday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  sunday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
      responses:
        '200':
          description: Delivery schedule updated successfully
        '400':
          description: Invalid schedule data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateDeliverySchedule400Example:
                  summary: Default updateDeliverySchedule 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:
                UpdateDeliverySchedule401Example:
                  summary: Default updateDeliverySchedule 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:
                UpdateDeliverySchedule404Example:
                  summary: Default updateDeliverySchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_id}/schedules/pickup:
    get:
      operationId: getPickupSchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Pickup Schedule
      description: Returns the full weekly pickup hours for a merchant. The schedule defines the hours per day of the week that the merchant can accept pickup orders.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Weekly pickup schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklySchedule'
              examples:
                GetPickupSchedule200Example:
                  summary: Default getPickupSchedule 200 response
                  x-microcks-default: true
                  value:
                    monday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    tuesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    wednesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    thursday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    friday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    saturday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    sunday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetPickupSchedule401Example:
                  summary: Default getPickupSchedule 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:
                GetPickupSchedule404Example:
                  summary: Default getPickupSchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
    put:
      operationId: updatePickupSchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Update Pickup Schedule
      description: Creates or updates the weekly pickup schedule for a merchant, specifying the hours per day of the week that the merchant can accept pickup orders. If a schedule does not exist, one will be created.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeeklySchedule'
            examples:
              UpdatePickupScheduleRequestExample:
                summary: Default updatePickupSchedule request
                x-microcks-default: true
                value:
                  monday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  tuesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  wednesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  thursday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  friday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  saturday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  sunday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
      responses:
        '200':
          description: Pickup schedule updated successfully
        '400':
          description: Invalid schedule data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdatePickupSchedule400Example:
                  summary: Default updatePickupSchedule 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:
                UpdatePickupSchedule401Example:
                  summary: Default updatePickupSchedule 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:
                UpdatePickupSchedule404Example:
                  summary: Default updatePickupSchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
  /pos/v1/merchant/{merchant_id}/schedules/catering:
    get:
      operationId: getCateringSchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Get Catering Schedule
      description: Returns the full weekly catering hours for a merchant. The schedule defines the hours per day of the week that the merchant can accept catering orders.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Weekly catering schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklySchedule'
              examples:
                GetCateringSchedule200Example:
                  summary: Default getCateringSchedule 200 response
                  x-microcks-default: true
                  value:
                    monday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    tuesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    wednesday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    thursday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    friday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    saturday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
                    sunday:
                      open: true
                      time_windows:
                      - start_time: {}
                        end_time: {}
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetCateringSchedule401Example:
                  summary: Default getCateringSchedule 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:
                GetCateringSchedule404Example:
                  summary: Default getCateringSchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
    put:
      operationId: updateCateringSchedule
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Grubhub Update Catering Schedule
      description: Creates or updates the weekly catering schedule for a merchant, specifying the hours per day of the week that the merchant can accept catering orders. If a schedule does not exist, one will be created.
      tags:
      - Schedules
      parameters:
      - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeeklySchedule'
            examples:
              UpdateCateringScheduleRequestExample:
                summary: Default updateCateringSchedule request
                x-microcks-default: true
                value:
                  monday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  tuesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  wednesday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  thursday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  friday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  saturday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
                  sunday:
                    open: true
                    time_windows:
                    - start_time: {}
                      end_time: {}
      responses:
        '200':
          description: Catering schedule updated successfully
        '400':
          description: Invalid schedule data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateCateringSchedule400Example:
                  summary: Default updateCateringSchedule 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:
                UpdateCateringSchedule401Example:
                  summary: Default updateCateringSchedule 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:
                UpdateCateringSchedule404Example:
                  summary: Default updateCateringSchedule 404 response
                  x-microcks-default: true
                  value:
                    error: invalid_request
                    message: Operation completed successfully.
                    status: 0
components:
  schemas:
    WeeklySchedule:
      type: object
      description: A weekly schedule defining operating hours for each day of the week.
      properties:
        monday:
          $ref: '#/components/schemas/DaySchedule'
        tuesday:
          $ref: '#/components/schemas/DaySchedule'
        wednesday:
          $ref: '#/components/schemas/DaySchedule'
        thursday:
          $ref: '#/components/schemas/DaySchedule'
        friday:
          $ref: '#/components/schemas/DaySchedule'
        saturday:
          $ref: '#/components/schemas/DaySchedule'
        sunday:
          $ref: '#/components/schemas/DaySchedule'
    TimeWindow:
      type: object
      description: A time window defining a start and end time.
      properties:
        start_time:
          type: string
          description: The start time in HH:mm format.
          pattern: ^\d{2}:\d{2}$
          example: '2026-06-02T18:30:00Z'
        end_time:
          type: string
          description: The end time in HH:mm format.
          pattern: ^\d{2}:\d{2}$
          example: '2026-06-02T18:30:00Z'
      required:
      - start_time
      - end_time
    DaySchedule:
      type: object
      description: Operating hours for a single day, supporting multiple time windows.
      properties:
        open:
          type: boolean
          description: Whether the merchant is open on this day.
          example: true
        time_windows:
          type: array
          description: Time windows when the merchant is available. Supports split shifts with multiple windows per day.
          items:
            $ref: '#/components/schemas/TimeWindow'
    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