List Locations

Provider Enablement / Endpoints

List Locations by Merchant

For a given merchant (identified by the appropriate merchant identifier received in the list merchants call), return all locations belonging to that merchant. The provider_id returned here will be passed to subsequent calls that require a location provider ID. It therefore must contain only characters that are valid in a URL (ASCII).

LevelUp will hit this endpoint to get the locations list for a given merchant.

Note that the the id here is not LevelUp’s internal id but rather your location ID as the provider. In short, it’s the ID that you return to us in the locations endpoint above.

The endpoint should return information about each location, including address, hours, phone # etc…

Request Endpoint

GET /merchants/:provider_merchant_id/locations

Example Response Body

{
  "updated_at": "2016-08-17T12:45:03Z",
  "locations": [
    {
      "location": {
        "active": true,
        "terminated": false,
        "accepts_tips_on_delivery": false,
        "accepts_tips_on_pickup": true,
        "extended_address": "Suite 100",
        "fulfills_deliveries": false,
        "fulfills_pickups": true,
        "hours": [
          {
            "sunday": [
              {
                "opens_at": "11:00",
                "closes_at": "15:00"
              }
            ]
          },
          {
            "monday": [
              {
                "opens_at": "7:30",
                "closes_at": "15:00"
              },
              {
                "opens_at": "17:00",
                "closes_at": "23:00"
              }
            ]
          },
          {
            "tuesday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "wednesday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "thursday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "friday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "saturday": [
              {
                "opens_at": "11:00",
                "closes_at": "15:00"
              }
            ]
          }
        ],
        "locality": "Boston",
        "name": "Siam Bistro Pearl St.",
        "phone": "3459131235",
        "postal_code": "02210",
        "provider_id": "12345",
        "region": "MA",
        "street_address": "150 Pearl St.",
        "lat": 42.3542524,
        "lng": -71.0588322,
        "pickup_minimum_amount": 500
      }
    },
    {
      "location": {
        "active": true,
        "terminated": false,
        "accepts_tips_on_pickup": false,
        "accepts_tips_on_delivery": false,
        "fulfills_deliveries": true,
        "fulfills_pickups": true,
        "hours": [
          {
            "sunday": [
              {
                "opens_at": "11:00",
                "closes_at": "15:00"
              }
            ]
          },
          {
            "monday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "tuesday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "wednesday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "thursday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "friday": [
              {
                "opens_at": "09:00",
                "closes_at": "22:00"
              }
            ]
          },
          {
            "saturday": [
              {
                "opens_at": "11:00",
                "closes_at": "15:00"
              }
            ]
          }
        ],
        "delivery_hours": [
          {
            "sunday": [
              {
                "opens_at": "13:00",
                "closes_at": "15:00"
              }
            ]
          },
          {
            "monday": [
              {
                "opens_at": "12:00",
                "closes_at": "20:00"
              }
            ]
          },
          {
            "tuesday": [
              {
                "opens_at": "12:00",
                "closes_at": "20:00"
              }
            ]
          },
          {
            "wednesday": [
              {
                "opens_at": "12:00",
                "closes_at": "20:00"
              }
            ]
          },
          {
            "thursday": [
              {
                "opens_at": "12:00",
                "closes_at": "20:00"
              }
            ]
          },
          {
            "friday": [
              {
                "opens_at": "12:00",
                "closes_at": "20:00"
              }
            ]
          },
          {
            "saturday": [
              {
                "opens_at": "13:00",
                "closes_at": "15:00"
              }
            ]
          }
        ],
        "locality": "Cambridge",
        "name": "Siam Bistro Mass. Ave.",
        "phone": "9786431567",
        "postal_code": "02139",
        "provider_id": "946283",
        "region": "MA",
        "street_address": "860 Mass. Ave.",
        "lat": 42.403601,
        "lng": -71.0806558,
        "pickup_minimum_amount": 500,
        "delivery_fee_amount": 399,
        "delivery_minimum_amount": 500,
        "delivery_area": [
          [
            29.4999233,
            -95.2000998
          ],
          [
            29.5459873,
            -95.213478
          ],
          [
            29.5773502,
            -95.2206922
          ],
          [
            29.4929148,
            -95.1840069
          ]
        ]
      }
    }
  ]
}

Example Response Schema

