CRM gifts

A CRM or marketing-automation system sends a gift when a player reaches a journey step, such as a birthday, a deposit milestone or a win-back.

Requires: a key with PERSONAL_LINKS, plus ORDERS to follow the resulting orders, and a webhook URL.

Choose the method

Situation	Method
The player chooses the gift, or you have no address	Personal links. Send the link through your channel. Luxorr collects the choice and the address.
The gift is fixed and you have the address	Direct order. See orders.

Most CRM journeys use personal links.

1. Set up campaigns

Ask Luxorr for one campaign per journey type, such as “VIP birthday” or “Deposit milestone”. A campaign holds the gifts a player can choose from, under one brand.

2. Send a batch per journey step

Collect the players who reached the step and send them in one batch:

{
  "campaignId": "1e2d3c4b-5a69-4c1f-9a52-8d0e4f4b9a3e",
  "recipients": [
    { "externalRecipientId": "player-1001", "label": "Ann Smith", "message": "Happy birthday from the VIP team!", "locale": "en-US" },
    { "externalRecipientId": "player-1002", "label": "Bob Jones", "message": "Alles Gute zum Geburtstag!", "locale": "de-DE" }
  ]
}

• en-US is always accepted. Other locales must be enabled for the tenant; GET /me lists them in tenant.locales. A locale that is not enabled rejects that recipient with not_enabled.
• Store link.claimUrl for every CREATED result.
• Fix the REJECTED recipients and send only those in a new batch.

Idempotency key per batch

You can derive the Idempotency-Key from the batch, for example birthday-2026-10-06T09:00. A retry must send the same body, byte for byte:

1. Build the batch once. Store the exact JSON with the key, then send it.
2. On a timeout or 5xx, resend the stored JSON with the same key. If the first attempt succeeded, the response is replayed with Idempotent-Replayed: true.
3. Do not rebuild the body under the same key. A different body answers 422 idempotency_key_reused.
4. To send a changed batch, first resend the stored body with the old key to learn which players have links. Then send only the remaining players under a new key, such as birthday-2026-10-06T09:00-2. Each recipient in a new batch gets a new link.

3. Deliver the link

Put claimUrl in your message: email, push, in-app inbox or chat. The gift site shows the operator’s brand.

When the tenant requires approval, links start REQUESTED and cannot be claimed yet. Send the message after personal_link.approved arrives.

4. Update the journey

Event	Meaning
personal_link.created	A link was created outside your journey, for example in the workspace. Links your key created are in the batch response and the feed, not in webhooks.
personal_link.claimed	The player chose a gift. data.orderId is the order. Mark the step done.
order.status_changed → SENT	The gift is on its way.
personal_link.cancelled	The link was withdrawn. Stop reminders.

If your system processes events in batches, read the event feed on a schedule instead. The feed keeps 30 days of events.

5. Reminders and cancellation

Send a reminder with the same claimUrl. To withdraw a link, call POST /personal-links/{linkId}:cancel with a reason. The player then sees the link as expired.