Appearance
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 Innercrowd | We call |
|---|---|
| An organiser creates a campaign (a quest) or a reward | POST /v1/vouchers/upsert with the voucher, no codes yet |
| Ambassadors join the campaign, or claim the reward | POST /v1/vouchers/upsert with the voucher and the new codes |
| The organiser changes the discount, product types, limits or end date | POST /v1/vouchers/upsert with the voucher only |
| An ambassador leaves, or a code is revoked | POST /v1/vouchers/delete with the voucher and those codes |
| The campaign or reward is deleted | POST /v1/vouchers/delete with the voucher only |
Endpoints
| Endpoint | Does | Answers |
|---|---|---|
POST /v1/vouchers/upsert | Creates 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/delete | Deletes 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.
| Option | Type | Default | What it does |
|---|---|---|---|
version | string | "v1" | The version you implement, and the prefix of the paths we call. |
discountTypes | list | required | The discount types you support: "percentage", "fixed" or both. We only send those. |
codes.length | integer | 12 | The length of every code we send. |