Skip to main content

Menu Ingestion

As a Stream DSP, merchants will be able to publish their menus and schedules to your platform.

When this happens, we will call the New Webhook Event endpoint with an event type of location.publish. You will need to retrieve the data from download_url for the menus and schedules.

PublishMenusPayload​

The data within the S3 file has now been defined in our OpenAPI specification, allowing for more accurate types. Click Here

Schedule Management​

Each menu has its own schedule, represented by the Schedule entity above. These will be provided in the schedule field of each Menu. This allows each individual menu to have specific availablity hours. The example below contains a schedule with hours of 9 am to 4 pm on weekdays, and 8 am to 6 pm on weekends.

{
  ...
  schedule: {
    monday: ["9:00-16:00"],
    tuesday: ["9:00-16:00"],
    wednesday: ["9:00-16:00"],
    thursday: ["9:00-16:00"],
    friday: ["9:00-16:00"],
    saturday: ["8:00-18:00"],
    sunday: ["8:00-18:00"]
  }
}

Schedule Exceptions (Holidays)​

Holiday information that overrides the schedule for the location will be provided in the holidays property of the payload.

Each holiday has a date represented in the MM-DD format, and a flag recurring_yearly that indicates if this holiday repeats every year. If recurring_yearly is false, the specific_years array will contain the specific years that the holiday occurs on.

Finally, the hours array contains the specifc timeslots that the location is open for this holiday. If hours is omitted, the location is closed for the entire day.

{
  ...
  holidays: [
    /** Annual closures / hour updates */
    {
      date: "12-25",
      recurring_yearly: true,
      name: "Christmas Day"
    },
    {
      date: "01-01",
      recurring_yearly: true,
      name: "New Year's Day",
      hours: ["9:00-17:00"]
    },
    /** One-off holidays/closure */
    {
      date: "11-28",
      recurring_yearly: false,
      specific_years: [2024],
      name: "Thanksgiving Day",
    }
  ]
}

Taxes​

We will provide tax rate information assigned the item level, allowing for things like exemptions, inclusive rates and more. Below are some examples of how this data can be provided.

Here is a default tax rate across the menu, with some items excluded from the rate.

{
  ...
  item: [
    {
      stream_id: "item_with_tax",
      tax_ids: ["tax_1234"],
      ...
    },
    {
      stream_id: "item_without_tax",
      tax_ids: [],
      ...
    }
  ]
  taxes: [
    /** Annual closures / hour updates */
    {
      is_inclusive: false,
      stream_id: "tax_1234",
      rate: 7.5, /** 7.5% */
      is_default: true,
      name: "Sales tax"
    }
  ]
}

Here is an example with multiple tax rates across the menu, with certain items having certain rates.

{
  ...
  item: [
    {
      stream_id: "item_with_tax",
      tax_ids: ["tax_1234"],
      ...
    },
    {
      stream_id: "item_with_added_excise",
      tax_ids: ["tax_1234", "tax_5678"],
      ...
    }
  ]
  taxes: [
    /** Annual closures / hour updates */
    {
      is_inclusive: false,
      stream_id: "tax_1234",
      rate: 7.5, /** 7.5% */
      is_default: true,
      name: "Sales tax"
    },
    {
      is_inclusive: false,
      stream_id: "tax_5678",
      rate: 2.5, /** 2.5% */
      is_default: false,
      name: "Excise tax"
    }
  ]
}

Feature Flags

The following are features that can be configured and unique to your integration. Please reach out to Stream if you would like to have access to and implement the following features.

Active / Inactive Item and Modifier Handling​

Default Behavior​

If an item family, item, or modifier is marked as inactive in Stream, either by the user or the POS system, the menu sent to the DSP will automatically exclude all inactive items. Items, item families, and modifiers will always be sent with is_active equal to true.

Example

{
  "_id": "item_1",
  "name": "Water Bottle",
  "price_amount": 100,
  "price_currency": "usd",
  "is_active": true
}

Configurable Behavior for Inactive Items and Modifiers​

A DSP can opt in if they would like to recieve inactive data for item family, item, and/or modifier for a recieved menu. The main benefits of this feature include:

  • When you 86 an item and publish the menu (removing the item from the new publish), resuming the item later requires a full menu re-publish to add it back. To avoid unnecessary menu rebuilds, this feature allows inactive items to be included in the initial menu publish. This way, future 86'ing of items can be handled by a targeted itemized update, reducing the need for full menu publishes.
  • You may have an UI/UX that shows the consumer that an item does exist on the menu, but is currently unavailable.

Example

{
  "_id": "item_1",
  "name": "Water Bottle 16oz",
  "price_amount": 100,
  "price_currency": "usd",
  "is_active": true
}
{
  "_id": "item_2",
  "name": "Water Bottle 24oz",
  "price_amount": 175,
  "price_currency": "usd",
  "is_active": false
}

The v2 menu schema provides an optimized data structure that significantly reduces payload size through improved data associations. Contact support to enable v2 schema access when building to the API.

Key Changes​

  • Better alignment with Stream catalog standard
  • Implemented association-based data structure
    • Better insight into relation based overrides
    • Reduced overall payload size

A DSP can also opt-in to be notified of object-level updates to items, variations, and modifiers in favor of a full menu publish.

See more