Partner API and widget

The key's brand

Auth Secret key: Authorization: Bearer vn_sk_…

curl -X GET "https://vouchernaut.com/api/partner/v1/me" \
  -H "Authorization: Bearer vn_sk_test_…"

This month's verifications and allowance

Auth Secret key: Authorization: Bearer vn_sk_…

The brand's plan and its billable verifications this London calendar month (live mode only: test mode is never billed): one per shopper, audience and month, whether they were verified here or recognised from another brand. left is how many more may verify this month, counting what the overage cap pays for on Growth and Scale; null when there's no limit. Any secret key may read it.

curl -X GET "https://vouchernaut.com/api/partner/v1/usage" \
  -H "Authorization: Bearer vn_sk_test_…"

The brand's campaigns

Auth Secret key: Authorization: Bearer vn_sk_…

Newest first, a page at a time. Pass the response's nextCursor back as cursor for the next page; it is null on the last. Needs the campaigns:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/campaigns" \
  -H "Authorization: Bearer vn_sk_test_…"

One campaign

Auth Secret key: Authorization: Bearer vn_sk_…

Needs the campaigns:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/campaigns/{id}" \
  -H "Authorization: Bearer vn_sk_test_…"

Move a campaign to another code pool

Auth Secret key: Authorization: Bearer vn_sk_…

Live secret keys only. Takes codePoolId and nothing else: another of the brand's code pools for a unique-code campaign (as the Shopify app does with the pool it makes). A live campaign may only move to a pool with codes left (409 pool_empty otherwise); a draft or paused one may take an empty pool. An archived campaign or one whose reward isn't a unique code is refused (400, error.details.reason campaign_archived or not_unique_code). Another brand's campaign or pool is 404. Needs the campaigns:write scope.

curl -X PATCH "https://vouchernaut.com/api/partner/v1/campaigns/{id}" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "codePoolId": "3f0e8c3a-2b1d-4c5e-9a7f-1d2c3b4a5e6f"
}'

A campaign's product list

Auth Secret key: Authorization: Bearer vn_sk_…

The SKUs and collections the campaign is limited to (its product list, uploaded in the console), sorted; both empty when it applies to everything. The Shopify app builds a discount's products from it. Needs the campaigns:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/campaigns/{id}/products" \
  -H "Authorization: Bearer vn_sk_test_…"

Make a code pool

Auth Secret key: Authorization: Bearer vn_sk_…

Live secret keys only. A shopify pool names its discount's DiscountCodeNode gid as externalRef (required for it, refused on a csv pool); asking again for the same discount answers the pool already made (200) rather than a second. lowStockThreshold defaults to 100. Add codes with POST /api/partner/v1/code-pools/{id}/codes. Needs the codes:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/code-pools" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

Add codes to a pool

Auth Secret key: Authorization: Bearer vn_sk_…

Live secret keys only. Adds the file's valid codes that aren't already in the pool (compared case-insensitively). A code has at most 64 characters and no whitespace or control characters; invalid rows are reported, not imported. Nothing is imported when the file is malformed, over 200,000 rows or would take the pool over 1,000,000 codes (400, with error.details.reason). One upload per brand runs at a time: another sent meanwhile gets 429 rate_limited with error.details.reason import_in_progress and Retry-After. Needs the codes:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/code-pools/{id}/codes" \
  -H "Authorization: Bearer vn_sk_test_…"

Captured shoppers

Auth Secret key: Authorization: Bearer vn_sk_…

What verified shoppers shared with the brand after verifying, in the key's mode, with the exact consent wording they agreed to. Oldest first, a page at a time: pass the response's nextCursor back as cursor for the next page; it is null on the last. To pick up later, pass the newest record's createdAt as since and skip ids you already have. sub is the per-brand pseudonymous shopper id (a gated link's sub). email is the address the shopper proved, shared because they ticked the capture consent; null when they proved a phone number. Needs the captures:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/captures" \
  -H "Authorization: Bearer vn_sk_test_…"

Export a shopper's data

Auth Secret key: Authorization: Bearer vn_sk_…

