Headless Onboarding at a Glance

Headless onboarding takes a merchant from nothing to a live DSP connection in eight steps, all through the Partner API. Steps 1 to 6 are calls you make. Step 7 is waiting: for most DSPs, binding a location starts an activation that finishes later, outside your request.

Every call, in order

#	Step	Call	Guide
1	Authenticate	POST /oauth/token with scope onboarding	Authentication
2	Create the merchant's org	POST /onboarding/org	Organization Creation
3	Connect the POS	POST /onboarding/integrations with type: "pos", then PUT /onboarding/integrations/{id} with the OAuth or manual code	POS Integration Flow
4	Import locations and menus	GET /onboarding/locations, then POST /onboarding/locations/ingest	Location Management
5	Connect the DSP	POST /onboarding/integrations with type: "dsp", then PUT /onboarding/integrations/{id}	DSP Integration
6	Bind POS locations to DSP stores	POST /onboarding/locations/bind	Bind DSP Locations
7	Track activation	GET /onboarding/org/{id}/locations?location_id= until dsps[].status is APPROVED	Tracking Activation
8	Optional: limit which menus a DSP gets	PUT /onboarding/menus/assignments	Assign Menus
9	Optional: publish menus now instead of waiting for the next catalog update	POST /onboarding/menus/publish	Publish Menus

Use GET /onboarding/integrations/dsp-options to list the DSPs you can offer. Each option's source is the value to pass as source in step 5.

Two statuses, not one

The flow has two separate statuses, and confusing them is the most common headless mistake:

Status	Belongs to	Values	Live when
Integration status	The merchant's POS or DSP account connection (the onboarding object from steps 3 and 5)	pending, waiting_for_oauth, active, deprovisioned	active
DSP connection status	One bound location on one DSP (from step 6 onwards)	pending, APPROVED, needs_reconnection, waiting_for_deprovision, deprovisioned	APPROVED

caution

An active DSP integration does not mean its locations are live. The integration becomes active when the merchant connects their DSP account in step 5. Each location bound to it in step 6 has its own status, and on most DSPs that starts as pending. See DSP Connection Statuses.

What you can't do through the API yet

The Partner API does not yet offer these operations. If you need one, contact Stream support:

• Unbind, retry, or rebind a single location.
• Read whether a publish reached the DSP. You can trigger a publish, but its response only confirms the publish was queued.
• Receive a notification when a connection's status changes. Poll instead, as described in Tracking Activation.