List Merchants

Provider Enablement / Endpoints

List Merchants

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

Request Endpoints

GET /merchants

Example Response Body

{
  "updated_at": "2016-08-17T12:45:03",
  "merchants": [
    {
      "merchant": {
        "name": "LevelUp Cafe",
        "provider_id": "abc123",
        "integration_id": "revel",
        "allows_order_scheduling": "true",
        "active": true,
        "terminated": false
      }
    },
    {
      "merchant": {
        "name": "Joe's Sandwich Shack",
        "provider_id": "xyz456",
        "integration_id": "monkeymedia",
        "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"
              },
              "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.