Skip to main content

Create an order

Push a new order into Otter and follow status through fulfillment.

Before you begin​

Steps​

  1. Create the order with POST /v1/orders (see API reference for the body). Include X-Store-Id and a stable externalIdentifiers.id.
  2. When the restaurant accepts (or integration-specific automation accepts), Otter sends an order status webhook with ORDER_ACCEPTED. Otter API integrations have no universal acceptance or automatic-rejection deadline; confirm any configured window during onboarding.
  3. (Optional) When the order is ready for pickup, Otter sends a status webhook with ORDER_READY_TO_PICKUP.
  4. Update the order to PREPARED with POST /v1/orders/{orderId}/status when your side marks prep complete (if your flow requires it).
  5. (Optional) When the order is handed off, Otter may send ORDER_HANDED_OFF.
  6. Update the order to FULFILLED with POST /v1/orders/{orderId}/status when the order is complete on your side.

Creation Flow

Verify​

Create a test order and confirm:

  • POST /v1/orders returns success and an order id
  • Repeating the request with the same externalIdentifiers.id returns 409 Conflict and does not create a duplicate order
  • You receive ORDER_ACCEPTED (or equivalent) on your webhook with a valid X-HMAC-SHA256
  • Status updates to PREPARED / FULFILLED return 202 Accepted for that order id. This confirms that the update was queued, not that downstream processing completed.

Common failures​

SymptomLikely causeFix
Create fails with store errorsMissing/wrong X-Store-Id or store not linkedRe-check store onboarding
Retry returns 409 ConflictThat external order id already existsTreat the original create as the business action; reconcile using your stored external id
No status webhooksWebhook not registered or URL unreachableFix registration; check URL
Signature check failsWrong secret or body bytesUse raw body + endpoint secret

Next​