For a shopper's access request: everything the brand holds on the shopper with this email, or this phone number for one who verified by SMS, in the key's mode (a live key, live data; a test key, test data), as JSON. Only the brand's own records: its verifications, the uses of proofs on it, the rewards it issued (without their codes), what the shopper shared with it and the orders it reported for them; a proof the shopper made with another brand is named by the brand's own verification that recognised it. An address the brand holds nothing for answers the same shape, empty. Audited without the address or number. Needs the shoppers:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/shoppers/export" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "sam@leeds.ac.uk",
  "phone": "+447700900123"
}'

Erase a shopper's data

Auth Secret key: Authorization: Bearer vn_sk_…

For a shopper's erasure request (by email, or phone for one who verified by SMS), in the key's mode: deletes what they shared with the brand and the uses of their proofs on it, and unlinks them from the brand's rewards, funnel events and orders (the rows stay, anonymous, for the brand's counts). Their proofs and other brands' records are theirs and untouched; a shopper erases everything at vouchernaut.com/privacy/verification. Answers the same, with zeros, for an address the brand holds nothing for. Audited without the address or number. Needs the shoppers:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/shoppers/erase" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "sam@leeds.ac.uk",
  "phone": "+447700900123"
}'

Report an order

Auth Secret key: Authorization: Bearer vn_sk_…

Creates the order, or updates the one with the same externalId. Amounts are whole minor units (pence, cents). The key decides the mode; test: true on a live key stores the order in test mode (Shopify test orders). An order is matched to the reward that led to it: an issued unique code (code_unique), the campaign's shared code (code_shared), the widget session (sessionId, the vn:sid the widget keeps) or, failing those, the verified shopper's email (email). The email is only ever stored as a keyed hash. A report for an order the pixel sent takes over its totals, codes and items, and keeps its session when none is sent. sourceName: "pos" or channel: "in_store" stores channel: in_store; an in-store order matched to an in-store claim redeems the claim only when the key also has in_store:redeem. A repeat that changes nothing is answered 200 and records nothing. Needs the orders:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/orders" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "string",
  "currency": "string",
  "total": 1000
}'

The brand's orders

Auth Secret key: Authorization: Bearer vn_sk_…

Newest first by when they were placed, in the key's mode, a page at a time: pass the response's nextCursor back as cursor for the next page; it is null on the last. since keeps orders placed at or after it; test=true on a live key lists test orders. Needs the orders:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/orders" \
  -H "Authorization: Bearer vn_sk_test_…"

One order

Auth Secret key: Authorization: Bearer vn_sk_…

The stored order, its match and commission basis. Another brand's order is not_found. A live key also reaches the brand's test orders (sent with test: true) when no live order has the id. Needs the orders:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/orders/{externalId}" \
  -H "Authorization: Bearer vn_sk_test_…"

Set the refunded total, or cancel

Auth Secret key: Authorization: Bearer vn_sk_…

{ refundedTotal } sets the refunded total (minor units, at most the order's total; the difference is recorded as a refund), or { status: "cancelled" } cancels the order. Needs an Idempotency-Key header (400 without one): a repeat with the same key answers the order as it stands and changes nothing. A live key also reaches the brand's test orders (sent with test: true) when no live order has the id. Needs the orders:write scope.

curl -X PATCH "https://vouchernaut.com/api/partner/v1/orders/{externalId}" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "idempotency-key: <idempotency-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "refundedTotal": 1000
}'

Refund part or all of an order

Auth Secret key: Authorization: Bearer vn_sk_…

Adds amount (minor units) to the refunded total; the order becomes partially_refunded, or refunded once the refunds reach its total, and its commission basis shrinks with it. Idempotent by refundId: a repeat answers the order as it stands and changes nothing. A refund that would take the refunded total above the order's total is refused with 422 refund_exceeds_total and changes nothing. A live key also reaches the brand's test orders (sent with test: true) when no live order has the id. Needs the orders:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/orders/{externalId}/refunds" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "refundId": "string",
  "amount": 1
}'

The funnel report

Auth Secret key: Authorization: Bearer vn_sk_…

Placement impressions to redeemed orders for the brand, from daily rollups refreshed every 10 minutes, as the console shows it. Counts of shoppers are distinct per day, so a range adds up shopper-days. Money is per currency. from and to are London days (up to 400, the last 30 by default). A test key reads test mode only; a live key reads live unless mode=test. Needs the reports:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/reports/funnel" \
  -H "Authorization: Bearer vn_sk_test_…"

