> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Base URL, resource conventions, IDs, money, and list behavior shared across every Developer API endpoint.

The Developer API is a JSON REST API. Every endpoint in this reference is grouped in the sidebar by resource — auth, locations, connections, menu, orders, and webhooks. This page covers the conventions they all share; the linked concept pages go deeper.

## Base URL

Each environment has its own host, both served under the `/v1` prefix:

```
https://api.staging.maple.inc/v1   # Sandbox — development and testing
https://api.maple.inc/v1           # Production — live traffic
```

Use the credential that matches the host (`mpk_test_…` in the sandbox, `mpk_live_…` in production). See [Environments](/developer-api/concepts/environments).

## Authentication

Send a `Bearer` credential on every request:

```http theme={null}
Authorization: Bearer mpk_test_…
```

Send your API key (`mpk_test_…` for the sandbox, `mpk_live_…` for production) as the bearer token. `GET /v1/me` returns the app, environment, and scopes for any key. Full detail in [Authentication](/developer-api/concepts/authentication).

## Resource conventions

* **Opaque IDs** carry a type prefix — `str_` (location), `ord_` (order), `dws_` (webhook subscription), `evt_` (event), and so on. Treat them as opaque strings.
* **Money is integer USD cents.** `450` means \$4.50. Never parse amounts as floats. Currency codes are always uppercase ISO‑4217 (`USD`).
* **Field casing.** Menu payloads use camelCase (`externalId`, `minSelections`, `modifierGroups`); order and webhook payloads use snake\_case (`fulfillment_type`, `menu_entity_id`, `payment_status`). A line item's `menu_entity_id` carries the `externalId` you published for that menu object.
* **Timestamps** on events and orders are Unix seconds (the `created` field).
* **Object typing.** Most resources carry an `object` field (`order`, `location`, `event`, …) so you can tell them apart.

## Lists

List endpoints return an envelope with an `object` of `list` and a `data` array:

```json theme={null}
{ "object": "list", "data": [ /* … */ ] }
```

Lists return a **bounded, most-recent-first window** rather than full cursor pagination:

* `GET /v1/orders` returns up to 100 orders and includes a `has_more` flag indicating more exist.
* `GET /v1/webhook_events` returns up to 50 events, most recent first.
* `GET /v1/locations` and `GET /v1/webhook_subscriptions` return the full set for your app.

For complete history and recovery, use the [event ledger and replay](/developer-api/concepts/webhooks#the-event-ledger) rather than paging.

<Note>
  **Filtering and pagination on `GET /v1/orders` are under construction.** The endpoint takes no query parameters today
  — it returns the 100 most-recent orders across **all** of your connected locations, with `has_more` signalling that
  more exist. There's no `location_id` filter or cursor to page further back yet; both are coming. For now, rely on
  `order.notification` webhooks to receive orders as they happen, and treat the list endpoint as a recent-activity view.
</Note>

## Errors

Errors use standard HTTP status codes with a JSON body carrying a stable `_tag` and a human-readable `message`. Branch on the tag, not the message. The full catalog is in [Errors](/developer-api/concepts/errors).

## Rate limits

There are no published per-app rate limits today. Be a good citizen — respond to webhooks asynchronously, avoid tight polling loops (you don't need to poll; orders are pushed), and retry `5xx` responses with exponential backoff and jitter.