Redemption entities

Represent the customers, employees or devices that redeem, block them, and erase them on request.

A Redemption Entity is your own record of who or what redeems: an end customer, an employee, a device or an account. Entities let you apply per-entity limits, bind Redemption Links to one person, and find every redemption of one customer.

What an entity is

Field	Meaning
refId	Your opaque identifier, unique among your entities when set. 1-128 characters of letters, digits and ._:@/+=-, for example customer:42 or device:5f2c…. Use an id from your own system, not an email address or a name: no personal data is required
displayName	Optional label for your dashboard users (up to 120 characters)
metadata	Optional JSON object of your own (up to 16 KiB)
email	Set only for entities created by the Email OTP Gate: the address the visitor verified. You cannot write it through the API
status	active, blocked or erased
createdVia	api, dashboard, redemption-link-otp or import

Entities belong to your partner only; another consumer can use the same refId for its own entity. Reading entities needs view-consumer-redemption-entities; creating, updating, blocking and unblocking need manage-consumer-redemption-entities; erasing needs erase-consumer-redemption-entities. All three can be granted to API keys.

Creating entities

Most integrations never create entities explicitly: they pass an inline redemptionEntity: {"refId": "customer:42"} when redeeming or when creating a Redemption Link, and the platform finds or creates the entity in the same transaction.

To create one up front, use POST /consumer/v1/redemption-entities:

curl -X POST "$VOUCHER_API_BASE_URL/consumer/v1/redemption-entities" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: entity-customer-42" \
  -d '{ "refId": "customer:42", "metadata": { "segment": "job-ticket" } }'

All fields are optional, so {} creates an anonymous entity. A refId that already exists answers 409 ref-id-taken, and more.redemptionEntityId names the existing entity. Sending email answers 400 data-failed-validation with the constraint unknown-field.

• Find an entity by your id with GET /consumer/v1/redemption-entities?filter[refId]=customer:42, or search over refId, displayName and email with search.
• Change refId, displayName or metadata with PATCH. Existing redemptions keep pointing at the entity id; their history is not rewritten.
• The webhook redemption-entity-created is sent for entities created in the dashboard and by the Email OTP Gate, not for entities your API key creates.

Blocking

POST …/{redemptionEntityId}:block stops an entity from redeeming, for example while you investigate misuse:

curl -X POST "$VOUCHER_API_BASE_URL/consumer/v1/redemption-entities/9017:block" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Idempotency-Key: block-9017-2026-10-26"

While an entity is blocked:

• redeeming with it (by id or by its refId) answers 409 redemption-entity-blocked;
• Redemption Links bound to it, and email OTP verification for its address, refuse to redeem;
• creating a new link for it answers the same 409.

:unblock makes it active again. Blocking an entity that is already blocked, or unblocking an active one, answers 409 invalid-state-transition.

Erasure (GDPR)

When a customer asks you to delete their data, call POST …/{redemptionEntityId}:erase:

curl -X POST "$VOUCHER_API_BASE_URL/consumer/v1/redemption-entities/9017:erase" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Idempotency-Key: erase-9017"

Erasure is immediate and irreversible. In one step the platform:

• sets refId, email, displayName and metadata to null and the status to erased;
• ends the entity’s landing sessions and pending email codes;
• revokes every entity-bound Redemption Link of the entity, so those links answer 410 redemption-link-revoked from then on.

Redemptions of the entity stay in your ledger for accounting, now anonymous: they keep the entity id and their own metadata, which is why redemption metadata must never contain personal data. After erasure, updating, blocking, unblocking or erasing the entity again answers 409 redemption-entity-erased; you can later create a new entity with the old refId.

AllRide processes entity data on your behalf as a processor. The audit log records that an entity was changed or erased but never stores its refId, email, name or metadata.

Related

• Redeeming vouchers
• Redemption links
• Email OTP links
• Erase a redemption entity