The brand's webhook endpoints

Auth Secret key: Authorization: Bearer vn_sk_…

Every endpoint in the key's mode, newest first, with the last four characters of its secret, never the secret. Needs the webhooks:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/webhook-endpoints" \
  -H "Authorization: Bearer vn_sk_test_…"

Subscribe a URL to events (REST hook)

Auth Secret key: Authorization: Bearer vn_sk_…

Makes an endpoint in the key's mode that receives the events named (event for one, as Zapier's REST hooks send it, or events). The URL must be https on a public host (no user name or password, up to 2,000 characters); its host is resolved and refused when it points at a private, loopback, link-local or metadata address. Up to 10 endpoints per mode. Answers the endpoint's id and its signing secret, which is never shown again: keep it to check signatures. Deliveries are signed: Vouchernaut-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> under the endpoint's secret. Needs the webhooks:write scope, and captures:read as well to subscribe to capture.submitted.

curl -X POST "https://vouchernaut.com/api/partner/v1/webhook-endpoints" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "string"
}'

Unsubscribe (remove an endpoint)

Auth Secret key: Authorization: Bearer vn_sk_…

Removes the endpoint; nothing more is sent to it. Another brand's or mode's endpoint is not_found. Needs the webhooks:write scope.

curl -X DELETE "https://vouchernaut.com/api/partner/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer vn_sk_test_…"

Rotate an endpoint's secret

Auth Secret key: Authorization: Bearer vn_sk_…

Makes a new signing secret, answered here only. For the next 24 hours deliveries carry a second v1 signature made with the old secret, so the receiver can switch over. Needs the webhooks:write scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/webhook-endpoints/{id}/rotate" \
  -H "Authorization: Bearer vn_sk_test_…"

Recent events (polling trigger)

Auth Secret key: Authorization: Bearer vn_sk_…

The brand's latest events in the key's mode, newest first, each exactly as a webhook delivers it, id first (a polling trigger deduplicates on it). Events are kept for 30 days. Needs the webhooks:read scope; capture.submitted (what shoppers shared) is listed only for a key with captures:read as well.

curl -X GET "https://vouchernaut.com/api/partner/v1/events" \
  -H "Authorization: Bearer vn_sk_test_…"

The brand's shops

Auth Secret key: Authorization: Bearer vn_sk_…

The brand's in-store locations by id, a page at a time (nextCursor). Needs the locations:read scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/locations" \
  -H "Authorization: Bearer vn_sk_test_…"

Look up an in-store claim

Auth Secret key: Authorization: Bearer vn_sk_…

The claim a code names, in the key's mode: the issued, unexpired one if any (a shared code names many), else the newest. storeCode narrows it to one shop. Needs the in_store:redeem scope.

curl -X GET "https://vouchernaut.com/api/partner/v1/in-store/claims/{code}" \
  -H "Authorization: Bearer vn_sk_test_…"

Redeem an in-store claim

Auth Secret key: Authorization: Bearer vn_sk_…

Marks the claim a code names redeemed by the till (redeemedVia: partner_api), recording orderRef. Once only: a claim already redeemed (by staff, the till or a matched order) is 409 claim_redeemed with error.details.redeemedAt and redeemedVia; an expired one 410. Needs the in_store:redeem scope.

curl -X POST "https://vouchernaut.com/api/partner/v1/in-store/claims/{code}/redeem" \
  -H "Authorization: Bearer vn_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "storeCode": "string",
  "orderRef": "string"
}'

PartnerError

Every error from both APIs. requestId matches the response's X-Request-Id.

