Skip to main content

Catalog Management

Manual Catalog Resync​

Once your merchants have connected a location to Stream, we will begin maintaining a mapped record of all items between your POS and the merchants connected DSPs.

Upon onboarding or from a user requested resync from the UI, Stream will fetch the catalog using Get Catalog.

Catalog Objects​

Item Family - Top level of all items. I.E. Whopper Combo Item - The main selection options presented for the item family. I.E. Size Modifier Group - Non-primary selections for item family. I.E Toppings, Drink. Modifier - Non-primary selection options for modifier groups. I.E. Cheese/Pickle,Coke/Dr Pepper.

To begin to understand Catalog Objects, start with reading about provider_id and it's purpose. Catalog Object Provider ID

In addition to the core catalog objects (Item Family, Item, Modifier Group, and Modifier), Stream also supports an optional Menu object within the catalog. This can be particularly useful for POSs that have managed menus or even for those that don't support multiple menus but want to provide additional structure to their catalog.

The Menu object can serve several purposes:

  1. Category Ordering: It allows you to specify the order in which categories should be displayed.
  2. Menu Scheduling: You can associate specific hours with a menu, indicating when certain categories are available.

Images​

Item Family images must follow the following guidelines for successful propegation to third party platforms.

  • File size < 25MB
  • JPG, WEBP or PNG format
  • 320px ≤ Width ≤ 6000px
  • 320px ≤ Height ≤ 6000px
note

Stream will not reprocess images unless the image URL changes. If you need to update an existing image, ensure you provide a new URL to trigger reprocessing.

Automatic Catalog Resync​

With the items existing in multiple places this can become a hassle to manage, which is why we have an automated process to keep everything in sync when changes are made inside the POS.

To take advantage of this functionality, you must configure a process to notify Stream when updates occur.

Send Notification​

Send a request to the Catalog Update Notification (POS -> Stream via Webhook) endpoint with the respective provider_id from the Get Locations endpoint.

Notification Behavior​

Upon notification of an update, Stream will resync the catalog using Get Catalog and publish changes to connected DSP platforms automatically.

Stock Updates​

To efficiently manage items and modifiers going out-of-stock at a certain location, we also provide a system to Notify stream when these specific events occur. Implementing this can be advantageous in that a full resync will not need to be done just to sync an update to one object.

Send Notification​

Send a request to the Catalog Object Update Notification (POS -> Stream via Webhook) endpoint with the respective location and object provider ids, the type of the object being updated, and the new is_active status of the object. The update will be applied in real-time to the catalog and no resync will be necessary.

Example item family out-of-stock payload

{
  "type": "location.catalog.object.updated",
  "object": {
    "location_id": "test_location",
    "object_id": "cheeseburger_provider_id",
    "object_type": "item_family",
    "object_update": {
      "is_active": false
    }
  }
}

Catalog Taxes​

Stream has delivered a customizable item-level tax rate solution, which deprecates our catalog wide tax rate implementation.

To set these tax rates through the API you can return the tax array on Get Catalog. Once a tax rate is defined there, you will assign them to items using the item family tax_ids property and the tax rate's provider_id. In the example below, the catalog would have a 9.5% tax rate applied to all items. With one item containing alcohol tax of 6.5%.

{
  "category": [...],
  "item_family": [{
    ...,
    "name": "Margarita",
    "tax_ids":["alcohol_tax"]
  }],
  "item": [...],
  "modifier_group": [...],
  "modifier":[...],
  "menu": [...],
  "tax": [
    {
      "provider_id": "sales_tax",
      "rate": 9.5,
      "name": "Sales Tax",
      "is_default": true,
    },
    {
      "provider_id": "alcohol_tax",
      "rate": 6.5,
      "name": "Alcohol Tax"
    }
  ]
}

Alcoholic Items​

Stream enables tagging items as alcoholic, to comply with regulations and properly prompt age verifications throughout the order flow.

To set this tax rate through the API you can return the is_alcohol property on item families within the Get Catalog Response. In the example below, the item family would be tagged as alcohol on the platforms it's published too.

{
  "provider_id": "booze_provider_id",
  "name": "Booze",
  "description": "Bottle of Booze",
  "is_alcohol": true,
  ...
}

Global Catalog​

If your integration will be using a global catalog, in which only one catalog is created and it is shared across all locations under a given merchant, there are additional features avaiable to make differences across locations easier to manage. Refer to the Global Catalog documentation for further information.