Global Catalog
Endpoint Updates
oAuth id Response
The oAuth exchange token endpoint you build must include the id property in the response, which corresponds to the merchant's id (provider merchant id) within your system.
Get Catalog X-Provider-Merchant-Id Header
Requests to your Get Catalog endpoint will include the X-Provider-Merchant-Id header instead of the X-Provider-Location-Id header.
Catalog Updated Webhook merchant_id Property
The merchant_id property should now be provided in the object property of the Catalog Updated Webhook payload. This will then resync the catalog for all locations underneath it connected to Stream.
Location-Specific Object Changes
Global catalog integrations have additional features on catalog objects to support differences across locations.
Location Overrides
In the example below, location overrides have been applied into certain items' location_overrides to change the price, availability, and description of items at specific locations. Specifically, location_2 has discounts on each platter's price, and location_1 has 86'd its "Party Platter". For a full list properties that can be overriden refer to the API documentation.
{
"category": [
{
"provider_id": "starters_provider_id",
"name": "Starters",
"item_family_ids": ["platter_provider_id"]
}
],
"item_family": [
{
"provider_id": "platter_provider_id",
"name": "c",
"description": "Appetizer Platter",
"is_active": true,
"modifier_group_ids": [],
"item_ids": [
"small_platter_provider_id",
"large_platter_provider_id",
"party_platter_provider_id"
],
"images": []
}
],
"item": [
{
"provider_id": "small_platter_provider_id",
"name": "Small Platter",
"is_active": true,
"price_amount": 500,
"price_currency": "usd",
"location_overrides": [
{
"provider_location_id": "location_2",
"override": {
"price_amount": 399
}
}
]
},
{
"provider_id": "large_platter_provider_id",
"name": "Large Platter",
"is_active": true,
"price_amount": 800,
"price_currency": "usd",
"location_overrides": [
{
"provider_location_id": "location_2",
"override": {
"price_amount": 599
}
}
]
},
{
"provider_id": "party_platter_provider_id",
"name": "Party Platter",
"is_active": true,
"price_amount": 2000,
"price_currency": "usd",
"location_overrides": [
{
"provider_location_id": "location_1",
"override": {
"is_active": false
}
},
{
"provider_location_id": "location_2",
"override": {
"price_amount": 1599
}
}
]
}
],
"modifier_group": [],
"modifier": [],
"menu": []
}
Location Memberships
In the example below, the "Brunch" menu has been introduced, but only exists at location_2. If location_memberships is ommited, the entity will exist at all locations. Note that location memberships only can be applied to certain entity types, please refer to the API documentation for more details.
{
"category": [
{
"provider_id": "sandwiches_provider_id",
"name": "Sandwiches",
"item_family_ids": ["blt_provider_id"]
},
{
"provider_id": "pancakes_provider_id",
"name": "Pancakes",
"item_family_ids": ["pancake_provider_id"]
}
],
"item_family": [
{
"provider_id": "blt_provider_id",
"name": "BLT Sandwich",
"description": "BLT Sandwich",
"is_active": true,
"price_amount": 1000,
"modifier_group_ids": [],
"item_ids": [],
"images": []
},
{
"provider_id": "pancake_provider_id",
"name": "Pancakes",
"description": "3 Pancakes",
"is_active": true,
"price_amount": 800,
"modifier_group_ids": [],
"item_ids": [],
"images": []
}
],
"item": [],
"modifier_group": [],
"modifier": [],
"menu": [
{
"provider_id": "brunch_provider_id",
"name": "Brunch",
"category_ids": ["pancakes_provider_id", "sandwiches_provider_id"],
"schedule": {
"monday": ["10:00-12:00"],
"tuesday": ["10:00-12:00"],
"wednesday": ["10:00-12:00"],
"thursday": ["10:00-12:00"],
"friday": ["10:00-12:00"],
"saturday": ["10:00-14:00"],
"sunday": ["10:00-14:00"]
},
"location_memberships": ["location_2"]
},
{
"provider_id": "lunch_and_dinner_provider_id",
"name": "Lunch & Dinner",
"category_ids": ["sandwiches_provider_id"],
"schedule": {
"monday": ["10:00-20:00"],
"tuesday": ["10:00-20:00"],
"wednesday": ["10:00-20:00"],
"thursday": ["10:00-20:00"],
"friday": ["10:00-20:00"],
"saturday": ["10:00-20:00"],
"sunday": ["10:00-20:00"]
}
}
]
}
Menu Overrides
In the example below, the "Brunch" menu has been introduced with lower pricing, but only exists at location_2. If location_memberships is ommited, the entity would exist at all locations. Note that the menu override can only be applied to all locations, and not to a specific location.
Each entry is keyed by provider_menu_id — the provider_id of the menu the override applies to — unlike location_overrides, which are keyed by provider_location_id.
{
"category": [
{
"provider_id": "starters_provider_id",
"name": "Starters",
"item_family_ids": ["platter_provider_id"]
}
],
"item_family": [
{
"provider_id": "platter_provider_id",
"name": "c",
"description": "Appetizer Platter",
"is_active": true,
"modifier_group_ids": [],
"item_ids": [
"small_platter_provider_id",
"large_platter_provider_id",
"party_platter_provider_id"
],
"images": [],
"menu_overrides": [
{
"provider_menu_id": "brunch_provider_id",
"override": {
"name": "Early Morning Bites"
}
}
]
}
],
"item": [
{
"provider_id": "small_platter_provider_id",
"name": "Small Platter",
"is_active": true,
"price_amount": 500,
"price_currency": "usd",
"menu_overrides": [
{
"provider_menu_id": "brunch_provider_id",
"override": {
"price_amount": 300
}
}
]
},
{
"provider_id": "large_platter_provider_id",
"name": "Large Platter",
"is_active": true,
"price_amount": 800,
"price_currency": "usd",
"menu_overrides": [
{
"provider_menu_id": "brunch_provider_id",
"override": {
"price_amount": 500
}
}
]
},
{
"provider_id": "party_platter_provider_id",
"name": "Party Platter",
"is_active": true,
"price_amount": 2000,
"price_currency": "usd",
"menu_overrides": [
{
"provider_menu_id": "brunch_provider_id",
"override": {
"price_amount": 1000
}
}
]
}
],
"modifier_group": [],
"modifier": [],
"menu": [
{
"provider_id": "brunch_provider_id",
"name": "Brunch",
"category_ids": ["starters_provider_id"],
"location_memberships": ["location_2"]
}
]
}
Category Hours Overrides
Categories support a schedule of availability hours, and both override scopes can carry a scoped schedule of the same shape:
location_overrides[].override.schedule— the category's hours at that location only. Global catalogs only.menu_overrides[].override.schedule— the category's hours within that menu only. Available to global and per-location catalogs.
A scoped schedule replaces the category's base schedule for that location or menu; scopes without an override keep the base schedule.
In the example below, the "Starters" category is available 11:00–22:00 by default, closes early at location_1, and runs on breakfast hours inside the "Brunch" menu.
{
"category": [
{
"provider_id": "starters_provider_id",
"name": "Starters",
"item_family_ids": ["platter_provider_id"],
"schedule": {
"monday": ["11:00-22:00"],
"tuesday": ["11:00-22:00"],
"wednesday": ["11:00-22:00"],
"thursday": ["11:00-22:00"],
"friday": ["11:00-22:00"],
"saturday": ["11:00-22:00"],
"sunday": ["11:00-22:00"]
},
"location_overrides": [
{
"provider_location_id": "location_1",
"override": {
"schedule": {
"monday": ["11:00-17:00"],
"tuesday": ["11:00-17:00"],
"wednesday": ["11:00-17:00"],
"thursday": ["11:00-17:00"],
"friday": ["11:00-17:00"],
"saturday": [],
"sunday": []
}
}
}
],
"menu_overrides": [
{
"provider_menu_id": "brunch_provider_id",
"override": {
"schedule": {
"monday": [],
"tuesday": [],
"wednesday": [],
"thursday": [],
"friday": [],
"saturday": ["09:00-14:00"],
"sunday": ["09:00-14:00"]
}
}
}
]
}
],
"item_family": [
{
"provider_id": "platter_provider_id",
"name": "Appetizer Platter",
"is_active": true,
"price_amount": 1200,
"price_currency": "usd",
"modifier_group_ids": [],
"item_ids": [],
"images": []
}
],
"item": [],
"modifier_group": [],
"modifier": [],
"menu": [
{
"provider_id": "brunch_provider_id",
"name": "Brunch",
"category_ids": ["starters_provider_id"],
"location_memberships": ["location_2"]
}
]
}