• errorobjectrequired
  • code"missing_key" | "invalid_key" | "key_revoked" | "key_expired" | "wrong_key_type" | "secret_key_in_browser" | "origin_not_allowed" | "insufficient_scope" | "brand_not_verified" | "terms_required" | "brand_suspended" | "plan_limit" | "plan_required" | "rate_limited" | "invalid_request" | "not_found" | "internal_error" | "market_unavailable" | "audience_not_offered" | "method_unavailable" | "email_not_eligible" | "not_on_staff_list" | "disposable_email" | "wrong_code" | "code_expired" | "too_many_requests" | "locked" | "rejected" | "verification_invalid" | "pool_empty" | "offer_unavailable" | "refund_exceeds_total" | "launch_unavailable" | "scan_expired" | "location_required" | "claim_limit" | "claim_redeemed" | "claim_expired" | "claim_void" | "wrong_pin" | "pin_locked" | "pin_not_set"required
  • messagestringrequired

    1 to any characters

  • detailsany
• requestIdstringrequired

  pattern ^[A-Za-z0-9_-]{8,64}$

Usage

• plan"free" | "growth" | "scale" | "enterprise"required
• monthstringrequired

  YYYY-MM, London time.

• resetsAtstringrequired

  When the next month's count starts, at zero.

• verificationsintegerrequired
• includedinteger | nullrequired
• overageintegerrequired

  Verifications over the allowance this month.

• leftinteger | nullrequired
• overLimitbooleanrequired

  New verifications are refused (plan_limit) until next month.

• overageCapPenceinteger | nullrequired

PartnerCampaign

• idstring (uuid)required
• namestringrequired
• status"draft" | "active" | "paused" | "archived"required

  As stored: what the brand last chose.

