Skip to main content

Quickstart

Get credentials, connect a store, call the Otter API, and receive a verified webhook — in one path.

By the end of this guide you will have application credentials, at least one linked store, a successful authenticated API call, and a webhook endpoint that validates Otter signatures.

Before you begin​

  • A technical contact who can store secrets securely
  • A publicly reachable HTTPS URL for webhooks (or a tunnel such as ngrok for local testing)
  • Agreement with your Account Representative on which products you are building (orders, menus, storefront, and so on)

Step 1: Register your application​

External partners need a registered application before calling the Otter API. Registration is manual.

  1. Contact your Account Representative and ask them to register your application.
  2. You receive:
  • Application ID (also called Partner ID in older materials — treat them as the same)
  • Client secret
  1. Store the client secret in your secrets manager. Never commit it to source control or expose it in a browser or mobile app.

Verify​

You have Application ID and client secret stored securely. See the API reference for authentication and base URLs.

Step 2: Authenticate and make your first call​

The Otter API uses OAuth 2.0 access tokens. Most partner apps start with the client credentials flow. See Authentication for flows, headers, scopes, and webhook verification.

  1. Obtain an access token from POST /v1/auth/token using your Client ID and client secret (details in the API reference).
  2. Call a simple authenticated endpoint with:
Authorization header
Authorization: Bearer <access_token>
  1. Confirm you get a successful response before wiring a full workflow.

Verify​

A successful authenticated response with your credentials means the application is wired correctly.

Step 3: Connect your stores​

Every restaurant location your app acts on must be paired with Otter. Store-scoped requests send the Otter store identity in X-Store-Id. Pairing paths (Account Representative, account pairing APIs, organization OAuth): Stores and connections.

  1. Ask your Account Representative to onboard each store, or automate pairing with Stores & account pairing / Organization onboarding when your product supports it.
  2. After linking, note the store ID Otter expects for that location.
  3. Send it on store-scoped requests:
Store-scoped request headers
Authorization: Bearer <access_token>
X-Store-Id: <store_id>

Verify​

Call a store-scoped endpoint from the API reference with X-Store-Id set. You should not get an unknown-store or authorization error for that header.

Step 4: Register webhooks and verify signatures​

Otter pushes events (order status, menu failures, storefront changes, and more) to HTTPS endpoints you control. Mental model (REST vs webhooks, ack, error callbacks): Events and webhooks.

  1. Ask your Account Representative to register your webhook URL(s) and choose an authentication type per endpoint.
  2. Save the webhook secret for each endpoint (Otter Developer Portal or your Account Representative).
  3. Implement your receiver to:
  • Accept POST with JSON
  • Validate X-HMAC-SHA256 on every request — see Keep webhooks secure
  • Return 2xx quickly; do heavy work asynchronously
  1. Subscribe to the event types your product needs.

Verify​

Trigger a test event (or complete a small flow that emits one). Your endpoint should receive the request, pass signature validation, and respond with 2xx.

Checklist​

You're done when:

  • Application ID + client secret stored securely
  • Authenticated API call succeeds
  • At least one store linked; X-Store-Id accepted
  • Webhook URL registered; signature validation passes

Common failures​

SymptomLikely causeFix
401 on API callsWrong secret or expired tokenConfirm credentials; refresh the bearer token
Store errors on resource callsMissing/wrong X-Store-Id or store not linked to this appRe-check store onboarding; use the Otter-linked id
No webhooksURL not registered, HTTP (not HTTPS), or firewallConfirm Otter can reach the URL
Signature check failsWrong secret or hashing decoded/parsed bodyUse the raw request body bytes — see Keep webhooks secure
Frequent 429Hitting rate limitsBack off with jitter; contact your TAM if normal traffic is limited

Next​