> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs-consumer.voucher.allride.io/consumer/email-otp-links.md): 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](https://docs-consumer.voucher.allride.io/consumer/redeeming.md#attaching-a-redemption-entity) or when creating a [Redemption Link](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md), and the platform finds or creates the entity in the same transaction.

To create one up front, use [`POST /consumer/v1/redemption-entities`](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-create):

```bash theme={null}
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`](https://docs-consumer.voucher.allride.io/errors/catalog#ref-id-taken), and `more.redemptionEntityId` names the existing entity. Sending `email` answers 400 [`data-failed-validation`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-update). Existing redemptions keep pointing at the entity id; their history is not rewritten.
* The webhook [`redemption-entity-created`](https://docs-consumer.voucher.allride.io/webhooks/events/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`](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-block) stops an entity from redeeming, for example while you investigate misuse:

```bash theme={null}
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`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-unblock) makes it `active` again. Blocking an entity that is already blocked, or unblocking an active one, answers 409 [`invalid-state-transition`](https://docs-consumer.voucher.allride.io/errors/catalog#invalid-state-transition).

## Erasure (GDPR)

When a customer asks you to delete their data, call [`POST …/{redemptionEntityId}:erase`](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-erase):

```bash theme={null}
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`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/errors/catalog#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](https://docs-consumer.voucher.allride.io/consumer/redeeming.md)
* [Redemption links](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md)
* [Email OTP links](https://docs-consumer.voucher.allride.io/consumer/email-otp-links.md)
* [Erase a redemption entity](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemption-entities-erase.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.