Skip to Content
Developers

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

TermMeaning
Pro DealA campaign that gives associates at the targeted stores personal discount codes for your online store.
AssociateA retail store employee using the ENDVR app. Only verified associates of targeted stores can claim codes.
CodeA single-use discount code in your store. Each code goes to one associate.
Codes per associate1 to 5. An associate claims them one after the other: the next opens once the previous one is used.
Code sourcegenerated (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

JobWhenCalls
Find Pro Deals that need codesEvery 15 minutesGET /pro-deals, GET /pro-deals/{id}/codes, POST …/codes/confirm
Report ordersOn every order create or update with a Pro Deal code, plus a daily catch-upPOST /redemptions
Handle eventsOn every webhookYour store's discount API
Sync the catalogOn product changes, plus a daily full syncPUT /catalog/products

On this page