Skip to content

Vouchers ​

Every ambassador shares a personal code. When you advertise vouchers in /v1/account, we create those codes in your platform ourselves, keep them in line with the organiser's campaign, and remove them when they are no longer needed. Sales come back through voucher.code on /v1/orders, as described in Orders.

Every call carries a voucher: the rules, under our id. Those are the discount, the event and product types it applies to, its limits and its end date. Next to it come the codes that share those rules. How you store that is up to you: as a coupon series with its codes, or as separate codes that each carry a copy of the rules.

Triggers ​

In InnercrowdWe call
An organiser creates a campaign (a quest) or a rewardPOST /v1/vouchers/upsert with the voucher, no codes yet
Ambassadors join the campaign, or claim the rewardPOST /v1/vouchers/upsert with the voucher and the new codes
The organiser changes the discount, product types, limits or end datePOST /v1/vouchers/upsert with the voucher only
An ambassador leaves, or a code is revokedPOST /v1/vouchers/delete with the voucher and those codes
The campaign or reward is deletedPOST /v1/vouchers/delete with the voucher only

Endpoints ​

EndpointDoesAnswers
POST /v1/vouchers/upsertCreates the voucher or replaces its rules, and adds up to 100 codes to it. New rules apply to all of the voucher's codes. Codes you already have are fine; codes we don't list stay as they are.200 with the voucher's shop link (urlTemplate) and the codes you could not add, and why. 422 with a message when the voucher itself can't be stored, for example for an unknown event or product type.
POST /v1/vouchers/deleteDeletes up to 100 of the voucher's codes. Without codes, deletes the voucher and all of its codes. Unknown vouchers and codes are fine.204. A POST, because some proxies and HTTP clients drop the body of a DELETE.
json
{
  "voucher": {
    "id": "9b1f0c2e-4d7a-4c1e-9a53-2f6e8d0b7c41",
    "discount": { "type": "percentage", "value": 15 },
    "appliesTo": {
      "event": { "id": "evt_123" },
      "productTypes": [{ "id": "tt_1" }, { "id": "tt_2" }]
    },
    "limits": { "ordersPerCode": 5, "productsPerOrder": null },
    "validUntil": "2027-07-03T20:00:00+02:00"
  },
  "codes": [{ "code": "SAMJANSEN015" }, { "code": "KIMDEVRIES07" }]
}
json
{
  "urlTemplate": "https://shop.ticketco.example/evt_123?code={code}",
  "rejected": [
    {
      "code": "KIMDEVRIES07",
      "reason": "taken",
      "message": "Already used by another voucher."
    }
  ]
}
json
{
  "voucher": { "id": "9b1f0c2e-4d7a-4c1e-9a53-2f6e8d0b7c41" },
  "codes": [{ "code": "SAMJANSEN015" }, { "code": "KIMDEVRIES07" }]
}
json
{
  "voucher": { "id": "9b1f0c2e-4d7a-4c1e-9a53-2f6e8d0b7c41" }
}

A fixed amount instead of a percentage: "discount": { "type": "fixed", "value": { "amount": 500, "currency": "EUR" } }. Both deletes answer 204, also when the voucher or codes were already gone.

Idempotency

We choose the voucher id and the codes. Repeating a call gives the same result, so a retry after a timeout never creates a second voucher or a stray code.

Storage

With coupon series, one voucher is one series. With separate codes only, copy the rules onto each code, and update the codes you hold for a voucher when its rules change. A code always stays with the voucher it was added to.

Shop links

urlTemplate is the page where a fan buys tickets with the code already applied. We replace {code} with each ambassador's code, so your shop should accept every code of the voucher this way. It may differ per voucher, for example per event, and we always use the one from the latest call. Send null when your shop can't apply a code from a link; ambassadors then share the code itself.

Rules

Leave out productTypes and the voucher applies to every product type of the event, including ones added later. limits.ordersPerCode is how many orders can use each code. limits.productsPerOrder is how many products in one order get the discount; the rest of the order is sold at full price. A null limit means unlimited. A reward uses 1 for both; a campaign usually only limits the orders.

Deletion

Orders that already used a code keep it in voucher.code, so the ambassador keeps the credit. If your platform can't delete a code that was used, deactivating it is enough. We never add a deleted code again.

Supported features

In /v1/account, capabilities.vouchers lists the discount types your platform supports (required), and optionally the code length. We only send discount types you list. Both limits are part of the voucher capability in this version, so support them before you advertise it. A campaign or reward that needs something you don't support can't hand out codes on your platform, and the organiser sees why while setting it up.

Code format

We send codes of A–Z and 0–9, exactly codes.length characters long (12 when you don't say). Reject a code as taken when it is already in use elsewhere, a code made in your back office included, and as invalid when your platform can't accept it. We pick another code and try again.

Configuration ​

In capabilities.vouchers of /v1/account.

OptionTypeDefaultWhat it does
versionstring"v1"The version you implement, and the prefix of the paths we call.
discountTypeslistrequiredThe discount types you support: "percentage", "fixed" or both. We only send those.
codes.lengthinteger12The length of every code we send.