Skip to content

Store data

Capability merchant Merchant · identity and services

API Spec

The implementable contract is in the Merchant API Spec — English only.

Part of the Merchant capability. Catalog is in Menus.

Merchant ID — originator-generated

Breaking change from V1

In V1, merchantId came from the Software Service (POS). In V2, merchantId is generated by the Ordering Application at onboarding. The POS keeps its own code in externalCode.

sequenceDiagram
 participant OA as Ordering Application
 participant SS as Software Service

 OA->>OA: generate merchantId
 OA->>SS: register / integrate with id + externalCode
 Note over OA,SS: same merchantId on all ops
 SS->>OA: GET /merchants/{merchantId} (or OA consumes catalog)

Rationale: no round-trip only to obtain an ID; deterministic reference from creation; simpler multi-platform reconciliation.

merchantId MUST be unique in the Ordering Application scope (UUID v4 recommended).

Identity and basic info

Descriptive fields (name, address, contacts, logo, etc.) via:

Goal Operation
Read store GET /merchants/{merchantId}
Partial update PATCH /merchants/{merchantId}
List merchants for token GET /merchants

PATCH — update store

The PATCH endpoint allows updating: - externalCode — New in V2: Software Service can now update the POS's internal store code - name, description, logoUrl — basic identity - contacts — contact info (phone, email, etc.)

Response: 202 (async processing).

V1 merchantType does not exist in V2.

Service

A merchant may have multiple services. The identifier is the type — no separate service id.

Field Required Description
type YES DELIVERY, TAKEOUT, or INDOOR
status YES OPEN, CLOSED, or PAUSED
operatingHours YES (when applicable) Hours by day of week
deliveryArea NO Radius or polygon (DELIVERY)
menuId NO Active menu — see Menus
pauseUntil NO Automatic resume if PAUSED 
GET|PUT|PATCH /merchants/{merchantId}/services/{serviceType}

Status

stateDiagram-v2
 [*] --> OPEN
 OPEN --> PAUSED: POST …/pause
 PAUSED --> OPEN: duration ends or PATCH OPEN
 OPEN --> CLOSED: schedule / operator
 CLOSED --> OPEN: schedule / operator
Status Meaning
OPEN Accepting orders for that service
CLOSED Outside hours or offline for the service
PAUSED Temporary operational pause

Pause

POST /merchants/{merchantId}/services/{serviceType}/pause

Body: durationMinutes (required), reason (optional). Response 202.
Does not rewrite operatingHours. Resume: expiry or PATCH with status: OPEN.

sequenceDiagram
 participant OA as Ordering Application
 participant SS as Software Service

 OA->>SS: POST …/services/DELIVERY/pause { durationMinutes: 30 }
 SS-->>OA: 202 Accepted
 Note over SS: status PAUSED, pauseUntil set
 OA->>SS: PATCH …/services/DELIVERY { status: OPEN }
 SS-->>OA: 202 Accepted

Operations map (store)

Goal operationId
List merchants listMerchants
Store detail getMerchant
Update basic info updateMerchant
Read service getService
Replace service replaceService
Update service updateService
Pause pauseService

Checklists

Checklist — Ordering Application

  • [ ] Generates and keeps stable merchantId
  • [ ] Correlates PDV via externalCode
  • [ ] Consumes services by type
  • [ ] Treats pause as distinct from operating hours

Checklist — Software Service

  • [ ] Hosts GET/PATCH for store and services
  • [ ] Accepts originator-owned merchantId
  • [ ] POST …/pause → PAUSED + pauseUntil
  • [ ] Does not use merchantType

Related