Getting started with the Ewity Platform Orders API

The Ewity Platform Orders API lets external platforms (third-party
ordering apps, marketplaces, websites) submit orders into Ewity for
fulfillment and settlement. Once integrated your platform can:

1. Sync the catalogue — pull merchant categories, products, variants, and modifiers per online location.
2. Validate a cart in real time — check stock, compute taxes, get a bill preview before placing the order.
3. Create orders directly against an Ewity online location, attached to your platform.
4. Track order status as the merchant accepts / fulfills / completes the order.
5. Record payments you collected from the customer against the order's bill, including partial settlements.

Cart and customer state live on your side. The API does not expose
cart create / update / get endpoints, and does not manage customer
records on your behalf. Run your own cart, your own customer profiles,
and call Validate Cart and Create Order directly when ready.

All endpoints are JSON over HTTPS under the prefix /platform-v1.

Build your first integration

Three calls in this order get you from zero to a placed order.

Order lifecycle

created (pending) ─►  acknowledged ─►  accepted ─►  ready-for-pickup ─►  on-delivery ─►  completed
                                          │
                                          └─►  Bill is generated here
                                          └─►  Payments can now be recorded

Any state ─►  cancelled

Two consequences for your integration:

1. Bills don't exist until the merchant accepts the order. Recording a
   payment immediately after creating an order returns 400 until
   acceptance. The accept happens in the merchant's POS app.
2. The paid flag flips to true only when cumulative payments cover the
   bill total. Partial payments are supported.

Sync the catalogue

Ewity is the source of truth for products, prices, modifiers, and
availability. Two integration patterns to choose from:

Sync periodically (e.g. every 15 min) and after StoreTurnedOn webhooks.

Things to know

• Maldives only. The API is currently scoped to Maldives merchants —
  mobiles are normalised to +960..., currency comes from the merchant's
  company settings (typically MVR). Reach out to integrations if you have
  a non-Maldives merchant.
• Every application gets a sandbox. Creating an application in the
  Developer Portal automatically provisions
  your own seeded sandbox company for end-to-end testing — see
  Signing up.
• Bills are merchant-gated. Orders start in pending with no bill;
  payments only work after acceptance. Build "awaiting confirmation" UX.
• No payment_method at order create. payment_method on the
  response is always null for orders you create. Record what you
  collected via Record Payment after the merchant accepts.
• Quantities have two fields. unit_quantity is what the customer
  ordered in the variant's selling unit (2 pizzas, 1.5 kg of fish);
  quantity is the same value converted to the product's base unit
  (2 pcs, 1500 g). Send unit_quantity on input; both come back on
  reads.
• Validate, then create. Stock and prices can change between calls —
  always validate immediately before creating.
• Fees you send replace auto-fees. Sending a fees[] array on
  Create Order overrides the location's auto-applied fees. Omit the
  field to keep auto-fees.
• Modifier ids are variant ids. They reference modifier-products in
  the catalogue; inline name / price is not accepted.
• Currency comes from the merchant. Read it off total_components
  rather than hard-coding it.
• Idempotency is on you. None of the write endpoints are idempotent
  on their own. Track platform-side request ids and reconcile against the
  id returned in the response.
• ref is capped at 150 chars. Payment refs longer than that are
  truncated server-side.
• No pagination, no enforced rate limit (yet). List endpoints return
  the full collection; please be reasonable about polling — limits may be
  added without notice if the API is abused.

Common error format

{
  "code": 400,
  "errorCode": "BAD_REQUEST",
  "message": "Human-readable explanation",
  "errorRef": "MTYZN",
  "ts": 1777666545
}