Loyalty events
points.loyalty
A profile’s loyalty point number increased.
This event includes the parameters of the transaction.charge event which generated the points.
Default retention: 30 days
Recommended retention: infinite
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| points | string | 52 |
The number of assigned points |
| $orderID | string | 13045a77-5230-481f-8f10-50d867c8d930 |
Unique ID of the transaction |
client.removePoints
A profile’s loyalty points were decreased.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| promotionCode | string | 0000080596 |
Code of the promotion |
| promotionName | string | Free fries |
Display name of the promotion |
| promotionUuid | string | 7810c17f-9e77-4053-a291-1db9d1d486f8 |
UUID of the promotion |
| points | integer | 1000 |
Total number of removed points |
| singleValue | integer | 500 |
Points removed for one redemption |
| value | integer | 1000 |
Total number of removed points |
| quantity | number | 2 |
The number of times a promotion was redeemed |
| date | integer | 1679512628953 |
Unix timestamp of the event |
points.sent
Loyalty points were sent to a different profile.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| points | integer | 200 |
The amount of transferred points |
| recipient | string | Bob |
The name of the recipient, provided by the sender |
| recipientClientId | integer | 54689894 |
The profile ID of the recipient |
| message | string | Have a snack |
Message added to the transfer, provided by the sender |
| lockIdentifier | string | d2307965-2aba-43d3-889f-cc362a1c9d07.1681561293278 |
Identifier of the point lock which will be released once the points are transferred |
points.received
Loyalty points were received from a different profile.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| points | integer | 200 |
The amount of transferred points |
| sender | string | Mike |
The name of the sender, provided by the sender |
| senderClientId | integer | 54688644 |
The profile ID of the sender |
| message | string | Have a snack |
Message added to the transfer, provided by the sender |
client.activatePromotion
This event is generated when a mobile SDK or API method activates a promotion.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| promotionCode | string | 0000080596 |
Code of the promotion |
| promotionUuid | string | 7810c17f-9e77-4053-a291-1db9d1d486f8 |
UUID of the promotion |
| promotionName | string | Free fries |
Display name of the promotion |
| promotionType | string | GENERAL |
Promotion type |
| promotionDiscountType | string | AMOUNT |
Type of the discount |
| promotionRedeemQuantityPerActivation | integer | 3 |
How many times per activation a multibuy promotion can be redeemed. 0 means no limit. |
| promotionRequireRedeemedPoints | integer | 10 |
How many loyalty points are needed to activate the promotion |
| lastingAt | string | 2023-08-24T14:15:22Z |
Time when promotion expires for the profile. If the promotion doesn't expire, the value is null. |
| date | integer | 1694777235525 |
Time when the event occurred (Unix timestamp) |
client.deactivatePromotion
This event is generated when a mobile SDK or API method deactivates a promotion.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| promotionCode | string | 0000080596 |
Code of the promotion |
| promotionUuid | string | 7810c17f-9e77-4053-a291-1db9d1d486f8 |
UUID of the promotion |
| promotionName | string | Free fries |
Display name of the promotion |
| promotionType | string | GENERAL |
Promotion type |
| promotionDiscountType | string | AMOUNT |
Type of the discount |
| promotionRedeemQuantityPerActivation | integer | 3 |
How many times per activation a multibuy promotion can be redeemed. 0 means no limit. |
| promotionRequireRedeemedPoints | integer | 10 |
How many loyalty points are needed to activate the promotion |
| lastingAt | string | 2023-08-24T14:15:22Z |
Time when promotion expires for the profile. If the promotion doesn't expire, the value is null. |
| date | integer | 1694777235525 |
Time when the event occurred (Unix timestamp) |
client.promotionExpire
A promotion expired for a profile (according to the lastingAt parameter).
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| promotionCode | string | 0000080596 |
Code of the promotion |
| promotionUuid | string | 7810c17f-9e77-4053-a291-1db9d1d486f8 |
UUID of the promotion |
| promotionName | string | Free fries |
Display name of the promotion |
| promotionType | string | GENERAL |
Promotion type |
| currentRedeemedQuantity | integer | 6 |
The number of times this promotion was redeemed by the profile. |
| promotionDiscountType | string | AMOUNT |
Type of the discount |
| promotionRequireRedeemedPoints | integer | 10 |
How many loyalty points are needed to activate the promotion |
| promotionRedeemQuantityPerActivation | integer | 3 |
How many times per activation a multibuy promotion can be redeemed. 0 means no limit. |
| date | integer | 1694777235525 |
Time when the event occurred (Unix timestamp) |
client.promotionRequest
This event is generated for each request made to /v4/promotions/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue}.
Default retention: 30 days
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| promotions | array of strings | ["1234","5678"] |
A list of promotions (promotion codes) that were returned in the response. |
| date | integer | 1694777235525 |
Time when the event occurred (Unix timestamp) |
handbill.assign
Promotions from a handbill were assigned to a profile.
- If the same handbill is requested multiple again before the generated promotion set expires, the event isn’t generated.
- If the same handbill is requested again after the expiration and a new promotion set is generated, a new event is generated too.
Default retention: 30 days
Note: Some parameters in the table apply only to certain handbill types and configurations.
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| channel | string | check-out |
Type of the handbill |
| promoCodes | array of strings | ["6ab12bc4-1433-4570-bf63-4eacef524463","690ba318-d867-4c3e-a051-e8a68daf1ef1"] | Codes of the promotions in the handbill |
| promotionsUuid | array of strings | ["3341a18a-f3bc-423d-927e-cfd21e86c962","0a0e19c4-867d-4126-84af-ab8c471f9584"] | UUIDs of the promotions in the handbill |
| id | string | 67230c01-76d4-44b8-a173-1cfe495f5e50 |
UUID of the handbill |
| variantId | string | f84141a7-c80a-49e7-b603-27cc83f4ca64 |
UUID of the generated variant |
| variantName | string | Variant A |
Name of the generated variant |
| date | integer | 1694777235525 |
Time when the event occurred (Unix timestamp) |
| limitPerDay | integer | 2 |
How many promotions were assigned, according to the limits for the variant |
| lastingType | string | RELATIVE |
The type of time period when the handbill is active (defined in the Activity section when creating the handbill) |
| lastingAt | string | 2023-08-24T14:15:22Z |
Time when promotion expires for the profile. If the promotion doesn't expire, the value is null. |
| lastingHours | integer | 24 |
Time until the promotion expires when lastingTime = RELATIVE. The countdown starts individually for a profile when the promotion is activated. |
| varietyGroupSize | integer | 3 |
Defines how many similar items may be recommended. This is calculated in according to varietyFactor. |
| varietyFactor | number | 0.5 |
The higher the number, the more variety in the choice of promotions. The choice of promotions is calculated by the AI. The highest value is 1. |
| fallback | boolean | false |
When the handbill is configured to use promotions selected by the AI, but the AI doesn't return promotions due to a technical issue, randomized promotions are used and this field is true |
| redistributionFrequencyFactor | number | 1 |
The default value of 1 allows the model to decide how often to redistribute promotions. A value lower than 1 decreases redistribution frequency, a value higher than 1 increases it. The lowest setting is 0.5 and the highest is 1.5. |
| popularityBoosting | number | 0.3 |
The importance of item popularity for the AI promotion model. 1 is highest. |
| controlGroup | boolean | true |
true if the profile belongs to the control group |
| controlGroupName | string | Control group |
The name of the control group |
voucherCode.assigned
A voucher was assigned to a profile.
Default retention: 30 days
Sources of this event
- Assigning vouchers in Mobile SDK
- Assigning vouchers in inserts
- API methods:
NOTE: API methods can also be called by SDKs and outgoing integrations.
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| poolUUID | string | add2c522-2ee5-4438-9e3e-153fb0b1f28c |
Unique identifier of the voucher pool |
| poolName | string | Example promo vouchers |
Name of the voucher pool |
| voucherUUID | string | 8fed24da-a32b-487d-b5af-78781f4e4cd9 |
Unique identifier of the voucher |
| voucherCode | string | 14EDA294 |
Code of the voucher |
| expireIn | integer | 1700917039 |
Date when the voucher expires (Unix timestamp in seconds). If the voucher never expires, the value is null. |
| assignedAt | integer | 1698242239 |
Date of assigning the voucher (Unix timestamp in seconds) |
voucherCode.redeemed
A voucher was redeemed.
Default retention: 30 days
Sources of this event
/v4/vouchers/item/redeem API method
NOTE: API methods can also be called by SDKs and outgoing integrations.
| Parameter | Type | Example | Description |
|---|---|---|---|
| Base parameters | various | n/a | Parameters that may exist in all events |
| poolUUID | string | add2c522-2ee5-4438-9e3e-153fb0b1f28c |
Unique identifier of the voucher pool |
| poolName | string | Example promo vouchers |
Name of the voucher pool |
| voucherUUID | string | 8fed24da-a32b-487d-b5af-78781f4e4cd9 |
Unique identifier of the voucher |
| voucherCode | string | 14EDA294 |
Code of the voucher |
| redeemedAt | integer | 1700139439 |
Date of redeeming the voucher (Unix timestamp in seconds) |
