Skip to content

Changelog

Version history of the Open Delivery Protocol.

V2.0.0-rc Release Candidate · July 2026 · V1 remains active during transition

How to read this changelog

This changelog is organized by capability/module to simplify implementation and migration.

Legend:

  • Breaking: requires contract or behavior changes.
  • New: new capability or functional block in V2.
  • Improvement: clarification, normative reinforcement, or evolution without direct contract break.

V2.0.0-rc - July 2026

First Release Candidate of V2. This release opens an ecosystem validation phase; V1 remains active during transition.

Status: ecosystem validation

Publishing the RC starts a validation period, not the stable release. In this phase:

  1. Review - companies and implementers review the documentation (guide, protocol, and API Specs).
  2. Pilot - selected companies implement parts of the specification in controlled environments and validate real flows.
  3. Feedback - adjustments and clarifications may be incorporated based on review and pilot outcomes.
  4. Release - only after that validation will V2 be promoted to a stable release.

Until then, V1 remains active and is the reference for production integrations.

Changes by capability

Discovery

  • Improvement: /.well-known/opendelivery is now mandatory to declare capabilities, versions, and integration modes before integration activation.

References: Discovery Protocol · Discovery API Spec

Authentication

  • Breaking: auth by application, with one client_id per software (not per store).
  • Improvement: domain-based scope standardization (od.orders, od.menu, od.logistics, od.crm, od.all).
  • Improvement: optional Authorization Code Flow for advanced cases.

References: Authentication Protocol · Authentication API Spec

Merchant

  • Breaking: merchantId is now generated by the originator; POS correlates with externalCode.
  • Breaking: merchantType removed.
  • Breaking: services are identified by type (DELIVERY, TAKEOUT, INDOOR) without a separate id.
  • Breaking: Service shape was simplified (no service id; focus on type + status; operatingHours replaces the legacy schedule model).
  • Breaking: legacy V1 onboarding/status endpoints (/v1/merchantOnboarding, /v1/merchantStatus) are no longer part of the normative Merchant V2 contract.
  • Improvement: explicit per-service pause semantics.
  • Improvement: catalog bootstrap/reconciliation via GET .../snapshot; merchantUpdate/menuUpdated is no longer the core sync path.

References: Merchant Protocol · Merchant API Spec

  • Breaking: end of the monolithic V1 merchantUpdate webhook.
  • Breaking: adoption of granular CRUD per catalog entity.
  • Breaking: subtotal on options removed; use option_price (required) and unity_price.
  • Improvement: recursive options with nested OptionGroups.
  • Improvement: quantity_available on ItemOffer for operational availability.

References: Menu Protocol · Merchant API Spec

Orders

  • Breaking: originator cancellation handshake (ORDER_CANCELLATION_REQUEST + accept/deny) removed; mandatory cancellation via CANCELLED.
  • Breaking: PICKED_UP event removed.
  • Breaking: Order.type removed from root; profile moves to Order.fulfillment.orderType.
  • Breaking: Order.delivery, Order.takeout, and Order.indoor moved under Order.fulfillment.*.
  • Breaking: timing was unified under Order.timing (orderTiming, schedule, preparationStartDateTime, orderPriority), and schedule is now required when orderTiming = SCHEDULED.
  • Breaking: item/option pricing fields are grouped under pricing in Order.items[*] and Order.items[*].options[*], while keeping V1 price format (Price { value, currency }).
  • Breaking: subtotalPrice was removed from item and option pricing in Orders V2.
  • Breaking: Order.status becomes authoritative in GET /orders/{id}.
  • Breaking: for DELIVERY orders, Order.customer is now required in the payload.
  • New: order-origin metadata with Order.context.salesChannel and order-level notes in Order.observations.
  • New: Order.items[*].itemOfferId, Order.items[*].options[*].defaultQuantity, and nested options support (Order.items[*].options[*].options).
  • New: optional CRM/Loyalty customer fields (Order.customer.birthDate and Order.customer.gender).
  • Improvement: explicit separation between status and events.
  • Improvement: repeated already-applied operation follows async pattern with 202 Accepted (no additional transition).

References: Orders Protocol · Orders API Spec · Conventions

Logistics

  • Improvement: async-first semantics (202 Accepted) consolidated for delivery lifecycle operations.
  • Improvement: alignment with discovery for tracking modes (push/pull).

References: Logistics Protocol · Logistics API Spec

Customer

  • New: capability for customer data, leads, and reviews in V2.

References: Customer Protocol · Customer API Spec

Loyalty

  • New: loyalty capability/module (points, cashback, coupons, rewards) within the CRM/Customer domain.

References: Loyalty Protocol

Indoor

  • New: capability for in-store operations (table, tab, counter), with central account and async behavior.

References: Indoor Protocol · Indoor API Spec

Cross-cutting changes

  • Improvement: V2 reinforces async integration as default (202 Accepted for mutations).
  • Improvement: clearer split between domain narrative (Protocol) and implementable contract (API Spec).

V1.7.0

V1 remains active during transition.

For differences and migration, see: V1->V2 Migration Guide.

Related