• state"draft" | "paused" | "archived" | "scheduled" | "ended" | "out_of_codes" | "live"required

  status, with active resolved against the dates, the total cap and the pool (in the key's mode): scheduled, live, ended or out_of_codes.

• rewardType"shared_code" | "unique_code" | "codeless_link" | "gated_link"required
• valueTextstring | nullrequired
• discountKind"percent" | "fixed" | "free_shipping" | "other"required
• discountValueinteger | nullrequired

  Basis points for percent, minor units for fixed.

• discountCurrencystring | nullrequired
• minSpendMinorinteger | nullrequired
• combinesWithobjectrequired
  • orderbooleanrequired
  • productbooleanrequired
  • shippingbooleanrequired
• affiliateRoutebooleanrequired
• termsstring | nullrequired
• sharedCodestring | nullrequired
• codePoolIdstring (uuid) | nullrequired
• linkUrlstring | nullrequired
• startsAtstring (date-time) | nullrequired
• endsAtstring (date-time) | nullrequired
• marketsstring[]required
• allowedCountriesstring[] | nullrequired
• totalCapinteger | nullrequired
• dailyCapinteger | nullrequired
• perShopperLimitintegerrequired
• perShopperWindowDaysinteger | nullrequired
• ageMininteger | nullrequired
• ageMaxinteger | nullrequired
• audiences"student" | "graduate" | "apprentice" | "teacher" | "youth" | "under_26" | "over_60" | "custom_age" | "nhs" | "healthcare" | "social_worker" | "carer" | "police" | "fire" | "first_responder" | "emergency_services" | "military" | "veteran" | "key_worker" | "delivery_transport" | "supermarket" | "charity_worker" | "government" | "employee" | "disability" | "maternity" | "social_follow" | "strava" | "donor"[]required
• merchantIdinteger | nullrequired
• captureFieldsobject[]required

  What the shopper is asked for after verifying, in order.

  • field"firstName" | "dateOfBirth" | "occupation"required
  • requiredbooleanrequired
• captureConsentTextstring | nullrequired
• marketingConsentTextstring | nullrequired

  Null hides the marketing tick box.

• codelessMode"shopify_discount" | "parameter" | nullrequired
• codelessParamstring | nullrequired

  name=value added to the landing page in parameter mode.

• gatedTtlMinutesintegerrequired

  How long a gated link's token lasts, 5 to 1440 minutes.

• channels"online" | "in_store"[]required

  Where it runs: online (your site and our hosted pages), in_store (the in-store launcher) or both.

• inStoreobjectrequired

  In store: how the phone shows the code (barcode, qr or text), for how many minutes (2 to 30), and whether staff confirm it with the shop's PIN.

  • display"barcode" | "qr" | "text"required
  • ttlMinutesintegerrequired
  • staffConfirmbooleanrequired
• createdAtstring (date-time)required
• updatedAtstring (date-time)required
• issuedTodayintegerrequired

  Rewards issued today (London) in the key's mode.

• issuedTotalintegerrequired

  Rewards issued in the key's mode.

CampaignProducts

• skusstring[]required
• collectionsstring[]required

PartnerCodePool

• idstring (uuid)required
• namestringrequired
• source"csv" | "shopify"required

  csv for imported codes; shopify for codes the Shopify app makes in the discount externalRef names.

• externalRefstring | nullrequired

  The Shopify DiscountCodeNode gid, for a shopify pool.

• lowStockThresholdintegerrequired

  code_pool.low fires when available codes fall below it.

• lowStockAlertedAtstring (date-time) | nullrequired
• availableintegerrequired
• issuedintegerrequired
• voidintegerrequired
• createdAtstring (date-time)required

CodePoolCreateRequest

• namestringrequired

  1 to 80 characters

• source"csv" | "shopify"

  default "csv"

• externalRefstring

  pattern ^gid:\/\/shopify\/DiscountCodeNode\/\d{1,20}$

• lowStockThresholdinteger

  0 to 1000000

CampaignPoolPatch

• codePoolIdstring (uuid)required

CapturesPage

• dataobject[]required
  • idstring (uuid)required
  • campaignIdstring (uuid)required
  • rewardIdstring (uuid) | nullrequired
  • substringrequired

    1 to any characters

  • audience"student" | "graduate" | "apprentice" | "teacher" | "youth" | "under_26" | "over_60" | "custom_age" | "nhs" | "healthcare" | "social_worker" | "carer" | "police" | "fire" | "first_responder" | "emergency_services" | "military" | "veteran" | "key_worker" | "delivery_transport" | "supermarket" | "charity_worker" | "government" | "employee" | "disability" | "maternity" | "social_follow" | "strava" | "donor" | nullrequired
  • verifiedUntilstring (date-time) | nullrequired
  • emailstring (email) | nullrequired
  • fieldsobjectrequired
    • firstNamestring
    • dateOfBirthstring
    • occupationstring
  • consentTextstringrequired
  • consentVersionstringrequired
  • marketingConsentbooleanrequired
  • createdAtstring (date-time)required
• nextCursorstring | nullrequired

ShopperExport

• emailstring

  The address asked about, when it was one.

• phonestring

  The number asked about (E.164), when it was one.

• mode"live" | "test"required
• identitiesobject[]required

  The shopper as the brand knows them.

  • substringrequired

    The per-brand shopper id.

  • emailstring | nullrequired
  • phonestring | nullrequired
• verificationsobject[]required

  Verifications started on the brand.

  • idstringrequired
  • substringrequired

    The per-brand shopper id.

  • audiencestringrequired
  • methodstringrequired
  • statusstringrequired
  • campaignIdstring | nullrequired
  • verifiedAtstring (date-time) | nullrequired
  • expiresAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
• usesobject[]required

  Each time a proof was used on the brand.

  • idstringrequired
  • verificationIdstring | nullrequired

    The brand's own verification it stood on (one of verifications), also when it recognised a proof the shopper made elsewhere; null when the brand has none.

  • campaignIdstring | nullrequired
  • reusedbooleanrequired
  • createdAtstring (date-time)required
• rewardsobject[]required

  Rewards the brand issued them (without codes).

  • idstringrequired
  • substringrequired

    The per-brand shopper id.

  • campaignIdstringrequired
  • verificationIdstring | nullrequired

    The brand's own verification it stood on (one of verifications), also when it recognised a proof the shopper made elsewhere; null when the brand has none.

  • rewardTypestringrequired
  • countrystring | nullrequired
  • surfacestring | nullrequired
  • issuedAtstring (date-time)required
  • expiresAtstring (date-time) | nullrequired
• capturesobject[]required

  What they shared with the brand after verifying.

  • idstringrequired
  • substringrequired

    The per-brand shopper id.

  • campaignIdstringrequired
  • rewardIdstring | nullrequired
  • fieldsobjectrequired
    • firstNamestring
    • dateOfBirthstring
    • occupationstring
  • marketingConsentbooleanrequired
  • consentTextstringrequired
  • marketingConsentTextstring | nullrequired
  • consentVersionstringrequired
  • createdAtstring (date-time)required
• ordersobject[]required

  Orders the brand reported that name the shopper or carry their email's hash.

  • idstringrequired
  • externalIdstringrequired

    The brand's order id.

  • substring | nullrequired

    The per-brand shopper id.

  • matchstringrequired
  • campaignIdstring | nullrequired
  • rewardIdstring | nullrequired
  • statusstringrequired
  • currencystringrequired
  • totalintegerrequired

    Minor units.

  • refundedTotalintegerrequired

    Minor units.

  • placedAtstring (date-time)required

ShopperRequest

The shopper's email, or the phone they proved by SMS (staff lists).

• emailstring

  The address the shopper proved; compared trimmed and lower-cased.

  0 to 254 characters · pattern ^[^\s@]+@[^\s@]+\.[^\s@]+$

• phonestring

  The mobile number the shopper proved by SMS: E.164, or a UK number starting 0.

  0 to 32 characters · pattern ^\+?[\d\s().-]{7,31}$

ShopperErasure

• erasedobjectrequired
  • capturesintegerrequired

    Captures deleted.

  • usesintegerrequired

    Verification uses deleted.

  • rewardsintegerrequired

    Rewards no longer linked to them.

  • eventsintegerrequired

    Funnel events no longer linked to them.

  • ordersintegerrequired

    Orders no longer linked to them (identity and email hash removed).

Order

• idstring (uuid)required
• externalIdstringrequired
• orderNumberstring | nullrequired
• mode"live" | "test"required
• source"pixel" | "api" | "shopify"required
• sourceNamestring | nullrequired
• channel"online" | "in_store"required
• status"placed" | "partially_refunded" | "refunded" | "cancelled"required
• currencystringrequired
• totalintegerrequired
• taxinteger | nullrequired
• discountTotalintegerrequired
• refundedTotalintegerrequired
• codesstring[]required
• lineItemsobject[]required
  • skustring | nullrequired
  • quantityintegerrequired
  • priceintegerrequired
  • productIdstring
  • variantIdstring
  • collectionsstring[]
• sessionIdstring | nullrequired
• newCustomerboolean | nullrequired
• countrystring | nullrequired
• device"mobile" | "tablet" | "desktop" | nullrequired
• matchobjectrequired
  • type"code_unique" | "code_shared" | "session" | "email" | "none"required
  • campaignIdstring (uuid) | nullrequired
  • rewardIdstring (uuid) | nullrequired
  • verificationIdstring (uuid) | nullrequired
  • audience"student" | "graduate" | "apprentice" | "teacher" | "youth" | "under_26" | "over_60" | "custom_age" | "nhs" | "healthcare" | "social_worker" | "carer" | "police" | "fire" | "first_responder" | "emergency_services" | "military" | "veteran" | "key_worker" | "delivery_transport" | "supermarket" | "charity_worker" | "government" | "employee" | "disability" | "maternity" | "social_follow" | "strava" | "donor" | nullrequired
  • substring | nullrequired
• awinTransactionIdinteger | nullrequired
• commissionBasisobjectrequired
  • channel"awin" | "direct"required
  • basisMinorintegerrequired

    0 to any

  • currencystringrequired
  • computedAtstring (date-time)required
• placedAtstring (date-time)required
• createdAtstring (date-time)required
• updatedAtstring (date-time)required

OrderRequest

• externalIdstringrequired

  1 to 100 characters

• orderNumberstring

  1 to 100 characters

• placedAtstring (date-time)
• currencystringrequired
• totalintegerrequired

  0 to 1000000000000

• subtotalinteger

  0 to 1000000000000

• taxinteger

  0 to 1000000000000

• discountTotalinteger

  0 to 1000000000000

• discountCodesstring[]

  up to 20 items

• lineItemsobject[]

  up to 200 items

  • skustring | null

    1 to 200 characters

  • quantityintegerrequired

    1 to 100000

  • priceintegerrequired

    0 to 1000000000000

  • productIdstring | integer
  • variantIdstring | integer
  • collectionsstring[]

    up to 50 items

• sessionIdstring

  pattern ^[A-Za-z0-9_-]{8,64}$

• customerEmailstring

  0 to 254 characters · pattern ^[^\s@]+@[^\s@]+\.[^\s@]+$

• newCustomerboolean
• countrystring

  pattern ^[A-Za-z]{2}$

• landingSitestring

  0 to 2048 characters

• sourceNamestring

  1 to 100 characters

• channel"online" | "in_store"
• testboolean

OrdersPage

• dataobject[]required
  • idstring (uuid)required
  • externalIdstringrequired
  • orderNumberstring | nullrequired
  • mode"live" | "test"required
  • source"pixel" | "api" | "shopify"required
  • sourceNamestring | nullrequired
  • channel"online" | "in_store"required
  • status"placed" | "partially_refunded" | "refunded" | "cancelled"required
  • currencystringrequired
  • totalintegerrequired
  • taxinteger | nullrequired
  • discountTotalintegerrequired
  • refundedTotalintegerrequired
  • codesstring[]required
  • lineItemsobject[]required
    • skustring | nullrequired
    • quantityintegerrequired
    • priceintegerrequired
    • productIdstring
    • variantIdstring
    • collectionsstring[]
  • sessionIdstring | nullrequired
  • newCustomerboolean | nullrequired
  • countrystring | nullrequired
  • device"mobile" | "tablet" | "desktop" | nullrequired
  • matchobjectrequired
    • type"code_unique" | "code_shared" | "session" | "email" | "none"required
    • campaignIdstring (uuid) | nullrequired
    • rewardIdstring (uuid) | nullrequired
    • verificationIdstring (uuid) | nullrequired
    • audience"student" | "graduate" | "apprentice" | "teacher" | "youth" | "under_26" | "over_60" | "custom_age" | "nhs" | "healthcare" | "social_worker" | "carer" | "police" | "fire" | "first_responder" | "emergency_services" | "military" | "veteran" | "key_worker" | "delivery_transport" | "supermarket" | "charity_worker" | "government" | "employee" | "disability" | "maternity" | "social_follow" | "strava" | "donor" | nullrequired
    • substring | nullrequired
  • awinTransactionIdinteger | nullrequired
  • commissionBasisobjectrequired
    • channel"awin" | "direct"required
    • basisMinorintegerrequired

      0 to any

    • currencystringrequired
    • computedAtstring (date-time)required
  • placedAtstring (date-time)required
  • createdAtstring (date-time)required
  • updatedAtstring (date-time)required
• nextCursorstring | nullrequired

RefundRequest

• refundIdstringrequired

  1 to 100 characters

• amountintegerrequired

  1 to 1000000000000

• reasonstring

  0 to 500 characters

• lineItemsobject[]

  up to 200 items

  • skustring | null

    1 to 200 characters

  • quantityintegerrequired

    1 to 100000

  • amountinteger

    0 to 1000000000000

OrderPatch

object | object

FunnelReport

• rangeobjectrequired
  • fromstring (date)required
  • tostring (date)required
  • daysintegerrequired
• filtersobjectrequired
  • mode"live" | "test"required
  • marketstring | nullrequired
  • campaignsstring[]required
  • group"day" | "audience" | "campaign" | "country" | "device" | "shopper" | "placement"required
• totalsobjectrequired
  • impressionsintegerrequired
  • opensintegerrequired
  • verificationsStartedintegerrequired
  • verifiedintegerrequired
  • repeatVerificationsintegerrequired
  • rewardsIssuedintegerrequired
  • ordersintegerrequired
  • returnedOrdersintegerrequired
  • redeemedintegerrequired
  • conversionnumber | nullrequired

    Verified / opens; null with no opens.

  • redemptionRatenumber | nullrequired

    Redeemed / rewards issued; null with no rewards.

  • returnRatenumber | nullrequired

    Returned orders / orders; null with no orders.

  • byCurrencyobject[]required

    Money per currency, never added across them.

    • currencystringrequired

      ISO 4217.

    • ordersintegerrequired
    • returnedOrdersintegerrequired
    • redeemedintegerrequired
    • revenueMinorintegerrequired

      Order totals less refunds, in minor units.

    • refundedMinorintegerrequired
    • aovMinorinteger | nullrequired
    • returnRatenumber | nullrequired
    • refundRatenumber | nullrequired

      Refunded / (revenue + refunded); null with none.

• funnelobject[]required
  • step"impressions" | "opens" | "verificationsStarted" | "verified" | "rewardsIssued" | "ordered" | "redeemed"required
  • valueintegerrequired
• rowsobject[]required
  • keystringrequired

    The group's value: a day, audience, campaign id (empty for none), ISO-2 country, device, new/returning/unknown, or placement type. Empty when unknown.

  • daystring (date)
  • labelstring | null

    Group campaign: the campaign's name.

  • impressionsintegerrequired
  • opensintegerrequired
  • verificationsStartedintegerrequired
  • verifiedintegerrequired
  • repeatVerificationsintegerrequired
  • rewardsIssuedintegerrequired
  • ordersintegerrequired
  • returnedOrdersintegerrequired
  • redeemedintegerrequired
  • conversionnumber | nullrequired

    Verified / opens; null with no opens.

  • redemptionRatenumber | nullrequired

    Redeemed / rewards issued; null with no rewards.

  • returnRatenumber | nullrequired

    Returned orders / orders; null with no orders.

  • byCurrencyobject[]required

    Money per currency, never added across them.

    • currencystringrequired

      ISO 4217.

    • ordersintegerrequired
    • returnedOrdersintegerrequired
    • redeemedintegerrequired
    • revenueMinorintegerrequired

      Order totals less refunds, in minor units.

    • refundedMinorintegerrequired
    • aovMinorinteger | nullrequired
    • returnRatenumber | nullrequired
    • refundRatenumber | nullrequired

      Refunded / (revenue + refunded); null with none.

• refreshedAtstring (date-time) | nullrequired

  When the brand's reports were last brought up to date.

WebhookEndpoint

• idstring (uuid)required
• mode"live" | "test"required
• urlstringrequired
• descriptionstringrequired
• events"verification.completed" | "reward.issued" | "capture.submitted" | "order.attributed" | "order.refunded" | "code_pool.low"[]required
• status"active" | "disabled"required
• disabledReasonstring | nullrequired

  gone (it answered 410), failing (72 hours of failures) or manual.

• failingSincestring | nullrequired
• secretHintstringrequired

  The last four characters of the signing secret.

• previousSecretExpiresAtstring | nullrequired

  Until when the secret before the last rotation still signs alongside, if it does.

• createdAtstringrequired
• updatedAtstringrequired

WebhookSubscribeRequest

• urlstringrequired

  0 to 4000 characters

• event"verification.completed" | "reward.issued" | "capture.submitted" | "order.attributed" | "order.refunded" | "code_pool.low"
• events"verification.completed" | "reward.issued" | "capture.submitted" | "order.attributed" | "order.refunded" | "code_pool.low"[]

  up to 6 items

• descriptionstring

  0 to 200 characters

WebhookEvent

• idstringrequired

  evt_ and 26 characters.

• type"verification.completed" | "reward.issued" | "capture.submitted" | "order.attributed" | "order.refunded" | "code_pool.low"required
• createdstringrequired

  ISO 8601, UTC, whole seconds.

• mode"live" | "test"required
• brandstringrequired

  The brand's slug.

• testtrue
• dataobjectrequired

Location

• idstringrequired
• storeCodestringrequired

  The brand's own id for the shop.

• namestringrequired
• addressLine1string | nullrequired
• addressLine2string | nullrequired
• citystring | nullrequired
• postcodestring | nullrequired
• countrystringrequired
• timezonestringrequired
• status"active" | "archived"required
• createdAtstring (date-time)required
• updatedAtstring (date-time)required

InStoreClaimForTill

• idstringrequired
• codestringrequired
• status"issued" | "redeemed" | "expired" | "void"required
• mode"live" | "test"required
• storeCodestringrequired
• locationIdstringrequired
• campaignobjectrequired
  • idstring (uuid)required
  • namestringrequired
• valueTextstringrequired
• issuedAtstring (date-time)required
• expiresAtstring (date-time)required
• redeemedAtstring (date-time) | nullrequired
• redeemedVia"staff_pin" | "partner_api" | "order_match" | nullrequired