API behavior and feature status
Use this page to distinguish production contracts from behavior that still requires product-specific confirmation.
The Otter API is available on the production host
https://partners.tryotter.com. Validate integrations with controlled
production test stores and low-risk test data.
Production contracts
| Area | Contract |
|---|---|
| Authentication | Access tokens are valid for 30 days by default. The returned expires_in value is authoritative. |
| Store scope | X-Store-Id is the store identifier from your system that is linked to the authenticated application. |
| Webhook correlation | The JSON eventId and X-Event-Id header contain the same UUID. Use it for deduplication and callbacks. |
| Order creation | externalIdentifiers.id is the stable order identity. A duplicate create returns 409 Conflict and does not create another order. |
| Order paths | {orderId} is the external order identifier your app supplied at creation. |
| Order status updates | The status endpoint accepts PREPARED, CANCELED, and FULFILLED. 202 Accepted means that Otter found the order and queued the update; it does not confirm that downstream processing completed. |
| Order acceptance windows | Otter API services have no default acceptance or automatic-rejection deadline. When an integration has an acceptance window, it is configured for that integration during onboarding. A UI accept-button window is separate from server-side automatic rejection. |
| Order cancellation callbacks | An intent-to-cancel webhook can be acknowledged only by posting CANCELED with the matching X-Event-Id. The API has no cancellation-decline callback state. |
| Order status webhooks | Status webhooks expose accepted, ready-to-pickup, handed-off, and fulfilled events. They do not expose rejected or canceled status events. |
| Menu replacement | POST /v1/menus replaces the complete menu snapshot. Omitted customer-menu entities are deleted. |
| Menu jobs | A menu upsert returns 202 Accepted with a pending job. Poll until SUCCESS or FAILED; the response does not confirm that menus or photos were persisted. |
| Delivery callbacks | A quote callback supports AVAILABLE with estimates or UNAVAILABLE with an optional reason. Accept and cancel callbacks represent success only; use the delivery error callback for failures. A stored callback returns 204, while a duplicate event ID returns 409. |
| Delivery status | A 204 status response means the update was accepted for asynchronous processing. Intermediate lifecycle statuses are not synchronously required. |
| Account Pairing | Deprecated. Store onboarding and status endpoints under Account Pairing may be removed in a future release. Prefer current store-connection guidance from your Otter representative. |
| Reports | Deprecated. Date boundaries are inclusive UTC calendar dates. Downloads are comma-delimited UTF-8 CSV. Each generate request creates a new job, and polling by jobId is the reconciliation path when a best-effort webhook is missed. Otter returns EXPIRED two days after workflow completion. Contact your Otter representative for migration options. |
| Reviews | An immediate reply returns the target service's opaque replyId after the provider accepts it. A scheduled reply confirms scheduling only, provides no eventual replyId, and may execute after the requested epoch-second timestamp. |
| Finance ingestion | 202 Accepted means synchronous validation passed and the payload was published to the ingestion queue. It does not confirm downstream processing completion, including validation, order association, or persistence. Stable transaction identifiers update an existing record instead of creating a duplicate. |
Preview behavior
Treat the following behavior as Preview. Do not make it a hard dependency until your Otter representative confirms the contract for your application.
| Area | Behavior that is not yet a public guarantee |
|---|---|
| Orders | Integration-specific acceptance-window values, scheduled-order acceptance timing, cancellation no-response handling, preparation-time anchors, supported currencies and rounding, and any future synchronous status-transition policy |
| Webhooks | End-to-end replay limits, global ordering, exhaustion handling, and retention outside one sender execution |
| Delivery | A product-level quote-validity promise, whether the current callback wait is a stable SLA, accept/cancel decline representation, failure and return states, read reconciliation, and compensation guarantees |
| Menus | Inbound payload/entity/photo limits, availability behavior for template-enabled stores, complete template-menu restrictions, idempotency, and ambiguous-response recovery |
| Reports | Output timezone for timestamp columns, ORDER_STORES row ordering, and a cross-flow null-serialization guarantee |
| Reviews | Per-service reply-size discovery, scheduling lateness, scheduled-operation status or callbacks, edits/deletes, retry policy, and idempotency |
| Finance | Partner-visible processing status, retry and completion SLAs, correction finality, supported currencies and rounding, and failure reconciliation |
| Organization | Whether every organization-created connection emits the same webhook sequence as account pairing |
| API lifecycle | Support targets, certification policy, incident communication, credential-rotation procedure, PII retention, versioning, and deprecation notice periods |
How to integrate with Preview behavior
- Keep Preview-dependent code behind a feature flag or configuration.
- Capture request IDs, event IDs, external resource IDs, and submitted payloads.
- Ask your Otter representative to confirm the behavior for your application.
- Promote the dependency only after it is represented in the API reference or this guide.
Related
Next
Implement only the production contracts required for your integration, then use the scenario checklist for controlled production-store validation.