List Merchants

Returns a list of all merchants (and their unique identifiers) available to Grubhub. The provider_id returned here is passed to subsequent calls to the locations index endpoint detailed below. It therefore must contain only characters that are valid in a URL (ASCII).

If the provider only includes a single brand, please add the singular brand to the endpoint. There should only be a single instance of the List Merchants endpoint. All merchants must be added to this endpoint. Grubhub pulls all allocated locations per merchant.

Request Endpoints

GET /merchants

Example Response Body

{
  "updated_at": "2016-08-17T12:45:03",
  "merchants": [
    {
      "merchant": {
        "name": "Grubhub Cafe",
        "provider_id": "abc123",
        "integration_id": "mediapos",
        "allows_order_scheduling": "true",
        "active": true,
        "terminated": false
      }
    },
    {
      "merchant": {
        "name": "Joe's Sandwich Shack",
        "provider_id": "xyz456",
        "integration_id": "mediapos",
        "allows_order_scheduling": "false",
        "active": false,
        "terminated": true
      }
    }
  ]
}

Example Response Schema

{
  "type": "object",
  "properties": {
    "updated_at": {
      "description": "An iso8601 datestamp in UTC of when the merchant list was last refreshed",
      "type": "string"
    },
    "merchants:": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "merchant": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the merchant"
              },
              "provider_id": {
                "type": "string",
                "description": "Unique identifier for the merchant"
              },
               "integration_id": {
                "type": "string",
                "description": "Unique identifier for the integration. If using the same integration, this id must be the same for each merchant""
              },
              "allows_order_scheduling": {
                "type": "boolean",
                "description": "Whether or not native order scheduling is supported by this order provider for the merchant"
              },
              "active": {
                "type": "boolean",
                "description": "Whether or not the merchant is able to accept orders. For example, this should be false if the merchant is experiencing ordering provider issues and is unable to accept orders"
              },
              "terminated": {
                "type": "boolean",
                "description": "Whether or not the merchant is permanently unavailable on the provider"
              }
            },
            "required": [
              "name",
              "provider_id",
              "integration_id",
              "allows_order_scheduling",
              "terminated",
              "active"
            ]
          }
        },
        "required": [
          "merchant"
        ]
      }
    }
  },
  "required": [
    "merchants"
  ]
}

Handling Available and Unavailable Merchants

An up-to-date list of available merchants should always be returned when the merchants endpoint is pinged. A merchant that is permanently removed from a provider and can no longer be ordered from is considered to be delisted. Delisted merchants should not be included in the merchants list.

Note that this does not necessarily mean that the merchant itself is closed, only that the merchant is no longer supported by that provider.

The active and terminated keys are used to determine whether a merchant is available for ordering. Details about these values are included in the response schema above.

Handling Relisted Merchants

It is possible that a provider decides to relist a merchant on their system. When a merchant is relisted, it should be included back in the merchants list. Additionally, the provider_id should not change.