Integrate Pro Deals
The complete flow, from a new Pro Deal to its last code.
This guide walks through everything your integration does over the life of a Pro Deal. Read How it works first for the big picture.
Concepts
| Term | Meaning |
|---|---|
| Pro Deal | A campaign that gives associates at the targeted stores personal discount codes for your online store. |
| Associate | A retail store employee using the ENDVR app. Only verified associates of targeted stores can claim codes. |
| Code | A single-use discount code in your store. Each code goes to one associate. |
| Codes per associate | 1 to 5. An associate claims them one after the other: the next opens once the previous one is used. |
| Code source | generated (ENDVR generates the codes, you create them in your store) or uploaded (you create codes and upload them). |
1. Find new Pro Deals
The brand creates Pro Deals in the Brand Portal. Poll the list, for example every 15 minutes, and act on every Pro
Deal that isn't finished and still has codesReady: false:
curl "https://api.endvr.io/v1/pro-deals?limit=100" -H "Authorization: Bearer $ENDVR_API_KEY"{
"id": "6730f1c2a9d4e5b6c7d8e9f0",
"title": "Winter Pro Deal",
"status": "scheduled",
"discount": { "type": "percentage", "value": 40 },
"codesPerAssociate": 2,
"codeSource": "generated",
"codesReady": false,
"codes": { "total": 500, "available": 500, "assigned": 0, "used": 0, "deactivated": 0 },
"startsAt": "2026-11-01T00:00:00Z",
"endsAt": "2026-12-31T23:59:59Z"
}2. Load the codes into your store
Read every page of codes and create each one in your store:
let cursor = null;
do {
const url = new URL(`https://api.endvr.io/v1/pro-deals/${proDealId}/codes`);
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const page = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
for (const { code } of page.data) {
await store.createDiscountCode({ code, percentOff: proDeal.discount.value, usageLimit: 1 });
}
cursor = page.nextCursor;
} while (cursor);Prefer CSV for a bulk import tool: send Accept: text/csv.
Every code must be:
- single-use (a usage limit of 1, across all customers),
- set to the Pro Deal's discount,
- valid from the Pro Deal's start to its end.
3. Confirm the codes are live
curl -X POST https://api.endvr.io/v1/pro-deals/6730f1c2a9d4e5b6c7d8e9f0/codes/confirm \
-H "Authorization: Bearer $ENDVR_API_KEY"Until you confirm, associates can't see the Pro Deal. Once confirmed, ENDVR releases it to the targeted stores and associates claim their codes in the app. Confirming is safe to repeat; confirm again after adding codes.
4. Report every order that used a code
When an order with a Pro Deal code is placed or changes, report it. This is how ENDVR counts the Pro Deal's results, bills it, and opens the associate's next code. See Report redemptions.
5. Deactivate codes when ENDVR asks
ENDVR sends code.deactivate when a code must stop working, for example when an associate leaves a targeted store,
and pro_deal.ended when the Pro Deal ends. Disable those codes in your store. See
Receive webhooks.
6. Keep enough codes
Watch codes.available on the Pro Deal. For uploaded codes, add more before it runs out; for generated codes, read
the new codes the brand adds and create them, then confirm again.
The jobs to run
| Job | When | Calls |
|---|---|---|
| Find Pro Deals that need codes | Every 15 minutes | GET /pro-deals, GET /pro-deals/{id}/codes, POST …/codes/confirm |
| Report orders | On every order create or update with a Pro Deal code, plus a daily catch-up | POST /redemptions |
| Handle events | On every webhook | Your store's discount API |
| Sync the catalog | On product changes, plus a daily full sync | PUT /catalog/products |