Troubleshooting Headless Onboarding
Common problems
| Symptom | Likely cause | What to do |
|---|---|---|
| Bind succeeded but the location gets no orders | The connection is pending, not APPROVED. A successful bind is not activation. | Read status in the bind response, then track activation. |
DoorDash bind returns 400 | The location is missing a timezone or phone number, or its menus have no hours. | Fix the location in the POS, re-ingest it, and bind again. Log the 400 response body: it is the only record of the reason. |
Connection stays pending on Uber Eats Retail or SkipTheDishes | These DSPs are activated manually by Stream's team. | Contact Stream support. |
Connection stays pending on DoorDash or Grubhub for more than 24 hours | The DSP has not completed its review, or rejected the store. | Contact Stream support. |
Connection changed to needs_reconnection | The DSP abandoned or restarted onboarding for the store. | Contact Stream support. |
Menu not showing on DoorDash or Grubhub while pending | Expected. The menu reaches the DSP once the DSP's side of the connection exists. | Wait for APPROVED. If the menu is still missing after that, contact Stream support. |
Menu on an APPROVED connection is out of date, or a publish failed | The last publish failed, or no catalog update has triggered one since the change. | Publish the menus once. If the menu is still wrong after the publish had time to run, contact Stream support. |
Publish returns 400 | A publish is already running or not finished, or the location is missing a timezone, phone number, or menu hours. | Read the response message, then see Publish Menus for what to do. |
Publish returns 404 | The location has no APPROVED or pending connection to that DSP, or location_id is not the Stream location ID. | Use locations[]._id from View Organization Locations and check the connection's status. |
| A DSP is missing from the options you can offer | It is not enabled for your partner account. | Check GET /onboarding/integrations/dsp-options and ask your Stream representative. |
caution
Deleting the DSP integration to retry one location disconnects all of them. DELETE /onboarding/integrations/{id} disconnects the merchant's entire DSP integration, including every location bound through it. The Partner API does not currently offer unbinding, retrying, or rebinding a single location. Ask Stream support instead.
Contacting Stream support
Include these IDs so the team can find the connection straight away:
| ID | Where you get it |
|---|---|
| Organization ID | org_id from Create Org |
| Location ID | locations[]._id from View Organization Locations |
| DSP connection ID | locations[]._id from the bind response, or dsps[]._id from View Organization Locations |
| DSP and store | dsps[].source and the dsp_provider_id you bound |
| Error body | The full response body, if a call failed |