OpenDelivery Compliance

Zupy is an OpenDelivery 2.0-compliant participant

Zupy is OpenDelivery 2.0 compliant for the Customer (Loyalty) capability. If your platform already speaks OpenDelivery, you can integrate with Zupy loyalty using the standard — discover us via our manifest, authenticate with client_credentials, and receive signed events. No Zupy-proprietary contract required.

What OpenDelivery is

OpenDelivery is an open Brazilian standard that defines how ordering platforms, delivery logistics, and merchant software interoperate. Zupy participates as a Customer capability provider (loyalty programs, accounts, transactions, rewards, coupons, and redemptions), so any OpenDelivery-aware ordering application can read a customer’s loyalty state and issue redemptions through a documented, non-proprietary interface.

Attribute	Value
Protocol version	`2.0`
Capability	`customer` (Loyalty), version `1.0.0`
API base URL	`https://api.zupy.com/v2`
Discovery manifest	`https://api.zupy.com/.well-known/opendelivery`
Grant type	`client_credentials`
Client ID generation	`by_app` and `by_merchant` (hybrid)

1. Discovery — find us via the manifest

Zupy publishes a public Discovery manifest at the well-known path. It advertises our protocol version, authentication models, and the exact operations we support — no need to coordinate out-of-band.

Discovery request

curl https://api.zupy.com/.well-known/opendelivery

Manifest (live)

{
  "appId": "39380028-0002-4d96-a557-fa05550b4a1c",
  "openDelivery": { "currentVersion": "2.0", "supportedVersions": ["2.0"] },
  "discovery": { "version": "1.0.0" },
  "authentication": {
    "supportedGrantTypes": ["client_credentials"],
    "clientIdGeneration": ["by_app", "by_merchant"]
  },
  "capabilities": {
    "customer": {
      "supported": true,
      "version": "1.0.0",
      "endpoint": "https://api.zupy.com/v2",
      "supportedOperations": [
        "listLoyaltyPrograms", "getLoyaltyProgramById",
        "listCustomerLoyaltyAccounts", "getLoyaltyAccountById",
        "listLoyaltyTransactions", "listLoyaltyRewards",
        "listLoyaltyCoupons", "createLoyaltyRedemption"
      ],
      "supportsBatchGet": true,
      "supportsBatchPost": false,
      "acceptedGetPeriodicity": "real_time"
    }
  }
}

appId is Zupy’s single, stable participant identity — the same value appears in every webhook we send (X-App-Id). It is not per-partner.

2. Authentication — two models, both standard

OpenDelivery allows a provider to declare more than one clientIdGeneration model. Zupy declares both, so you pick the one that fits your integration:

by_app (recommended)

One credential for your application, valid across all merchants linked to it. Best for platforms that integrate many Zupy merchants. Each merchant is activated by the merchant themselves via a toggle in their Zupy dashboard. Provisioned by the Zupy partnerships team.

by_merchant (self-serve)

One credential per merchant, provisioned by the merchant from their own dashboard (/integrations). Best when a single merchant wants to connect an app Zupy hasn’t formally partnered with yet. No partnership required.

Both models use the client_credentials OAuth2 grant to obtain a bearer token, and both are exposed identically at https://api.zupy.com/v2.

Selecting a merchant with `by_app`

A by_app token can reach multiple merchants, so each request must name which merchant it targets using the X-App-MerchantId header. Zupy only serves data for merchants whose toggle links your application — anything else is denied.

X-App-MerchantId

string

The merchant identifier as your application knows it (the OpenDelivery merchantId). Zupy maps it to the merchant internally. Required on every by_app read.

3. Merchant identity — two-sided by design

OpenDelivery models a merchant with two identifiers, and Zupy stores both:

Field	Owner	Zupy value
`externalCode`	The software service (Zupy)	`Company.od_merchant_id` (a stable UUID)
`merchantId`	The ordering application (you)	the id you assign, carried in `X-App-MerchantId`

Call GET /v2/merchants with your token to list every merchant your credential can reach, each returned with both identifiers.

4. Supported operations

All eight Customer/Loyalty operations are live at https://api.zupy.com/v2. List operations are paginated ({ items, page, pageSize, total }).

Operation	Method & path
`listLoyaltyPrograms`	`GET /loyalty/programs`
`getLoyaltyProgramById`	`GET /loyalty/programs/{id}`
`listCustomerLoyaltyAccounts`	`GET /loyalty/accounts`
`getLoyaltyAccountById`	`GET /loyalty/accounts/{id}`
`listLoyaltyTransactions`	`GET /loyalty/transactions`
`listLoyaltyRewards`	`GET /loyalty/rewards`
`listLoyaltyCoupons`	`GET /loyalty/coupons`
`createLoyaltyRedemption`	`POST /loyalty/redemptions` → `202 Accepted`

