POS Feature Flags
Your POS integration starts with a standard set of behavior. On top of that, Stream maintains a small number of feature flags — optional capabilities that can be switched on for your integration specifically, so you only implement what your system actually supports.
This page is the complete list of what exists for POS integrations, plus the behavior that is not optional and the limits that apply to every integration.
| Capability | Default | What it changes |
|---|---|---|
| Sign up with your POS | Off | Merchants can create a Stream account directly from your OAuth flow |
| Markup line item | Off | Markup is separated out of item prices into its own line item |
| Global catalog | Off | One catalog is shared across all of a merchant's locations |
| Order adjustments | Off | Adjusted orders are pushed to you instead of stored for the merchant |
| Menu publish notifications | Off | Receive DSP menu publish success and/or failure events |
| Connection state | Off | Receive connect and disconnect calls as locations are linked and unlinked |
How feature flags work
A few rules apply to every flag on this page:
- Everything is off by default. An integration with no flags enabled is a valid, complete integration — flags only add behavior. If you never request one, nothing about your integration changes.
- Flags are enabled by Stream, not self-service. There is no API for turning a flag on. Ask your Stream contact for the capability by name and we will enable it against your integration.
- Enabling requires your integration to be live. A capability can only be switched on once your
integration status is
live. While you are still inbuildingorpilot, plan your build around the flag but expect it to be enabled at go-live. Turning a capability back off is always possible, at any status. - Flags apply to your whole integration, not per merchant or per location. Once enabled, the behavior applies to every location connected to your system.
There is currently no endpoint that returns which flags are enabled on your integration. If you are unsure what you have, ask your Stream contact and we will confirm.
DSP and Events integrations have their own capabilities — see DSP Feature Flags and Events Feature Flags.
Sign up with your POS
Default: off — your POS can be connected to an existing Stream account, but cannot create one.
When enabled, your integration is offered as a sign-up option: a merchant with no Stream account can start from your OAuth flow and have an account created for them. With it off, a merchant starting that flow without an existing session is rejected.
Markup line item
Default: off — any Stream markup is included in the item prices you receive.
When enabled, the markup component is removed from each item and modifier price and sent instead as a single additional line item on the order.
What you need to implement: accept a line item that carries no POS product id and charge it as a flat amount. See Order Markup Values.
Global catalog
Default: off — catalogs are fetched and stored per location.
When enabled, one catalog is shared across all of a merchant's locations. Stream requests the catalog scoped by merchant rather than by location, and expects a stable merchant-level identifier.
What you need to implement: a catalog endpoint that accepts and correctly scopes by the merchant identifier, and a stable merchant id on your side. See Global Catalog.
Order adjustments
Default: off — when a DSP adjusts an order that has already reached your POS, Stream records the adjustment and alerts the merchant, but sends you nothing.
When enabled, the adjustment is applied and pushed to your orders endpoint as an adjustment payload, and Stream expects your order identifier back in the response.
What you need to implement: idempotent handling of an adjustment to a previously accepted order, returning the same response shape as order creation.
Menu publish notifications
Default: off — no publish notifications are sent.
When enabled, Stream notifies you when a location's menu is published to a delivery platform. Two scopes exist and can be enabled independently:
- Menu publish success — the publish completed.
- Menu publish failure — the publish failed, with a failure code and reason.
Each notification names the delivery platform, the location, and the menu involved, and identifies the location by your location id.
What you need to implement: a handler on your events endpoint for the scopes you enable.
This is about menus Stream publishes out to delivery platforms on the merchant's behalf. It is unrelated to Stream ingesting your catalog.
Connection state
Default: off — Stream never calls you about connection state.
When enabled, Stream calls your integration to connect a location after it is successfully ingested, and to disconnect it when the location is deprovisioned. Use this if your system needs to track, or act on, whether a location is actively linked to Stream.
What you need to implement: connect and disconnect endpoints for a location. Optionally, return a connection status on your locations endpoint so Stream does not re-connect a location that is already online.
Behavior that is always on
Four POS behaviors are not optional, and every integration must account for them:
- Order status updates are always sent. Stream pushes order status changes — ready for pickup, completed, delivery and driver updates — to your orders endpoint. There is no flag to opt out, so your endpoint must handle update payloads as well as new orders.
- Menu ingest is always active. Deletion tracking runs on every ingest.
- Locations are ingested one at a time. Batched multi-location ingest is not available to partner integrations.
- Merchants can always edit their catalog in the Stream dashboard. If your POS is the source of truth on your side, note that Stream-side editing cannot currently be locked for a partner integration.
Catalog size limit
A single catalog is capped at 15,000 items and 15,000 modifiers. This ceiling is fixed across all partner POS integrations and is not configurable per partner. If you expect merchant catalogs to approach it, raise it with Stream before you go live.