{
  "type": "object",
  "properties": {
    "updated_at": {
      "description": "An iso8601 datestamp in UTC of when the location list was last refreshed",
      "type": "string"
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "location": {
            "type": "object",
            "properties": {
              "active": {
                "description": "Whether or not the location is able to accept orders. For example, this should be false if the location is experiencing ordering provider issues and is unable to accept orders",
                "type": "boolean"
              },
              "terminated": {
                "description": "Whether or not the location is permanently unavailable on the provider",
                "type": "boolean"
              },
              "accepts_tips_on_delivery": {
                "description": "Whether or not the location accepts tips on delivery orders",
                "type": "boolean"
              },
              "accepts_tips_on_pickup": {
                "description": "Whether or not the location accepts tips on pickup orders",
                "type": "boolean"
              },
              "extended_address": {
                "description": "Additional address information, e.g. 'Suite 100'",
                "type": "string"
              },
              "fulfills_deliveries": {
                "description": "Whether or not the location accepts delivery orders",
                "type": "boolean"
              },
              "fulfills_pickups": {
                "description": "Whether or not the location accepts pickup orders",
                "type": "boolean"
              },
              "hours": {
                "type": "object",
                "properties": {
                  "sunday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "monday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "tuesday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "wednesday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "thursday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "friday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "saturday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  }
                },
                "required": [
                  "sunday",
                  "monday",
                  "tuesday",
                  "wednesday",
                  "thursday",
                  "friday",
                  "saturday"
                ]
              },
              "delivery_hours": {
                "type": "object",
                "properties": {
                  "sunday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "monday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "tuesday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "wednesday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "thursday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "friday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "saturday": {
                    "type": "array",
                    "description": "An array containing zero or more objects containing opens_at and closes_at timestamp properties",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  }
                },
                "required": [
                  "sunday",
                  "monday",
                  "tuesday",
                  "wednesday",
                  "thursday",
                  "friday",
                  "saturday"
                ]
              },
              "provider_id": {
                "description": "The ID for the location that we will pass to you when ordering",
                "type": "string"
              },
              "locality": {
                "description": "The city/region of the location, e.g. 'Boston'",
                "type": "string"
              },
              "name": {
                "description": "The name of the location, e.g. 'Siam Bistro Pearl St.'",
                "type": "string"
              },
              "phone": {
                "description": "The phone number for the location",
                "type": "string"
              },
              "postal_code": {
                "description": "The postal code for the location",
                "type": "string"
              },
              "region": {
                "description": "The state the location is in",
                "type": "string"
              },
              "street_address": {
                "description": "The street address of the location",
                "type": "string"
              },
              "lat": {
                "description": "The latitude of the location",
                "type": "number"
              },
              "lng": {
                "description": "The longitude of the location",
                "type": "number"
              },
              "pickup_minimum_amount": {
                "description": "The minimum order total required for pickup, in cents",
                "type": "number"
              },
              "delivery_fee_amount": {
                "description": "The delivery fee charged, in cents",
                "type": "number"
              },
              "delivery_minimum_amount": {
                "description": "The minimum order total required for delivery, in cents",
                "type": "number"
              },
              "delivery_area": {
                "type": "array",
                "description": "An array of coordinates that defines the bounds for the delivery zone of the location",
                "items": {
                  "type": "array",
                  "description": "An array with the latitude and longitude coordinates of the location's delivery area",
                  "items": {
                    "lat": {
                      "description": "The latitudinal coordinate of the point",
                      "type": "number"
                    },
                    "lng": {
                      "description": "The longitudinal coordinate of the point",
                      "type": "number"
                    }
                  },
                  "required": [
                    "lat",
                    "lng"
                  ]
                }
              }
            },
            "required": [
              "active",
              "terminated",
              "accepts_tips_on_delivery",
              "accepts_tips_on_pickup",
              "locality",
              "name",
              "provider_id",
              "postal_code",
              "region",
              "street_address"
            ]
          }
        }
      }
    }
  },
  "required": [
    "locations",
    "updated_at"
  ]
}

Handling Hours

If a location has multiple open and close times, return an array of each open and close time as in this example. If open/closed hours span midnight, they should be split into two separate segments, one for each actual day. So if a location is open on Tuesday night from 6 pm to 2 am, we should represent that like this:

{
  "hours": {
    "tuesday": [{
      "opens_at": "18:00",
      "closes_at": "24:00"
    }],
    "wednesday": [{
      "opens_at": "0:00",
      "closes_at": "2:00"
    }]
  }
}

If a location’s hours for a particular day are not known as given from provider, return the hours attribute with a value of null.

Ex: only Tuesdays and Wednesdays of a particular merchant are not known:

{
  "hours": {
    "monday": [{
      "opens _at": "18:00",
      "closes_at": "22:00"
    }],
    "tuesday": null,
    "wednesday": null
  }
}

However, if they are known to be closed return with a value of “closed”. Ex: Monday hours are not known. Tuesdays and Wednesdays are explicitly closed as given by provider

{
  "hours": {
    "monday": null,
    "tuesday": "closed",
    "wednesday": "closed"
  }
}

Your response should always include all days of the week, even if some are null, indicating the hours are unknown or not recorded.

Handling Available and Unavailable Locations

The locations list should include all available locations from its merchant. The availability of a location is independent of business hours. If a location has business hours between 9AM - 9PM, and there is a request to the locations endpoint at 10PM, the location is still considered to be active and should be included in the response.

If a location is permanently removed from a provider and can no longer be ordered from then it is considered to be delisted. Delisted locations should not be included in the most up-to-date list of locations. Note that a delisted location does not necessarily mean that the location itself is closed, only that it is no longer supported by that provider.

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

Handling Relisted Locations

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