Merchant¶
API Spec
The implementable contract (endpoints, fields, errors, and examples) is in the Merchant API Spec — English only.
This page is the overview: what changes in V2, roles, and how the docs are split. Store and catalog details live in the child pages.
What it is for¶
The Merchant capability defines how the ecosystem exchanges the establishment and what it offers: store identity, service contexts (delivery, takeout, indoor), and catalog.
It is the source of truth for static and operational merchant data in Open Delivery — not orders, logistics, or CRM.
Merchant does not require Orders. It MAY be implemented alone (store/catalog only). Full stacks usually combine Merchant + Orders; Indoor requires Orders separately.
What changes from V1 to V2¶
Breaking — read before migrating
This is the domain with the most changes from V1. See also the migration guide.
| Topic | V1 | V2 |
|---|---|---|
| Merchant ID | Generated by PDV | Generated by Ordering Application; PDV uses externalCode |
| Catalog | Monolithic merchantUpdate webhook |
CRUD per entity + snapshot |
| Service | Identified by service id | Identified by type (DELIVERY / TAKEOUT / INDOOR) |
merchantType |
Present | Removed |
| Option prices | option_price optional; confusing subtotal |
option_price required (0 if free); no subtotal |
unity_price |
Implicit | Explicit (minor units) |
| Availability | Not standardized | quantity_available (operational signal) |
| Pause | Ad-hoc | POST …/services/{type}/pause without rewriting hours |
How the docs are organized¶
Discovery capability merchant is one. Docs split for reading:
| Page | Content |
|---|---|
| Merchant (this) | Concept, V1→V2, roles, discovery, ops map |
| Store data | Merchant ID, identity, Service, hours, area, pause |
| Menus | Hierarchy, ItemOffer, options, snapshot, sync |
Merchant (capability)
├── Store data → identity + services
└── Menus → catalog (CRUD + snapshot)
Not protocol extensions
Store data and Menus are documentation modules. The formal Indoor extension is declared in Discovery with Orders; the catalog is not — it is part of merchant.
Roles¶
| Role | Responsibility |
|---|---|
| Software Service | Operational source of the store and, typically, host of catalog and services. |
| Ordering Application | Generates merchantId, consumes store/catalog, builds the ordering experience. |
| Delivery Platform (optional) | Reads availability / delivery area when needed. |
In typical integrations, the Ordering Application is the client and the Software Service is the server for this capability’s endpoints.
Map: goal → page → operation¶
| Goal | Page | Operation (spec) |
|---|---|---|
| List app merchants | — | listMerchants |
| Read / update store | Store data | getMerchant · updateMerchant |
| Configure service / pause | Store data | getService · replaceService · updateService · pauseService |
| Catalog bootstrap | Menus | getMenuSnapshot |
| Item / option CRUD | Menus | createItemOffer · createOption · … |
Full contract: Merchant API Spec.
Discovery¶
"capabilities": {
"merchant": {
"endpoint": "https://api.example.com/od/v2",
"supportedOperations": ["getMerchant", "getMenuSnapshot", "pauseService"]
}
}
Store and menus in the same capability — no extension key for catalog. Guide: Discovery.
Authorization¶
OAuth 2.0 Bearer. Preferred scope: od.menu (or equivalent declared in the manifest). See Authentication.
Out of scope here¶
| Topic | Where |
|---|---|
| Order lifecycle | Orders |
| Dine-in account | Indoor (requires Orders) |
| Delivery | Logistics |
| Customer data | Customer |
Out of MVP¶
| Topic | Status |
|---|---|
Fine-grained catalog delta webhook (successor to merchantUpdate) |
Not core V2 — use snapshot + CRUD |
| Free-form custom fields on merchant | Out of MVP (committee) |
| Multi-channel stock | Out of scope; quantity_available is operational only |