🏪 Merchants
Fields
| Name | Type | Description |
|---|---|---|
id | string | The unique identifier for the merchant (e.g., mer_AbCd1234). |
name | string | The public display name (e.g., "Riyadh Burger House"). |
legal_name | string | The official registered business name. |
is_active | boolean | Master switch (true/false) to show or hide the merchant entirely. See "Understanding Availability". |
status | string | Real-time operational status within scheduled hours (e.g., accepting_orders, busy, temporarily_closed). See "Understanding Availability". |
address | object | Structured physical address (street, city, country using ISO 3166-1 alpha-2). |
location | object | Precise geographic coordinates (latitude, longitude). |
merchant_type | string | High-level category (e.g., restaurant, retail_store, grocery). |
tags | array | List of descriptive keywords for search (e.g., ["burgers", "halal"]). |
operating_hours | array | List defining scheduled opening hours per day (day_of_week, open_time, close_time in 24h local). See "Understanding Availability". |
updated_at | string | Timestamp of the last modification (ISO 8601 UTC). |
Understanding Merchant Availability
1.
is_active (boolean): If false, the merchant is completely unavailable and should never be shown (e.g., permanently closed, suspended, onboarding incomplete).2.
operating_hours (array): Check if the current time falls within the scheduled open_time and close_time for the current day_of_week in the merchant's local timezone. If outside these hours, they are closed.3.
status (string): If within operating_hours, this field provides real-time overrides."accepting_orders": Open and ready."busy": Open, but may experience delays."temporarily_closed": Within scheduled hours but currently unable to take orders (e.g., kitchen issue, cleaning). Treat as closed.Sample JSON
Restaurant Example
{
"id": "mer_AbCd1234",
"name": "Riyadh Burger House",
"legal_name": "Riyadh Foods Company LLC",
"is_active": true,
"status": "accepting_orders",
"address": { "street": "789 King Fahd Road", "city": "Riyadh", "country": "SA" },
"location": { "latitude": 24.7136, "longitude": 46.6753 },
"merchant_type": "restaurant",
"tags": ["burgers", "fast_food", "halal", "family_friendly"],
"operating_hours": [
{ "day_of_week": "saturday", "open_time": "12:00", "close_time": "01:00" },
{ "day_of_week": "sunday", "open_time": "12:00", "close_time": "01:00" }
],
"updated_at": "2025-10-15T16:30:00Z"
}Grocery Store Example
{
"id": "mer_TmRydh01",
"name": "Tamimi Markets - Olaya",
"legal_name": "Tamimi Markets Company",
"is_active": true,
"status": "accepting_orders",
"address": { "street": "123 Olaya Street", "city": "Riyadh", "country": "SA" },
"location": { "latitude": 24.7000, "longitude": 46.6833 },
"merchant_type": "grocery",
"tags": ["supermarket", "fresh_produce", "bakery", "imported_goods"],
"operating_hours": [
{ "day_of_week": "saturday", "open_time": "08:00", "close_time": "23:59" },
{ "day_of_week": "sunday", "open_time": "08:00", "close_time": "23:59" }
],
"updated_at": "2025-10-16T09:00:00Z"
}