Redemption is asynchronous: POST /loyalty/redemptions returns 202 with a correlationId. A 409 means the account can’t afford the reward. Redemptions are single-unit (quantity must be 1).

5. Webhooks — signed OpenDelivery events

When loyalty state changes, Zupy sends a signed event to your registered webhook URL. Events use the OpenDelivery envelope (id, eventType, occurredAt, accountId, customerId, programId, payload).

`eventType`	Fired when
`loyalty.points.earned`	The customer earns points
`loyalty.redemption.created`	A reward is redeemed (coupon issued)
`loyalty.coupon.used`	A coupon is consumed at the point of sale
`loyalty.tier.changed`	The customer moves loyalty tier

Every webhook carries these headers:

X-App-Id

string

Zupy’s participant appId — identical across all our webhooks.

X-App-MerchantId

string

The merchant this event belongs to (the merchantId you assigned).

X-App-Signature

string

Lowercase hex HMAC-SHA256 of the raw request body, signed with your webhook secret — no sha256= prefix. Verify it before trusting the payload.

Always verify X-App-Signature against the raw body bytes (not a re-serialized JSON) using your webhook secret. Reject any request whose signature does not match.

6. Inbound — accrue points from orders

If your platform owns the orders, you can have Zupy award loyalty points automatically when a sale happens — and reverse them if that sale is cancelled. Zupy is the loyalty host: you send two signals, we do the rest (we never track your order lifecycle — when to send each signal is entirely your call). Send an OpenDelivery CustomerEventEnvelope to:

Accrue / reverse

POST https://api.zupy.com/v2/customer-events/
Authorization: Bearer <your OAuth2 token>   # by_app also sends X-App-MerchantId

`eventType`	Zupy does
`order.created`	Awards points for the order (using the merchant’s configured rate)
`order.cancelled`	Reverses the points that order awarded

Both are authenticated with the same OAuth2 credential you use for reads (by_app or by_merchant) — no separate scheme. A minimal envelope:

order.created

{
  "id": "evt-9c1f",
  "eventType": "order.created",
  "occurredAt": "2026-07-19T12:00:00Z",
  "customerIdentifier": { "type": "phone", "value": "+5511999998888" },
  "orderId": "order-abc123",
  "payload": { "id": "order-abc123", "totalAmount": 5000 }
}

customerIdentifier

object

{ type, value } — type is phone or email (a document/CPF-only customer is skipped, no lookup). The customer is enrolled automatically if new.

payload.totalAmount

number

Order total in cents (OpenDelivery convention). Zupy converts to the base currency before applying the points rate.

Idempotent by orderId. Re-sending the same order.created never double-credits; re-sending order.cancelled never double-reverses. A cancel for an order that was never credited is a no-op.

Accrual is opt-in per merchant. A merchant must have an OpenDelivery accrual rate configured; until then, order.created is accepted (204) but awards nothing. When points are awarded, Zupy emits the loyalty.points.earned webhook back to you (§5).

A response of 204 means accepted. Unknown OpenDelivery event types are rejected (422); other known-but-non-loyalty events (e.g. order.delivered) are acknowledged (202) and ignored.

Reference

OpenDelivery spec

The normative OpenDelivery 2.0 specification.

Partner Onboarding

What you receive and how to go live.

Outbound Webhooks

Webhook delivery, retries, and signature verification in depth.

Get a credential

Contact the Zupy partnerships team for a by_app credential.

Introduction

Guides

What OpenDelivery is

1. Discovery — find us via the manifest

2. Authentication — two models, both standard

by_app (recommended)

by_merchant (self-serve)

Selecting a merchant with `by_app`

3. Merchant identity — two-sided by design

4. Supported operations

5. Webhooks — signed OpenDelivery events

6. Inbound — accrue points from orders

Reference

OpenDelivery spec

Partner Onboarding

Outbound Webhooks

Get a credential

​What OpenDelivery is

​1. Discovery — find us via the manifest

​2. Authentication — two models, both standard

by_app (recommended)

by_merchant (self-serve)

​Selecting a merchant with by_app

​3. Merchant identity — two-sided by design

​4. Supported operations

​5. Webhooks — signed OpenDelivery events

​6. Inbound — accrue points from orders

​Reference

OpenDelivery spec

Partner Onboarding

Outbound Webhooks

Get a credential

What OpenDelivery is

1. Discovery — find us via the manifest

2. Authentication — two models, both standard

Selecting a merchant with `by_app`

3. Merchant identity — two-sided by design

4. Supported operations

5. Webhooks — signed OpenDelivery events

6. Inbound — accrue points from orders

Reference