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.

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. 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