# Use these docs with AI (/docs/api/ai) These docs are written to be read by people and by AI tools. | Resource | URL | Use it for | | --- | --- | --- | | OpenAPI 3.1 spec | [`/openapi.yaml`](/openapi.yaml) | Code generators, API clients, Postman or Bruno imports, and agents that read specs. | | Docs index | [`/llms.txt`](/llms.txt) | A map of every page, in the [llms.txt](https://llmstxt.org) format. | | Every page in one file | [`/llms-full.txt`](/llms-full.txt) | Pasting the whole documentation into a chat or a coding agent. | | One page as Markdown | `Copy Markdown` at the top of each page | Giving an assistant exactly the page you're on. | ## With a coding agent [#with-a-coding-agent] Point your agent at the spec and the guide you're implementing: ```txt Read https://docs.endvr.io/openapi.yaml and https://docs.endvr.io/llms.mdx/docs/api/guides/pro-deals.md. Build a job for our WooCommerce store that finds new ENDVR Pro Deals, creates their codes as single-use coupons, confirms them, and reports every order that used one. Verify webhook signatures as described in https://docs.endvr.io/llms.mdx/docs/api/guides/webhooks.md. ``` ## Generate a client [#generate-a-client] ```bash npx @openapitools/openapi-generator-cli generate -i https://docs.endvr.io/openapi.yaml -g typescript-fetch -o ./endvr-client ``` Any OpenAPI 3.1 generator works. # Authentication (/docs/api/authentication) Every call carries a brand **integration key** as a bearer token: ```http Authorization: Bearer endvr_ik_live_... ``` ## Create a key [#create-a-key] The **Other platforms** card is not in the Brand Portal yet: today **Brand Settings › Integrations** only offers Shopify. It ships together with the Client API. An **Owner** or **Admin** of the brand will create keys in the Brand Portal under **Brand Settings › Integrations › Other platforms**, choosing the e-commerce platform. The key is shown **once**: copy it into your secret manager right away. ENDVR only keeps a hash and can't show it again. A key belongs to one brand and one connection. It is meant for servers: never put it in a browser, a mobile app or a public repository. ## Test and live keys [#test-and-live-keys] | Prefix | Mode | What it does | | --- | --- | --- | | `endvr_ik_test_` | `test` | Writes test data. Test redemptions are never billed and never open an associate's next code. | | `endvr_ik_live_` | `live` | Writes real data. Redemptions are billed according to your ENDVR plan. | `GET /connection` tells you which mode a key is in. See [Test mode](/docs/api/testing). ## Rotate a key [#rotate-a-key] Create a new key in the portal and deploy it. The old key keeps working for **24 hours** after the rotation, so you can switch without downtime. Revoke a key immediately if it leaks. ## Errors [#errors] A missing, unknown or revoked key answers `401` with an [`unauthorized`](/docs/api/errors#unauthorized) problem. # Errors (/docs/api/errors) Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with the `application/problem+json` content type: ```json { "type": "https://docs.endvr.io/docs/api/errors#validation-failed", "title": "Validation failed", "status": 422, "requestId": "req_7trb2hnc8kq2", "errors": [ { "path": "redemptions[0].orderAmount", "message": "must be a decimal string such as \"129.90\"" } ] } ``` `type` is stable: branch on it, not on `title` or `detail`, which can change. Quote `requestId` when you contact ENDVR. Batch writes that are well formed answer `200` even if some items were rejected: check each item result (see [Report redemptions](/docs/api/guides/redemptions#batches-and-results)). ## Error types [#error-types] ### unauthorized [#unauthorized] `401`. The key is missing, unknown or revoked. Check the `Authorization` header and the key in the Brand Portal. Don't retry. ### forbidden [#forbidden] `403`. The key is valid but can't do this, for example because the brand paused the connection. Don't retry. ### not-found [#not-found] `404`. The Pro Deal, product or other resource doesn't exist for this brand. Don't retry. ### conflict [#conflict] `409`. The resource is not in a state that allows the call, for example uploading codes to a Pro Deal that generates its own, or sending a test webhook before setting an endpoint. Fix the state first. ### validation-failed [#validation-failed] `422`. The request is malformed. `errors` lists each invalid field. Fix the request; don't retry it unchanged. ### rate-limited [#rate-limited] `429`. Too many requests. Wait for the `Retry-After` seconds, then retry. See [Rate limits](/docs/api/rate-limits). ### internal-error [#internal-error] `500`, `502`, `503` or `504`. Something failed on ENDVR's side. Retry with exponential backoff; writes are safe to retry. # Sync your catalog (/docs/api/guides/catalog) ENDVR uses your product catalog when the brand builds campaigns, for example to pick the products of a training module or a Pro Deal. Keep it in sync from your store. ## Upsert products [#upsert-products] `PUT /catalog/products` creates or replaces up to 100 products, keyed by **your** product and variant ids. Sending a product again replaces the stored copy, variants included, so always send the full product. ```bash curl -X PUT https://api.endvr.io/v1/catalog/products \ -H "Authorization: Bearer $ENDVR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "products": [{ "id": "prod_1001", "title": "Trail Runner 2", "url": "https://shop.example.com/products/trail-runner-2", "imageUrl": "https://shop.example.com/images/trail-runner-2.jpg", "variants": [ { "id": "var_1001_42", "sku": "TR2-BLK-42", "title": "Black / 42", "price": "159.00", "currency": "USD" } ] }] }' ``` Each product comes back as `accepted`, `duplicate` (nothing changed) or `rejected` with a reason. ## Archive products [#archive-products] When a product leaves your store, archive it: ```bash curl -X DELETE https://api.endvr.io/v1/catalog/products/prod_1001 \ -H "Authorization: Bearer $ENDVR_API_KEY" ``` Archived products can't be added to new campaigns; campaigns that already use them keep them. Upsert the product again to restore it. ## Read back [#read-back] - `GET /catalog/products?updatedSince=…` lists what changed, to reconcile after an outage. - `GET /catalog/products/{id}` reads one product, archived or not. ## A sync that holds [#a-sync-that-holds] 1. **On change:** when a product is created or updated in your store, upsert it. When it is deleted or unpublished, archive it. 2. **Daily full sync:** upsert every published product in batches of 100. Unchanged products come back as `duplicate`. 3. **Clean-up:** list ENDVR's products and archive any your store no longer has. # Go-live checklist (/docs/api/guides/go-live) Run through this list with your test key, then switch. ## Integration [#integration] - [ ] `GET /connection` returns the right brand and platform. - [ ] New Pro Deals are found, their codes are created in the store as single-use codes with the right discount and dates, and they are confirmed. - [ ] Every order with a Pro Deal code is reported when placed and again when it changes. - [ ] `orderAmount` excludes tax and shipping and is after discounts. - [ ] A daily catch-up job re-sends the last days of redemptions. - [ ] Each item result is checked, and `rejected` items are logged. - [ ] The catalog is synced on change and once a day. ## Webhooks [#webhooks] - [ ] The endpoint is HTTPS and verifies every signature. - [ ] It answers `2xx` quickly and processes in the background. - [ ] It skips events it already handled (by `webhook-id`). - [ ] `code.deactivate` and `pro_deal.ended` disable the codes in the store. - [ ] `POST /webhooks/test` succeeds for both event types. ## Operations [#operations] - [ ] Keys and the webhook secret are in a secret manager, not in code. - [ ] `429` answers are retried after `Retry-After`; `5xx` answers with backoff. - [ ] You log the `requestId` of every error. - [ ] Someone gets alerted when the integration fails. ## Switch [#switch] 1. Create a **live** key in the Brand Portal. 2. Deploy it and set the webhook endpoint with it (live and test have separate settings). 3. Check `GET /connection` shows `mode: live`, then watch the first live redemptions with `GET /redemptions`. # Integrate Pro Deals (/docs/api/guides/pro-deals) This guide walks through everything your integration does over the life of a Pro Deal. Read [How it works](/docs/api) first for the big picture. ## Concepts [#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 [#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`: ```bash curl "https://api.endvr.io/v1/pro-deals?limit=100" -H "Authorization: Bearer $ENDVR_API_KEY" ``` ```json { "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 [#2-load-the-codes-into-your-store] Read every page of codes and create each one in your store: ```js 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`. Create the codes in your store first, then upload them, up to 100 per call: ```bash curl -X POST https://api.endvr.io/v1/pro-deals/6730f1c2a9d4e5b6c7d8e9f0/codes \ -H "Authorization: Bearer $ENDVR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "codes": ["ACME-PRO-0001", "ACME-PRO-0002"] }' ``` Upload at least `codesPerAssociate` × the number of associates you expect. You can add more codes at any time. 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 [#3-confirm-the-codes-are-live] ```bash 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 [#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](/docs/api/guides/redemptions). ## 5. Deactivate codes when ENDVR asks [#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](/docs/api/guides/webhooks). ## 6. Keep enough codes [#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 [#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` | # Report redemptions (/docs/api/guides/redemptions) A **redemption** is an order in your store that used a Pro Deal code. Report each one, and report it again whenever the order changes. ## What to send [#what-to-send] ```json { "code": "PRO-7KQ2-XM4D", "orderId": "10042", "orderAmount": "129.90", "currency": "USD", "processedAt": "2026-11-17T14:03:00Z", "status": "paid", "updatedAt": "2026-11-17T14:03:00Z", "refunds": [] } ``` | Field | What to put | | --- | --- | | `code` | The Pro Deal code applied to the order, as the associate typed it. | | `orderId` | Your order id. Together with `code`, it identifies the redemption. | | `orderAmount` | The sum of the order's line items **after discounts, without tax or shipping**, as a decimal string. | | `currency` | The order's currency, ISO 4217. | | `processedAt` | When the order was placed. | | `status` | `paid`, `cancelled` or `voided`. | | `updatedAt` | When the order last changed in your store. | | `refunds` | Optional. Refunds are stored for reference and never billed. | The first `orderAmount` ENDVR receives for an order is the one billed, according to your ENDVR plan. Later updates change the status and refunds you see, not the billed amount. Refunds and cancellations are not credited. ## When to send [#when-to-send] - **When the order is placed**, as soon as you can: the associate's next code opens only once this one is reported. - **When the order changes** (paid, cancelled, voided, refunded), with a newer `updatedAt`. - **In a daily catch-up job** that re-sends the last few days. Re-sending is safe. ## Retries are safe [#retries-are-safe] A redemption is unique on `(code, orderId)`: - a new pair is stored: `accepted`; - the same pair with a **newer** `updatedAt` updates it: `accepted`; - the same pair with the same or an older `updatedAt` changes nothing: `duplicate`. So you can retry a failed call, or re-send a whole day, without double counting. You don't need an idempotency key. ## Batches and results [#batches-and-results] Send up to 100 redemptions per call. The answer has one result per item, in order: ```json { "results": [ { "index": 0, "result": "accepted" }, { "index": 1, "result": "duplicate" }, { "index": 2, "result": "rejected", "reason": "unknown_code" } ] } ``` A `200` doesn't mean every item was stored: check each result. A rejected item is not stored; fix it and send it again. A `422` means the request itself is malformed and nothing was stored. | `reason` | Meaning | What to do | | --- | --- | --- | | `unknown_code` | The code doesn't belong to any of the brand's Pro Deals. | Check it was a Pro Deal code; skip it if not. | | `code_not_assigned` | The code was never claimed by an associate. | Check the code; it may have been shared outside ENDVR. | | `invalid_amount` | `orderAmount` isn't a positive decimal in the order's currency. | Fix the amount. | ## Check what ENDVR stored [#check-what-endvr-stored] ```bash curl "https://api.endvr.io/v1/redemptions?updatedSince=2026-11-17T00:00:00Z" \ -H "Authorization: Bearer $ENDVR_API_KEY" ``` Filter by `proDealId`, `code` or `orderId` to reconcile one order. # Receive webhooks (/docs/api/guides/webhooks) ENDVR sends events to one HTTPS endpoint of yours. They follow the [Standard Webhooks](https://www.standardwebhooks.com) specification. ## Events [#events] | Event | When | What to do | | --- | --- | --- | | [`code.deactivate`](/docs/api/reference/webhooks/codeDeactivateEvent) | A code must stop working: the brand removed the associate, or the associate left a targeted store. | Disable or delete the code in your store. | | [`pro_deal.ended`](/docs/api/reference/webhooks/proDealEndedEvent) | The Pro Deal ended. | Disable its codes that were not used. | Every event has the same envelope: ```json { "type": "code.deactivate", "timestamp": "2026-11-17T15:20:11Z", "data": { "proDealId": "6730f1c2a9d4e5b6c7d8e9f0", "code": "PRO-7KQ2-XM4D", "reason": "associate_left_store" } } ``` ## Set the endpoint [#set-the-endpoint] ```bash curl -X PUT https://api.endvr.io/v1/webhooks \ -H "Authorization: Bearer $ENDVR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://shop.example.com/endvr/webhooks", "events": ["code.deactivate", "pro_deal.ended"] }' ``` The first answer carries the signing `secret` (`whsec_…`). Store it with your other secrets: it is not shown again. ## Verify every request [#verify-every-request] Each request carries three headers: | Header | Content | | --- | --- | | `webhook-id` | The event id, the same on every retry. | | `webhook-timestamp` | Seconds since the Unix epoch when this attempt was signed. | | `webhook-signature` | One or more `v1,` values, separated by spaces. | The signature is the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with your secret after removing the `whsec_` prefix and base64-decoding the rest. To verify: 1. Reject the request if `webhook-timestamp` is more than 5 minutes from your clock. 2. Compute the signature over the **raw** body, before any JSON parsing. 3. Accept the request if any `v1` value in `webhook-signature` matches, using a constant-time comparison. ```js tab="Node.js" import crypto from "node:crypto"; export function verifyEndvrWebhook(secret, headers, rawBody) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const signatures = headers["webhook-signature"] ?? ""; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) { throw new Error("Webhook timestamp is too old or in the future"); } const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64"); const valid = signatures.split(" ").some((entry) => { const [version, signature] = entry.split(","); return ( version === "v1" && signature?.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) ); }); if (!valid) throw new Error("Invalid webhook signature"); } ``` ```python tab="Python" import base64, hashlib, hmac, time def verify_endvr_webhook(secret: str, headers: dict, raw_body: bytes) -> None: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > 300: raise ValueError("Webhook timestamp is too old or in the future") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for entry in headers.get("webhook-signature", "").split(" "): version, _, signature = entry.partition(",") if version == "v1" and hmac.compare_digest(signature, expected): return raise ValueError("Invalid webhook signature") ``` ```php tab="PHP" 300) { throw new RuntimeException('Webhook timestamp is too old or in the future'); } $key = base64_decode(preg_replace('/^whsec_/', '', $secret)); $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$rawBody}", $key, true)); foreach (explode(' ', $headers['webhook-signature'] ?? '') as $entry) { [$version, $signature] = array_pad(explode(',', $entry, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $signature)) { return; } } throw new RuntimeException('Invalid webhook signature'); } ``` The [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks) do the same in many languages. ## Respond and process [#respond-and-process] - Answer `2xx` as soon as the event is stored, then do the work in the background. - Any other answer, or no answer, is retried with exponential backoff for **24 hours**. - The same event can arrive more than once: use `webhook-id` to skip the ones you already handled. - Events can arrive out of order. Deactivating a code twice must be harmless. ## Test it [#test-it] Send a signed sample of any event to your endpoint: ```bash curl -X POST https://api.endvr.io/v1/webhooks/test \ -H "Authorization: Bearer $ENDVR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "code.deactivate" }' ``` The answer says whether your endpoint answered `2xx`. ## Rotate the secret [#rotate-the-secret] `PUT /webhooks` with `"rotateSecret": true` returns a new secret. For 24 hours, events carry signatures from both the old and the new secret, so you can deploy the new one without missing events. ## When deliveries keep failing [#when-deliveries-keep-failing] `GET /webhooks` shows `failingSince`, and the brand sees the failures in the Brand Portal. Fix the endpoint; events still within their 24 hours of retries are delivered. # Overview (/docs/api) The Client API is published for review and is not built yet: `api.endvr.io` doesn't answer, and the key screen in the Brand Portal doesn't exist. The guides and the reference show the planned `/v1` contract. **Pro Deals** give the retail associates who sell your products personal, single-use discount codes for your online store. On Shopify, ENDVR runs the whole flow for you. The Client API lets you run the same Pro Deals on any other platform (WooCommerce, BigCommerce, Magento, a custom store) by connecting your store to ENDVR from your own servers. ## How it works [#how-it-works] **You create a Pro Deal** in the Brand Portal: the stores it targets, the discount, how many codes each associate gets and the dates. **Your server loads the codes into your store.** Either ENDVR generates them and you create them as single-use discount codes, or you create your own and upload them. **You confirm the codes are live.** ENDVR releases the Pro Deal to associates, who claim their codes in the ENDVR app. **Associates shop on your store** with their code. Your server reports each order that used one. **ENDVR tells you when a code must stop working**, for example when an associate leaves a store, through a webhook. ## Base URL [#base-url] ```txt https://api.endvr.io/v1 ``` JSON in and out, dates in ISO 8601 UTC, money as decimal strings. Every call is authenticated with a brand integration key. Your first calls with a test key. Create, use and rotate keys. The end-to-end guide. Receive and verify events. # Pagination (/docs/api/pagination) Lists return a page of results and a cursor: ```json { "data": [ ... ], "nextCursor": "eyJwIjoyfQ" } ``` Pass `nextCursor` as `cursor` to get the next page. On the last page, `nextCursor` is `null`. | Parameter | Default | Range | | --- | --- | --- | | `limit` | 50 | 1 to 100 | | `cursor` | none (first page) | The `nextCursor` of the previous page | Cursors are opaque: don't build or change them. Keep the other query parameters the same while you page. ```python import os, requests def all_codes(pro_deal_id: str): url = f"https://api.endvr.io/v1/pro-deals/{pro_deal_id}/codes" headers = {"Authorization": f"Bearer {os.environ['ENDVR_API_KEY']}"} cursor = None while True: params = {"limit": 100, **({"cursor": cursor} if cursor else {})} page = requests.get(url, headers=headers, params=params).json() yield from page["data"] cursor = page["nextCursor"] if cursor is None: break ``` # Quickstart (/docs/api/quickstart) You need a **test key** (`endvr_ik_test_…`), created by an Owner or Admin in the Brand Portal under **Brand Settings › Integrations**. Test keys write test data that is never billed, so you can try everything safely. ```bash export ENDVR_API_KEY="endvr_ik_test_..." ``` ### Check the key [#check-the-key] ```bash tab="cURL" curl https://api.endvr.io/v1/connection \ -H "Authorization: Bearer $ENDVR_API_KEY" ``` ```js tab="Node.js" const res = await fetch("https://api.endvr.io/v1/connection", { headers: { Authorization: `Bearer ${process.env.ENDVR_API_KEY}` }, }); console.log(await res.json()); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.endvr.io/v1/connection", headers={"Authorization": f"Bearer {os.environ['ENDVR_API_KEY']}"}, ) print(res.json()) ``` ```json title="Response" { "brandId": "64b7f0c2a1d2e3f4a5b6c7d8", "brandName": "Acme Outdoor", "platform": "woocommerce", "mode": "test", "status": "waiting_first_event", "lastEventAt": null } ``` ### Find a Pro Deal and its codes [#find-a-pro-deal-and-its-codes] ```bash curl "https://api.endvr.io/v1/pro-deals?status=scheduled" \ -H "Authorization: Bearer $ENDVR_API_KEY" curl "https://api.endvr.io/v1/pro-deals/6730f1c2a9d4e5b6c7d8e9f0/codes?limit=100" \ -H "Authorization: Bearer $ENDVR_API_KEY" ``` Create each code in your store as a **single-use** discount code with the Pro Deal's discount. ### Confirm the codes are live [#confirm-the-codes-are-live] ```bash curl -X POST https://api.endvr.io/v1/pro-deals/6730f1c2a9d4e5b6c7d8e9f0/codes/confirm \ -H "Authorization: Bearer $ENDVR_API_KEY" ``` ENDVR releases the Pro Deal to associates; the answer is the Pro Deal with `codesReady: true`. ### Report a redemption [#report-a-redemption] ```bash tab="cURL" curl -X POST https://api.endvr.io/v1/redemptions \ -H "Authorization: Bearer $ENDVR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "redemptions": [{ "code": "PRO-7KQ2-XM4D", "orderId": "10042", "orderAmount": "129.90", "currency": "USD", "processedAt": "2026-11-17T14:03:00Z", "status": "paid", "updatedAt": "2026-11-17T14:03:00Z" }] }' ``` ```js tab="Node.js" const res = await fetch("https://api.endvr.io/v1/redemptions", { method: "POST", headers: { Authorization: `Bearer ${process.env.ENDVR_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ redemptions: [ { code: "PRO-7KQ2-XM4D", orderId: "10042", orderAmount: "129.90", currency: "USD", processedAt: "2026-11-17T14:03:00Z", status: "paid", updatedAt: "2026-11-17T14:03:00Z", }, ], }), }); console.log(await res.json()); ``` ```python tab="Python" res = requests.post( "https://api.endvr.io/v1/redemptions", headers={"Authorization": f"Bearer {os.environ['ENDVR_API_KEY']}"}, json={ "redemptions": [{ "code": "PRO-7KQ2-XM4D", "orderId": "10042", "orderAmount": "129.90", "currency": "USD", "processedAt": "2026-11-17T14:03:00Z", "status": "paid", "updatedAt": "2026-11-17T14:03:00Z", }] }, ) print(res.json()) ``` ```json title="Response" { "results": [{ "index": 0, "result": "accepted" }] } ``` ## Next steps [#next-steps] - Follow [Integrate Pro Deals](/docs/api/guides/pro-deals) for the complete flow and the jobs to run. - Set up [webhooks](/docs/api/guides/webhooks) so codes stop working when they must. # Rate limits (/docs/api/rate-limits) Every key has a request quota. Responses report where you stand with the `RateLimit` header (the values below are an example): ```http RateLimit: limit=600, remaining=598, reset=42 ``` Over the quota, the API answers `429` with a `Retry-After` header in seconds. Wait that long, then retry. ## Stay within the limits [#stay-within-the-limits] - **Batch writes:** send up to 100 redemptions or products per call instead of one per call. - **Page with `limit=100`** when you read whole lists. - **Use `updatedSince`** to read only what changed. - **Spread scheduled jobs** instead of running them all on the hour. - **Back off** on `429` and on `5xx`, with jitter. # Test mode (/docs/api/testing) Use a **test key** (`endvr_ik_test_…`) while you build. Every call works the same as with a live key, with these differences: | | Test key | Live key | | --- | --- | --- | | Redemptions are stored | Yes, as `mode: test` | Yes, as `mode: live` | | Redemptions are billed | Never | According to your plan | | A redemption opens the associate's next code | No | Yes | Data written with one mode is only visible with a key of the same mode: `GET /redemptions` with a test key lists test redemptions only. ## A safe test run [#a-safe-test-run] 1. Create a Pro Deal in the Brand Portal for one store you control, with a small number of codes. 2. With the test key, read its codes and create them in a staging copy of your store. 3. Confirm, place an order with a code, and report it. 4. Check the result per item, then `GET /redemptions?code=…` to see what ENDVR stored. 5. Set your webhook URL and call `POST /webhooks/test` for each event type. When everything passes, follow the [go-live checklist](/docs/api/guides/go-live). # Versioning and changelog (/docs/api/versioning) The version is in the path: `https://api.endvr.io/v1`. ## What can change in v1 [#what-can-change-in-v1] Once `/v1` is released, it only changes by adding things: - new endpoints, new optional parameters, new fields in responses; - new values in enums such as event types, statuses and rejection reasons; - new event types you can subscribe to. Build your integration to ignore fields it doesn't know and to handle unknown enum values. Anything removed or changed in a breaking way is announced at least **6 months** ahead, with `Deprecation` and `Sunset` headers on the affected calls. ## Changelog [#changelog] ### 2026-11-17 — Draft 0.2 [#2026-11-17--draft-02] - Read endpoints for the catalog (`GET /catalog/products`, `GET /catalog/products/{id}`) and redemptions (`GET /redemptions`). - Webhook events documented with their payloads; `POST /webhooks/test`. - Error types and rejection reasons documented. ### 2026-11-17 — Draft 0.1 [#2026-11-17--draft-01] - First draft of the Pro Deal, redemption, catalog and webhook endpoints. # ENDVR for developers (/docs) ENDVR connects brands with the retail store associates who sell their products. Brands run campaigns (sales incentives, digital education, retail tasks and Pro Deals) and reward associates for what they do. There are two ways to work with that data from outside the Brand Portal: Ask Claude about your campaigns, stores, associates and wallet in plain words. No code needed. A REST API for your servers: run Pro Deals on any e-commerce platform and keep your catalog in sync. ## Which one do I need? [#which-one-do-i-need] | You want to | Use | | --- | --- | | Get answers about your brand's performance without opening the portal | [AI assistant](/docs/mcp) | | Prepare a weekly review, a campaign wrap-up or a store check-in with Claude | [Use cases](/docs/mcp/use-cases) | | Connect a store that is not on Shopify to Pro Deals | [Client API](/docs/api) | | Build an AI client or agent that talks to ENDVR | [MCP for developers](/docs/mcp/developers) | ## Built for AI agents too [#built-for-ai-agents-too] Every page is also available as Markdown, and the whole site as [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt). The Client API contract is at [`/openapi.yaml`](/openapi.yaml). See [Use these docs with AI](/docs/api/ai). # Campaigns (/docs/mcp/campaigns) Claude can list your campaigns by status and type, and read any campaign in detail. ## Ask things like [#ask-things-like] - Which campaigns are live right now? - What's waiting in draft, and what's scheduled? - Which Pro Deals have we run? - How many associates took part in the Holiday Sales contest, and how much did we pay in rewards? - What are the missions of the Spring Training module, and how many completions does each one have? - How much budget is left on the Holiday Sales contest? - How many prize units are still available in our summer contest? - Show me the leaderboard of the Q4 sales contest. - When does the Back to School campaign end, and which stores does it target? ## What you get [#what-you-get] **The campaign list**, by portal tab: live (the default), scheduled, draft, under review, paused, finished, rejected and on hold, with the number of campaigns in every tab. You can filter by type and search by campaign or mission name. Short lists (11 campaigns or fewer) also include each campaign's completions, participating associates and rewards paid. **One campaign in detail:** its status and dates, the stores it targets, its missions (with completions for Digital Education), and its rewards. Claude can add up to three extra sections: | Section | What it adds | | --- | --- | | Settings | Description, language, time zone, start and end dates. | | Budget | Per reward: the money and codes earned so far and what is left. | | Prizes | Prize units assigned and left. | | Leaderboard | For contests: the top 10 associates by submissions, with their store, sales and prizes. | ## Campaign types [#campaign-types] | Type | In the portal | | --- | --- | | Contest | Sales Incentives: associates submit sales; rewards and prizes go to the best or to every qualifying sale. | | Learning | Digital Education: modules and quizzes about your products; a passing grade unlocks rewards. | | General | Retail OPS: in-store tasks such as displays, photos or surveys, reviewed by the brand. | | Consumer | Campaigns for shoppers. | | Pro Deal | Associate-only discount codes on your e-commerce store. | ## Good to know [#good-to-know] - The list and the details are live. Completions, associates and rewards paid on the list come from the reporting data and say when they were last updated. - To launch, pause, end or edit a campaign, use the link in the answer to open it in the Brand Portal. # ChatGPT (/docs/mcp/clients/chatgpt) ChatGPT adds remote MCP servers in **developer mode**. On Business, Enterprise and Edu workspaces, an admin turns developer mode on for the workspace first. Availability on personal plans depends on OpenAI. ## Add ENDVR [#add-endvr] With developer mode on, open ChatGPT's apps settings and select **+** › **Add custom MCP server**. The exact menu names change from time to time. Name it **ENDVR** and enter the server URL: ```txt https://mcp.endvr.io ``` For authentication, choose **OAuth**. Confirm ChatGPT's warning about custom servers and create the app. ChatGPT sends you to the ENDVR sign-in page. Sign in with your ENDVR account, choose your brand and select **Allow access**. ## Use it [#use-it] In a chat, add the ENDVR app from the tools menu and ask, for example, "Using ENDVR, which campaigns are live right now?". ## Good to know [#good-to-know] - ChatGPT returns the sign-in to `chatgpt.com`, which the ENDVR sign-in page shows as **You will be sent back to**. - Revoke it under **Connect to AI** in the Brand Portal. # Claude Code (/docs/mcp/clients/claude-code) ## Add ENDVR [#add-endvr] ```bash claude mcp add --transport http endvr https://mcp.endvr.io ``` Add `--scope user` to use it in every project, or `--scope project` to share it with your team through the project's `.mcp.json`. ## Sign in [#sign-in] Run `/mcp` inside Claude Code, choose **endvr** and select **Authenticate**. A browser page opens: sign in with your ENDVR account, choose your brand and select **Allow access**. You can also run: ```bash claude mcp login endvr ``` ## Check it [#check-it] ```bash claude mcp list ``` **endvr** should show as connected. Then ask, for example, "Using ENDVR, list our live campaigns as a Markdown table." ## Good to know [#good-to-know] - The sign-in page opens on your computer and comes back to Claude Code on a local address, so it works behind most firewalls. - To use a second brand, add the server again under another name (`endvr-brand-b`) and pick that brand when you sign in. - Remove it with `claude mcp remove endvr`, and revoke it under **Connect to AI** in the Brand Portal. # Claude (/docs/mcp/clients/claude) Claude is the recommended way to use the ENDVR assistant. You add ENDVR once, and it works on claude.ai, Claude Desktop and the Claude mobile apps with the same account. ## Which plans [#which-plans] Every Claude plan can add ENDVR as a custom connector. On the Free plan you can add one custom connector. On Team and Enterprise plans, an Owner adds it for the organization first. ## Add ENDVR [#add-endvr] In claude.ai or Claude Desktop, open **Customize › Connectors**. Select **+ Add**, then **Add custom connector**. Name it **ENDVR** and paste the server URL: ```txt https://mcp.endvr.io ``` Select **Add**. Select **Connect** on the ENDVR connector. Sign in with your ENDVR account, choose your brand and select **Allow access**. **An Owner, once for the organization:** Open **Organization settings › Connectors**. Add a custom connector named **ENDVR** with the server URL `https://mcp.endvr.io`. **Each member:** Open **Customize › Connectors**, find **ENDVR** and select **Connect**. Sign in with your own ENDVR account, choose your brand and select **Allow access**. Each member signs in with their own account, so everyone sees only what their ENDVR role allows. ## Use it [#use-it] Start a new chat and ask a question, for example: - What is my wallet balance? - Which campaigns are live right now? - Give me a performance review of last month. Claude shows when it looks something up in ENDVR. See [Use cases](/docs/mcp/use-cases) for more. On mobile, there's nothing to set up: the connector you added on the web or desktop is already there. ## Turn it off for a chat [#turn-it-off-for-a-chat] In a chat, open the tools menu and switch **ENDVR** off. To remove it for good, remove the connector in **Customize › Connectors**, and revoke it under **Connect to AI** in the Brand Portal. ## A second brand [#a-second-brand] Each connector reads one brand. To use another brand, add a second custom connector (for example **ENDVR – Brand B**) with the same URL and choose the other brand when you sign in. # OpenAI Codex CLI (/docs/mcp/clients/codex) ## Add ENDVR [#add-endvr] Add the server to `~/.codex/config.toml`: ```toml title="~/.codex/config.toml" [mcp_servers.endvr] url = "https://mcp.endvr.io" ``` ## Sign in [#sign-in] ```bash codex mcp login endvr ``` A browser page opens: sign in with your ENDVR account, choose your brand and select **Allow access**. On a machine without a browser, add `--no-browser` and open the printed link yourself. ## Good to know [#good-to-know] - Codex receives the sign-in on a local address (`127.0.0.1`), which ENDVR accepts. - Revoke it under **Connect to AI** in the Brand Portal. # Cursor (/docs/mcp/clients/cursor) ## Add ENDVR [#add-endvr] Add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project): ```json title="mcp.json" { "mcpServers": { "endvr": { "url": "https://mcp.endvr.io" } } } ``` ## Sign in [#sign-in] Open **Cursor Settings › MCP**. **endvr** shows that it needs a login: select it, and a browser page opens. Sign in with your ENDVR account, choose your brand and select **Allow access**. The page returns to Cursor on your computer. ## Use it [#use-it] In the agent chat, ask, for example, "Using ENDVR, show our top 10 stores this quarter." ## Good to know [#good-to-know] - Cursor's cloud and web agents return the sign-in to `cursor.com`; the desktop app returns it to your computer. - Revoke it under **Connect to AI** in the Brand Portal. # Gemini CLI (/docs/mcp/clients/gemini-cli) ## Add ENDVR [#add-endvr] Add the server to your Gemini CLI `settings.json`: ```json title="settings.json" { "mcpServers": { "endvr": { "httpUrl": "https://mcp.endvr.io" } } } ``` ## Sign in [#sign-in] Start Gemini CLI and run `/mcp auth endvr`, or ask something that needs ENDVR. Gemini CLI finds the sign-in on its own and opens a browser page: sign in with your ENDVR account, choose your brand and select **Allow access**. ## Good to know [#good-to-know] - Gemini CLI receives the sign-in on a local address (`localhost`), which ENDVR accepts. - Revoke it under **Connect to AI** in the Brand Portal. # Other clients (/docs/mcp/clients/other-clients) ## Microsoft Copilot Studio [#microsoft-copilot-studio] Status: **not available yet.** Copilot Studio returns the sign-in to a Microsoft address generated for each connector, which ENDVR doesn't accept for now. ## Windsurf [#windsurf] Status: **unknown.** We haven't been able to confirm how Windsurf signs in. Try it with `https://mcp.endvr.io`; if the connection stops before the ENDVR sign-in page, it isn't supported yet. ## Other MCP clients [#other-mcp-clients] Any client that supports remote MCP servers with OAuth and returns the sign-in to your own computer (`localhost`, `127.0.0.1` or `[::1]`) works today. See [Connect an MCP client](/docs/mcp/developers). # VS Code (/docs/mcp/clients/vs-code) You need GitHub Copilot with agent mode. Your organization's Copilot policy may restrict MCP servers. ## Add ENDVR [#add-endvr] Add the server to your `mcp.json` (run **MCP: Open User Configuration** from the Command Palette, or use `.vscode/mcp.json` for one workspace): ```json title="mcp.json" { "servers": { "endvr": { "type": "http", "url": "https://mcp.endvr.io" } } } ``` ## Sign in [#sign-in] Start the server from the code lens above it in `mcp.json`, or from **MCP: List Servers**. VS Code asks to sign in: allow it, and a browser page opens. Sign in with your ENDVR account, choose your brand and select **Allow access**. ## Use it [#use-it] Open Copilot Chat in **Agent** mode and ask, for example, "Using ENDVR, list our campaigns waiting in draft." ## Good to know [#good-to-know] - VS Code returns the sign-in to your computer, or to `vscode.dev` in the browser version. - Revoke it under **Connect to AI** in the Brand Portal. # Choose your AI client (/docs/mcp/connect) ENDVR works with AI apps that support remote MCP servers. You only need the server URL: ```txt title="ENDVR server URL" https://mcp.endvr.io ``` The same URL, with a copy button, is in the Brand Portal under **Connect to AI** in the sidebar. The item shows up once the assistant is turned on for your brand. ## Recommended [#recommended] claude.ai, Claude Desktop and the Claude mobile apps. The easiest way to start, on any Claude plan. For people who work in the terminal or want ENDVR data next to their code. ## All clients [#all-clients] | Client | Status | Guide | | --- | --- | --- | | Claude (web, Desktop, mobile) | Available | [Connect Claude](/docs/mcp/clients/claude) | | Claude Code | Available | [Connect Claude Code](/docs/mcp/clients/claude-code) | | ChatGPT | Available | [Connect ChatGPT](/docs/mcp/clients/chatgpt) | | Cursor | Available | [Connect Cursor](/docs/mcp/clients/cursor) | | VS Code with GitHub Copilot | Available | [Connect VS Code](/docs/mcp/clients/vs-code) | | OpenAI Codex CLI | Available | [Connect Codex](/docs/mcp/clients/codex) | | Gemini CLI | Available | [Connect Gemini CLI](/docs/mcp/clients/gemini-cli) | | Microsoft Copilot Studio | Not available yet | [Other clients](/docs/mcp/clients/other-clients#microsoft-copilot-studio) | | Windsurf | Unknown | [Other clients](/docs/mcp/clients/other-clients#windsurf) | ## Before you start [#before-you-start] - **A brand account.** You sign in with your own ENDVR account. Retailer accounts can't connect. - **One brand per connection.** You choose the brand on the ENDVR sign-in page. To use a second brand, add the connection again and choose that brand. - **Your role applies.** The assistant sees what your role lets you see in the portal, nothing more. ## The ENDVR sign-in page [#the-endvr-sign-in-page] Every client sends you to the same ENDVR page the first time you use it. It shows which app is asking, what it will be able to do, and the brands you can choose from. - **Verified domain** means ENDVR confirmed the app's identity. An **Unverified app** warning means the app's name is self-declared. Claude can show as unverified for now: continue only if you started the connection yourself, and check where **You will be sent back to** points: `claude.ai` or `claude.com` for Claude, `chatgpt.com` for ChatGPT, `cursor.com` or your own computer for Cursor, `vscode.dev` or your own computer for VS Code, and your own computer for the command-line clients. - **It will be able to** lists the access: reading your Brand Portal data for the brand you pick. - After **Allow access**, you go back to your AI app and the connection is ready. ## Manage your connections [#manage-your-connections] In the Brand Portal, select **Connect to AI** in the sidebar: - **Connected apps** lists every app you allowed, with its brand and the date you connected it. **Revoke** stops its access right away; you can connect it again at any time. - **Recent agent activity** shows the last 50 things your connected apps did: which lookup, for which brand, and whether it worked. ENDVR doesn't keep what was asked or answered. # Connect an MCP client (/docs/mcp/developers) The ENDVR MCP server follows the [Model Context Protocol](https://modelcontextprotocol.io) authorization spec: a client only needs the server URL to discover how to sign in. ## Supported clients [#supported-clients] | Client | Supported | | --- | --- | | claude.ai, Claude Desktop and mobile | Yes | | Claude Code, Codex CLI, Gemini CLI, MCP Inspector | Yes (loopback) | | ChatGPT | Yes | | Cursor (desktop, web and cloud agents) | Yes | | VS Code with GitHub Copilot | Yes | | Any client that receives the sign-in on a loopback address (`http://localhost`, `127.0.0.1`, `[::1]`, any port) | Yes | | Other hosted clients that redirect to their own web address | Not yet | ENDVR accepts the callbacks of the clients above and loopback addresses. A registration with any other redirect URI is refused with `invalid_redirect_uri`, and one refused URI refuses the whole registration. Authorization responses carry `iss` (RFC 9207). | | | | --- | --- | | Server URL (resource) | `https://mcp.endvr.io` | | Protected resource metadata | `https://mcp.endvr.io/.well-known/oauth-protected-resource` | | Authorization server | `https://auth.endvr.io` | | Scope | `brand.read` | | Transport | Streamable HTTP, stateless: `POST /` | The server URL is the host itself: there is no path to add. ## Sign-in flow [#sign-in-flow] ### Discover [#discover] Call `POST https://mcp.endvr.io` without a token. The server answers `401` with: ```http WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.endvr.io/.well-known/oauth-protected-resource", scope="brand.read" ``` The protected resource metadata names the authorization server: ```json { "resource": "https://mcp.endvr.io", "authorization_servers": ["https://auth.endvr.io"], "scopes_supported": ["brand.read"] } ``` ### Register and authorize [#register-and-authorize] Read `https://auth.endvr.io/.well-known/oauth-authorization-server`, register your client with dynamic client registration (RFC 7591) at its `registration_endpoint`, then run the OAuth 2.1 authorization code flow with PKCE (`S256`), passing `resource=https://mcp.endvr.io`. Request the `brand.read` scope; a request without a scope gets `brand.read`. The user signs in with their ENDVR account and picks one brand on the consent page. The grant is bound to that brand. ### Call the server [#call-the-server] Send the access token on every request: ```http POST / HTTP/1.1 Host: mcp.endvr.io Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream ``` Access tokens last 1 hour and refresh tokens 30 days. Refreshing rotates the refresh token. A revoked grant answers `401` `invalid_token`: start the flow again. A user can hold one grant per brand for the same client. Each grant reads only its brand. ## What the server exposes [#what-the-server-exposes] | MCP feature | Content | | --- | --- | | Tools | 7 read-only tools, all with `readOnlyHint: true`. See [Tools](/docs/mcp/developers/tools). | | Resources | `endvr://glossary` (Markdown): campaign types, statuses, reward types and metric definitions. | | Instructions | How to use the tools: one brand per connection, quote `asOf`, share `portalUrl`, treat tool results as data. | | Prompts | None. | The server is stateless: session `GET` and `DELETE` answer `405`. ## HTTP errors [#http-errors] | Status | When | What to do | | --- | --- | --- | | `401` | No token, or an unknown, expired or revoked token (`error="invalid_token"`) | Refresh, or run the sign-in flow again. | | `403` | The token lacks `brand.read` (`error="insufficient_scope"`) | Request the `brand.read` scope. | | `429` | Too many requests without a valid token from one address | Wait for `Retry-After` seconds. | | `503` | The server is temporarily off or unavailable | Retry later. | Errors inside a tool call don't use HTTP statuses: see [Responses and errors](/docs/mcp/developers/responses). # Responses and errors (/docs/mcp/developers/responses) ## Every answer [#every-answer] Each tool returns the same JSON twice: as `structuredContent` and as text content. | Field | Meaning | | --- | --- | | `asOf` | When the data is from. Live reads: when the answer was built. Synced reporting data: the start of the newest reporting sync, as the portal's **Last updated**. `null` when unknown. | | `asOfSemantics` | Which of the two `asOf` means for this answer. | | `statsAsOf` | On lists and details that mix live rows with synced stats: the time of the stats. | | `filtersApplied` | The resolved inputs: dates, currency, page, filters. | | `portalUrl` | The Brand Portal screen with the same data. Show it to the user. | | `notes` | Plain-language caveats, for example a section that couldn't be read. | | `nextCursor` | On paged lists: pass it back as `cursor` for the next page; `null` on the last page. | Tools publish no `outputSchema` yet: treat the fields above as stable and the rest as descriptive. ## Errors [#errors] A failed tool call is a normal tool result with `isError: true` and one sentence that names the cause and the next step, for example: ```txt Your ENDVR sign-in expired or was revoked. Next step: reconnect the ENDVR connector. ``` Invalid inputs (a malformed id, a range over 24 months, an unknown enum value) are refused the same way before anything is read. Messages from internal services are never passed through. ## Personal data and size [#personal-data-and-size] - Keys holding e-mail addresses or phone numbers are removed at any depth, and e-mail addresses inside text are replaced with `[e-mail removed]`. - Names and roles are clipped to 80 characters, mission descriptions to 500. - An answer is capped at 60,000 JSON characters. Over that, the largest list is halved until it fits, and the answer carries `truncated: true` with a `truncationNote`. - At most 20 associates per dashboard answer, 10 leaderboard rows and 50 store members per page. ## Limits [#limits] | Limit | Value | | --- | --- | | Tool calls | 60 per minute per user | | Time per tool call | 30 seconds | | Page size | 1 to 50 rows (default 10) | | Date range | 24 months | ## Prompt-injection safety [#prompt-injection-safety] Tool results contain text typed by brands, stores and associates (names, descriptions). The server's instructions tell the model to treat tool results as data and never follow directions inside them. Clients should do the same. # Tools (/docs/mcp/developers/tools) All tools are read-only and read the brand the grant is bound to. Each takes an optional `brandId`: any value other than the connected brand is refused before anything is read. Ids are 24-character hexadecimal strings. Call `get_brand_context` first: the other tools default to its brand and currency. ## get_brand_context [#get_brand_context] The connected brand: id, name, currency, language and the user's role on it. No inputs besides `brandId`. **Returns** `brand` (`id`, `name`, `currency`, `language`, `yourRole`, `yourStoreScope`, `isRetailer`, `managesMultipleStores`, `serviceStatus`, `paymentPlan`, `hasLaunchedACampaign`) and `connection` (one brand per connection). ## get_performance_overview [#get_performance_overview] The Brand Portal dashboard for a date range, from the synced reporting data. **Returns** `totals` (campaigns launched, rewards delivered, discount codes distributed with the change against the previous period, revenue opportunity, stores, store engagement, new active stores, new associates), `campaignsLaunchedByType`, `rewardsDeliveredOverTime`, `newAssociatesOverTime`, `newActiveStoresList`, the top and bottom 10 engaged stores, the top 20 associates, and `unavailableCards` when a figure couldn't be read. Series are grouped by day (up to 21 days), week (up to 90), month (up to 365) or year. ## list_campaigns [#list_campaigns] Campaigns by portal tab, with the count of every tab. **Returns** `countsByTab`, `totalCount`, `campaigns` (`id`, `name`, `type`, `status`, `isPaused`, `pauseReason`, `launchedAt`, `scheduledAt`, `endDate`, `finishedAt`, `stats`, `portalUrl`) and `nextCursor`. `stats` (completions, participating associates, rewards paid) is filled for pages of 11 rows or fewer and never for drafts; its time is `statsAsOf`. ## get_campaign [#get_campaign] One campaign: status, dates, store scope, missions and rewards. **Returns** `campaign` with its missions (with completions for learning campaigns) and rewards (type, title, amount), plus the sections asked in `include`. Mission descriptions are clipped to 500 characters. ## list_stores [#list_stores] Stores connected to the brand, pending or blocked, with the count per status. **Returns** `countsByStatus`, `totalCount`, `stores` (`id`, `name`, `location`, `status`, `isActive`, `currency`, `connectedAt`, `associates`, `pendingAssociates`, `stats`, `portalUrl`) and `nextCursor`. `stats` (associates, missions completed, sales, rewards paid) is filled for approved pages of 11 rows or fewer. ## get_store [#get_store] One store: status, address, associates with their results, totals and campaigns. **Returns** `store` (`id`, `name`, `address`, `currency`, `status`, `associates`, `groups`, `stats`), `associates` (names and roles, never contact details, with their missions, sales and rewards) and the store's campaigns (first page). A store that isn't connected to the brand returns an error asking to approve it. ## get_wallet [#get_wallet] The brand wallet and its latest transactions. **Returns** `wallet` (`balance`, `pendingBalance`, `campaigns`: deposited, earned and left) and `transactions` (`id`, `type`, `amount`, `status`, `paymentMethod`, `createdAt`, newest first) with `nextCursor`. Roles that can't see the wallet in the portal get an error. # Glossary (/docs/mcp/glossary) The assistant gives Claude these definitions, so you and Claude use the words the same way. ## Campaign types [#campaign-types] | Type | Name in the portal | What it is | | --- | --- | --- | | `contest` | Sales Incentives | Associates submit sales; rewards and prizes go to the best or to every qualifying sale. | | `learning` | Digital Education | Modules and quizzes about your products; a passing grade unlocks rewards. | | `general` | Retail OPS | In-store tasks such as displays, photos or surveys, reviewed by the brand. | | `consumer` | Consumer | Campaigns for shoppers: sign-ups and purchases with cashback. | | `pro_deal` | Pro Deal | Associate-only discount codes on your e-commerce store. | ## Campaign statuses [#campaign-statuses] `draft`, `scheduled`, `under_review` (sent to ENDVR's review), `live`, `paused`, `finished`, `rejected`, `on_hold`. ## Reward types [#reward-types] | Type | What it is | | --- | --- | | `money` | Cash paid into the associate's ENDVR wallet, from the campaign budget funded by your brand wallet. | | `discount`, `gift_card`, `free_product` | Codes unlocked by completions, counted one by one. | | `prize` | Physical prize units assigned to winners. | ## People and places [#people-and-places] - **Associate:** a retail store employee who uses the ENDVR app. - **Store:** a retail location connected to your brand. Stores are approved, pending (waiting for your review) or blocked. - **Active associate:** an associate who used ENDVR in the past year. ## Freshness [#freshness] - **Live data** (lists, details, wallet) is read when Claude asks. - **Reporting data** (dashboard figures, per-row results) is refreshed regularly. Its time is the portal's **Last updated**. # Overview (/docs/mcp) The ENDVR AI assistant connects Claude to your Brand Portal. Once it is connected, you can ask about your campaigns, stores, associates and wallet the way you would ask a colleague, and Claude looks up the answer in ENDVR for you. Claude only reads what you can already see in ENDVR, for the one brand you choose when you connect. It can't change anything. The assistant is being turned on brand by brand. If it isn't on for your brand yet, Claude tells you so the first time you ask a question; your ENDVR contact can turn it on. ## What you can ask [#what-you-can-ask] The dashboard for any period: campaigns launched, rewards and discount codes distributed, engaged stores, new and top associates. What is live, scheduled or in draft, how each campaign is doing, the budget left and the contest leaderboard. Connected and pending stores, each store's team, their results and the campaigns they are in. Your balance, the money committed to campaigns and the latest transactions. ## How it works [#how-it-works] **You ask** in Claude: "How did our spring training go?" **Claude picks what to look up** in ENDVR, for example the campaign list and that campaign's details. **ENDVR answers with your data**, the same numbers as the Brand Portal screens, with the time they were read and a link to the screen. **Claude explains it**, and can turn it into a summary, a table or the next question. ## What it can't do [#what-it-cant-do] Claude can't launch, pause or end campaigns, make payments or top up your wallet, manage your team, or delete anything. Those always happen in the Brand Portal, where you and your team stay in control. Drafting campaigns, missions and rewards for you to review and launch from the Brand Portal. ## Next steps [#next-steps] Claude, ChatGPT, Cursor, VS Code and more. Ready-made questions for weekly reviews and wrap-ups. # Performance (/docs/mcp/performance) Ask about results over a period, and Claude reads the same numbers as the Brand Portal dashboard. ## Ask things like [#ask-things-like] - How many discount codes did we distribute in December? - How many campaigns did we launch this year, by type? - Which 10 stores were the most engaged last quarter? - Of the stores that took part, which ones had the fewest submissions in October? - How many new associates joined between July and September? - Who were our top associates this year, and how much did they sell? - What's our potential Pro code revenue if an associate spends $150 on average? - Show me the performance of the Spring Training campaign at our Toronto stores. ## What you get [#what-you-get] | Figure | What it means | | --- | --- | | Campaigns launched | Live and finished campaigns, by type. | | Rewards distributed | Rewards given to associates: cash totalled in your currency, codes counted one by one, over time. | | Discount codes distributed | Discount codes unlocked by associates, with the change against the previous period. | | Potential Pro code revenue | Codes distributed × average discount × the average spend you give. Only when you give an average spend. | | Active stores | Stores with an associate active on ENDVR in the past year. Not affected by the period. | | New active stores | Stores that connected and had their first associate activate in the period, with their names. | | Campaign engagement | Targeted stores, and how many made at least one submission. | | Top and bottom 10 engaged stores | Stores with the most and the fewest submissions. Stores with no submission at all don't appear. | | New associates | Associate accounts created at your connected stores in the period, over time. | | Top performing associates | Up to 20 associates ranked by approved submissions, with reported sales and rewards received. | ## Choosing the period and filters [#choosing-the-period-and-filters] - **Period:** any range up to 24 months. Without one, Claude uses the last 6 months. - **Grouping:** charts are grouped by day, week, month or year depending on the length of the period. - **Campaigns and stores:** narrow the numbers to up to 20 campaigns or 50 stores ("only our Toronto stores"). - **Currency:** amounts are in your brand's currency unless you ask for another one. ## Good to know [#good-to-know] - Dashboard figures come from ENDVR's reporting data, which is refreshed regularly. Every answer says when it was last updated, like the portal's **Last updated**, so you know how fresh the numbers are. - If one figure can't be read, Claude still answers with the others and tells you which one is missing. - Every answer includes a link to the dashboard so you can check it. # Access and privacy (/docs/mcp/privacy) ## Access [#access] - **You sign in with your own ENDVR account** and choose one brand. The connection only ever reads that brand. - **Read-only.** The connection can read Brand Portal data; it can't change anything. - **Your role applies.** What you can't see in the portal, Claude can't read either: for example, the wallet is only available to roles that see it in the portal. - **Instant revoke.** Revoking an app under **Connect to AI** in the Brand Portal stops it right away. Losing access to the brand in ENDVR stops it too. ## Personal data [#personal-data] - E-mail addresses and phone numbers are removed from every answer before it reaches the assistant. - Associates are shown by name, role and store, as in the portal. - Names and text typed by people (associates, stores, campaigns) are shortened and passed to Claude as data. Claude is told never to follow instructions found inside them. - Large answers are capped; long lists are cut and marked as such. ## What ENDVR keeps [#what-endvr-keeps] For every lookup, ENDVR records which one ran, when, for which brand and app, and whether it worked. You see these in **Recent agent activity**. ENDVR doesn't keep your questions or Claude's answers. ## Fair use [#fair-use] - Up to 60 lookups per minute per person. - Each lookup has 30 seconds to answer. These limits are well above what a conversation needs. If you reach them, wait a minute and ask again. # Stores and associates (/docs/mcp/stores) Claude can list the stores connected to your brand and read any store in detail, including its associates. ## Ask things like [#ask-things-like] - How many stores are connected, and how many requests are waiting for review? - Which connected stores have no active associates? - Find our stores in Vancouver. - Who are the top associates at Beach Store? - How many missions has the Beach Store team completed, and how much have they sold? - Which campaigns is Beach Store taking part in? - List the associates at Beach Store and their roles. ## What you get [#what-you-get] **The store list**, by status: approved (connected, the default), pending (requests to review) or blocked, with the number of stores in each status. You can keep only stores with at least one active associate, or only those without, and search by name or address. Short lists (11 stores or fewer) also include each store's associates, missions completed, sales and rewards paid. **One store in detail:** its status, address, number of associates and groups, its totals, its campaigns, and its associates by name and role with their missions, sales and rewards (for pages of 10 associates or fewer). ## Good to know [#good-to-know] - Associates are shown by name and role, as in the portal. E-mail addresses and phone numbers are never included. - To see a store's team, the store must be connected to your brand. For a pending store, Claude tells you to approve it first. - Store and team lists are live; their results come from the reporting data and say when they were last updated. # Troubleshooting (/docs/mcp/troubleshooting) ## Messages in Claude [#messages-in-claude] Your connection was revoked, or your sign-in expired. Reconnect the ENDVR connector in Claude (in Claude, **Customize › Connectors**) and sign in again. The assistant is being turned on brand by brand. Ask your ENDVR contact to turn it on for your brand. Your account isn't a member of this brand, or it is a type of account that can't connect (for example a retailer account). Ask an Owner or Admin of the brand to add you. Your role can't see the wallet in the Brand Portal, so Claude can't read it either. Ask an Owner or Admin. You reached the limit of 60 lookups per minute. Wait a minute and ask again. The store isn't connected to your brand yet. Approve it in the Brand Portal under **Stores**. ## On the ENDVR sign-in page [#on-the-endvr-sign-in-page] Only brand accounts can connect an AI assistant. Sign in with a brand account. Only members of a brand can connect it. Choose another brand, or ask an Owner of this brand to add you. Go back to Claude and start the connection again. ## My AI app can't connect [#my-ai-app-cant-connect] If the connection stops before the ENDVR sign-in page, your app may not be supported yet: see [Choose your AI client](/docs/mcp/connect). Microsoft Copilot Studio can't connect yet. ## The numbers don't match the portal [#the-numbers-dont-match-the-portal] Dashboard figures and per-row results come from ENDVR's reporting data, which is refreshed regularly; lists and details are live. Compare the **Last updated** time in the portal with the time Claude quotes. If they match and the numbers still differ, check that the period, currency and filters are the same: Claude says which ones it used. ## Claude answered about the wrong brand [#claude-answered-about-the-wrong-brand] Each connection reads one brand. Ask Claude which brand it is connected to. To use another brand, add the connector again and pick that brand on the ENDVR sign-in page. # Use cases (/docs/mcp/use-cases) Copy a prompt into Claude and adjust the names and dates. Claude chains the lookups for you and quotes when the data was last updated. ## Monday performance review [#monday-performance-review] ```txt Give me a performance review of last week compared with the week before: campaigns launched, rewards and discount codes distributed, new associates, and the 5 most engaged stores. Finish with three things I should look at this week. ``` ## Campaign wrap-up [#campaign-wrap-up] ```txt Our "Holiday Sales" contest just finished. Summarize it: dates, stores targeted, completions, participating associates, rewards paid, budget left, and the top 10 of the leaderboard. Write it as a short note I can send to my manager. ``` ## Store check-in before a visit [#store-check-in-before-a-visit] ```txt I'm visiting Beach Store tomorrow. Tell me who works there and their roles, how many missions they completed, their sales and rewards, and which of our campaigns they are in. ``` ## Spot stores that need attention [#spot-stores-that-need-attention] ```txt Which connected stores have no active associates? And among the stores that took part in our campaigns in the last 3 months, which 10 had the fewest submissions? ``` ## Budget check before a new campaign [#budget-check-before-a-new-campaign] ```txt What's my wallet balance and pending balance? How much is committed to live campaigns and how much is left? List the last 5 transactions. ``` ## Training progress [#training-progress] ```txt How is our "Spring Training" module going? Show each mission with its completions, and how many associates took part. ``` ## Pro Deal results [#pro-deal-results] ```txt List our Pro Deal campaigns, then tell me how many discount codes they distributed this year and what the revenue opportunity would be at an average spend of $180. ``` ## Tips for better answers [#tips-for-better-answers] - **Name the period.** "Last quarter", "in October" or "since January 1" beats "recently". - **Name the campaign or store.** Claude searches by name, so "the Holiday Sales contest" is enough. - **Ask for a format.** A table, a short note, or bullet points to paste into a deck. - **Check the source.** Every answer carries a link to the Brand Portal screen with the same numbers. # Wallet (/docs/mcp/wallet) Claude can read your brand wallet, so you can check the money before you plan a campaign. ## Ask things like [#ask-things-like] - What is my wallet balance? - How much money is pending? - How much have we put into campaigns, how much have associates earned, and how much is left? - What were my last 10 wallet transactions? - Did our last top-up go through? ## What you get [#what-you-get] - **Balance** and **pending balance**. - **Campaigns:** the money deposited into campaigns, earned by associates, and left. - **Transactions,** newest first: type, amount, status, payment method and date. Amounts are in your brand's currency. ## Good to know [#good-to-know] - Only roles that can see the wallet in the Brand Portal get an answer. For other roles, Claude says the wallet isn't available to you. - Card details and payment data are never read. - Claude can't top up the wallet or move money. Use the link in the answer to open the wallet in the Brand Portal. # Get the connection (/docs/api/reference/connection/getConnection) GET /connection ```json { "tags": [ "Connection" ], "operationId": "getConnection", "summary": "Get the connection", "description": "The brand, platform, mode and status of the connection the key belongs to. Call it first to check a key.\n", "responses": { "200": { "description": "The connection.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # List Pro Deals (/docs/api/reference/pro-deals/listProDeals) GET /pro-deals ```json { "tags": [ "Pro Deals" ], "operationId": "listProDeals", "summary": "List Pro Deals", "description": "The brand's Pro Deals, newest first.", "parameters": [ { "name": "status", "in": "query", "description": "Only Pro Deals in this status.", "schema": { "$ref": "#/components/schemas/ProDealStatus" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of Pro Deals.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProDeal" } }, "nextCursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Get a Pro Deal (/docs/api/reference/pro-deals/getProDeal) GET /pro-deals/{id} ```json { "tags": [ "Pro Deals" ], "operationId": "getProDeal", "summary": "Get a Pro Deal", "parameters": [ { "$ref": "#/components/parameters/ProDealId" } ], "responses": { "200": { "description": "The Pro Deal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProDeal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # List codes (/docs/api/reference/pro-deals/listProDealCodes) GET /pro-deals/{id}/codes ```json { "tags": [ "Pro Deals" ], "operationId": "listProDealCodes", "summary": "List codes", "description": "The Pro Deal's codes and their state. For a Pro Deal with `codeSource: generated`, these are the codes to\ncreate in your store as single-use discount codes. Send `Accept: text/csv` for one code per line.\n", "parameters": [ { "$ref": "#/components/parameters/ProDealId" }, { "name": "status", "in": "query", "description": "Only codes in this state.", "schema": { "$ref": "#/components/schemas/CodeStatus" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of codes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "nextCursor": { "$ref": "#/components/schemas/NextCursor" } } } }, "text/csv": { "schema": { "type": "string" }, "example": "code\nPRO-7KQ2-XM4D\nPRO-9TRB-2HNC\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Upload your own codes (/docs/api/reference/pro-deals/uploadProDealCodes) POST /pro-deals/{id}/codes ```json { "tags": [ "Pro Deals" ], "operationId": "uploadProDealCodes", "summary": "Upload your own codes", "description": "For a Pro Deal with `codeSource: uploaded`: add codes you created in your store. Up to 100 codes per call;\na code already on the Pro Deal comes back as `duplicate`.\n", "parameters": [ { "$ref": "#/components/parameters/ProDealId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codes" ], "properties": { "codes": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 3, "maxLength": 64 } } } }, "example": { "codes": [ "ACME-PRO-0001", "ACME-PRO-0002" ] } } } }, "responses": { "200": { "$ref": "#/components/responses/BatchResult" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Confirm the codes are live (/docs/api/reference/pro-deals/confirmProDealCodes) POST /pro-deals/{id}/codes/confirm ```json { "tags": [ "Pro Deals" ], "operationId": "confirmProDealCodes", "summary": "Confirm the codes are live", "description": "Tells ENDVR the codes work in your store. ENDVR then releases the Pro Deal to associates, who can claim\ntheir codes in the ENDVR app. Safe to repeat; confirm again after adding codes.\n", "parameters": [ { "$ref": "#/components/parameters/ProDealId" } ], "responses": { "200": { "description": "The Pro Deal after the confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProDeal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # List redemptions (/docs/api/reference/redemptions/listRedemptions) GET /redemptions ```json { "tags": [ "Redemptions" ], "operationId": "listRedemptions", "summary": "List redemptions", "description": "Redemptions reported with this key's mode, most recently updated first.", "parameters": [ { "name": "proDealId", "in": "query", "schema": { "type": "string" } }, { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "orderId", "in": "query", "schema": { "type": "string" } }, { "name": "updatedSince", "in": "query", "description": "Only redemptions updated at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of redemptions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RedemptionRecord" } }, "nextCursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Report redemptions (/docs/api/reference/redemptions/reportRedemptions) POST /redemptions ```json { "tags": [ "Redemptions" ], "operationId": "reportRedemptions", "summary": "Report redemptions", "description": "Up to 100 orders that used a Pro Deal code. A redemption is unique on `(code, orderId)`: sending it again\nwith a newer `updatedAt` updates it, and an equal or older one comes back as `duplicate`, so retries are\nsafe. An associate's next code opens once their current code is reported.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "redemptions" ], "properties": { "redemptions": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Redemption" } } } }, "example": { "redemptions": [ { "code": "PRO-7KQ2-XM4D", "orderId": "10042", "orderAmount": "129.90", "currency": "USD", "processedAt": "2026-11-17T14:03:00Z", "status": "paid", "updatedAt": "2026-11-17T14:03:00Z" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/BatchResult" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # List products (/docs/api/reference/catalog/listProducts) GET /catalog/products ```json { "tags": [ "Catalog" ], "operationId": "listProducts", "summary": "List products", "parameters": [ { "name": "updatedSince", "in": "query", "description": "Only products changed at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "includeArchived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of products.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductRecord" } }, "nextCursor": { "$ref": "#/components/schemas/NextCursor" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Upsert products (/docs/api/reference/catalog/upsertProducts) PUT /catalog/products ```json { "tags": [ "Catalog" ], "operationId": "upsertProducts", "summary": "Upsert products", "description": "Creates or replaces up to 100 products, keyed by your own product ids. A product sent again replaces the\nstored one, variants included; an archived product sent again is restored.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Product" } } } }, "example": { "products": [ { "id": "prod_1001", "title": "Trail Runner 2", "url": "https://shop.example.com/products/trail-runner-2", "imageUrl": "https://shop.example.com/images/trail-runner-2.jpg", "variants": [ { "id": "var_1001_42", "sku": "TR2-BLK-42", "title": "Black / 42", "price": "159.00", "currency": "USD" } ] } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/BatchResult" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Invalid" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Get a product (/docs/api/reference/catalog/getProduct) GET /catalog/products/{id} ```json { "tags": [ "Catalog" ], "operationId": "getProduct", "summary": "Get a product", "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "description": "The product, archived or not.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Archive a product (/docs/api/reference/catalog/archiveProduct) DELETE /catalog/products/{id} ```json { "tags": [ "Catalog" ], "operationId": "archiveProduct", "summary": "Archive a product", "description": "Hides the product from new campaigns. Upsert it again to restore it.", "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "204": { "description": "Archived." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Get the webhook endpoint (/docs/api/reference/webhooks/getWebhook) GET /webhooks ```json { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Get the webhook endpoint", "responses": { "200": { "description": "The webhook configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Set the webhook endpoint (/docs/api/reference/webhooks/putWebhook) PUT /webhooks ```json { "tags": [ "Webhooks" ], "operationId": "putWebhook", "summary": "Set the webhook endpoint", "description": "Sets where ENDVR sends events. The signing secret is returned when the endpoint is first set and when\n`rotateSecret` is true, and never again. After a rotation, events carry signatures from both secrets for\n24 hours.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "An HTTPS URL." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "rotateSecret": { "type": "boolean", "default": false } } }, "example": { "url": "https://shop.example.com/endvr/webhooks", "events": [ "code.deactivate", "pro_deal.ended" ] } } } }, "responses": { "200": { "description": "The webhook configuration, with `secret` when it was just created or rotated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret. Present only right after it was created or rotated.", "examples": [ "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" ] } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Invalid" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # Send a test event (/docs/api/reference/webhooks/sendTestWebhook) POST /webhooks/test ```json { "tags": [ "Webhooks" ], "operationId": "sendTestWebhook", "summary": "Send a test event", "description": "Sends a signed event of the chosen type with sample data to the configured endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookEventType" } } }, "example": { "type": "code.deactivate" } } } }, "responses": { "200": { "description": "The delivery attempt.", "content": { "application/json": { "schema": { "type": "object", "required": [ "delivered", "statusCode" ], "properties": { "delivered": { "type": "boolean", "description": "True when your endpoint answered 2xx." }, "statusCode": { "type": [ "integer", "null" ], "description": "Your endpoint's HTTP status; null when it could not be reached." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # code.deactivate (/docs/api/reference/webhooks/codeDeactivateEvent) Webhook code.deactivate ```json { "tags": [ "Webhooks" ], "operationId": "codeDeactivateEvent", "summary": "code.deactivate", "description": "A code must stop working in your store: disable or delete the discount code. Sent when the brand removes an\nassociate from a Pro Deal or the associate leaves a targeted store. Codes already used are not sent.\n", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "const": "code.deactivate" }, "data": { "type": "object", "required": [ "proDealId", "code", "reason" ], "properties": { "proDealId": { "type": "string" }, "code": { "type": "string" }, "reason": { "type": "string", "enum": [ "associate_removed", "associate_left_store" ] } } } } } ] }, "example": { "type": "code.deactivate", "timestamp": "2026-11-17T15:20:11Z", "data": { "proDealId": "6730f1c2a9d4e5b6c7d8e9f0", "code": "PRO-7KQ2-XM4D", "reason": "associate_left_store" } } } } }, "responses": { "200": { "description": "Answer any 2xx once the event is stored; anything else is retried." } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml. # pro_deal.ended (/docs/api/reference/webhooks/proDealEndedEvent) Webhook pro_deal.ended ```json { "tags": [ "Webhooks" ], "operationId": "proDealEndedEvent", "summary": "pro_deal.ended", "description": "The Pro Deal ended. Disable its codes that were not used. No `code.deactivate` is sent for them.\n", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "const": "pro_deal.ended" }, "data": { "type": "object", "required": [ "proDealId", "endedAt" ], "properties": { "proDealId": { "type": "string" }, "endedAt": { "type": "string", "format": "date-time" } } } } } ] }, "example": { "type": "pro_deal.ended", "timestamp": "2026-12-31T23:59:59Z", "data": { "proDealId": "6730f1c2a9d4e5b6c7d8e9f0", "endedAt": "2026-12-31T23:59:59Z" } } } } }, "responses": { "200": { "description": "Answer any 2xx once the event is stored; anything else is retried." } } } ``` Schemas referenced with $ref are defined in https://docs.endvr.io/openapi.yaml.