Skip to main content

Location Management

Location Retrieval​

When a merchant connects to Stream, we will fetch all available locations from your platform using the Get Locations endpoint. This allows merchants to select which locations they want to connect to Stream.

Location Properties​

Each location should include essential information:

  • Unique provider_id to identify the location
  • Name and address details
  • Preparation time in minutes prep_time_minutes (optional)
  • Connection status to stream connection_status (optional). This can be used to stop Stream from requesting catalog information during ingest processing.

Location Operational Status Management (Obligatory)​

Stream provides functionality for merchants to manage their location statuses through our platform. This can effectively disable/enable connected channels for a location.

Status Updates​

When a location's status changes in your POS system (e.g., temporary closure, service interruption), you should notify Stream by sending a request to the Location Status Update Notification (POS -> Stream via Webhook) endpoint with the updated status information.

Example location status update payload:

{
  "type": "location.status.updated",
  "object": {
    "location_id": "test_location_123",
    "status": "active" | "inactive" ,
    "paused_until": 1707772800000, // Optional: Unix timestamp in milliseconds
  }
}

Location Integration Connection Status (Optional)​

If opted in, we will send connection status updates to your platform to help you recognize and manage Stream's connection state. This allows your platform to:

  • Control webhook delivery: Use the connection status to determine whether to send webhooks to Stream
  • Update platform UI: Display accurate connection status in your system (connected/disconnected)
  • Customize user experience: Show appropriate CTA text on SSO buttons and other integration touchpoints

Note: These requests are only sent when Stream initiates the connection status change. No request is sent when your POS triggers the change itself.

How connection_status affects connection requests​

Before marking a location connected, Stream reads connection_status from each location in the Get Locations response:

  • online — Stream treats the location as already connected and will not send a redundant PUT to mark it connected again.
  • offline (or omitted when not connected) — After ingest completes successfully, Stream sends PUT /stream-pos/v1/location/connection to mark the location connected.

Your platform must return connection_status accurately on Get Locations. If a location is not connected to Stream, return offline (or omit the field) so Stream can send the PUT when it is ready. If you return online for a location that is not actually connected, Stream will skip the PUT and your platform may never receive the signal to start sending webhooks.

After you handle a connection or disconnection request, update the value you return on subsequent Get Locations calls so Stream and your platform stay in sync.

Connection Endpoints:

  • PUT /stream-pos/v1/location/connection - Indicates the location should be connected to Stream. Your platform should begin sending webhooks for events like catalog.location.updated, order.created, etc. Stream only sends this when Get Locations reports the location as not already online. Endpoint

  • DELETE /stream-pos/v1/location/connection - Indicates the location should be disconnected from Stream. Your platform should stop sending webhooks and update the connection status in your UI. Endpoint