Loyalty Details schema field group
Loyalty Details is a standard schema field group for the XDM Individual Profile class. It provides a single object-type field, loyalty, that models a customer’s loyalty program membership state, including loyalty IDs, points balances, tier assignments, rewards, challenges, and card details.
This page is for schema designers and data engineers familiar with XDM Individual Profile and schema field groups. After reading this page, you can map loyalty profile data to the correct loyalty field paths.
When to use this field group when-to-use
Use this field group when all of the following conditions apply.
- The schema class is XDM Individual Profile and represents a loyalty program member’s current state.
- The schema stores persistent loyalty attributes in Real-Time Customer Profile.
- Downstream use cases require loyalty membership state for segmentation or personalization.
Use XDM ExperienceEvent schemas for event-based loyalty activity such as points accrual, challenge completions, or tier change events.
Field group structure structure
The loyalty object contains the following properties.
adjustedPointscardsDetailschallengesexpiredPointsjoinDatelifetimePointslifetimePurchasesloyaltyIDnextTierpointspointsExpirationLists loyalty points, or groups of loyalty points, that are scheduled to expire. Each array item contains:
pointsExpirationDate: The date and time when the points expire.pointsExpiring: The number of points expiring on the associated date.
pointsRedeemedpointsToNextTierprogrampromisedPointsreturnedPointsrewardsstatusactive, disabled, or suspended.tiertierExpiryDatetierUpgradeDateupgradeDatetierUpgradeDate instead. Update existing schemas and source mappings that reference upgradeDate to use tierUpgradeDate.The following example shows the loyalty object with representative values for the nested structures. See the populated example in the XDM repository for a complete valid payload.
{
"loyalty": {
"program": "Acme Rewards",
"tier": "gold",
"points": 4200,
"pointsExpiration": [
{ "pointsExpirationDate": "2026-12-31T00:00:00Z", "pointsExpiring": 500 }
],
"cardsDetails": [
{ "number": "LC-0042", "status": "active" }
],
"challenges": [
{
"id": "CH-001",
"state": "active",
"tasks": [{ "name": "Make 3 purchases", "goal": 3, "progress": 1 }]
}
],
"rewards": {
"badges": [
{ "id": "BDG-100", "state": "active" }
]
}
}
}
cardsDetails cardsDetails
cardsDetails is an array of objects that captures information about loyalty cards associated with the member.
numberseriesstatusactive, inactive, or suspended.challenges challenges
challenges is an array of objects that captures loyalty challenges associated with the member, including challenge progress and related tasks.
descriptionendDatefrequencyTypeidnameseriesstartDatestateactive, completed, or expired.tasksLists tasks associated with the loyalty challenge. Each array item contains:
endDate: The task end date and time.entity: The entity associated with the task.goal: The target value for the task.name: The task name.progress: Current progress toward the task goal.startDate: The task start date and time.state: Current task state.type: Task type or category.
rewards rewards
The rewards object captures rewards associated with the loyalty program.
badgesAchievement badges earned by the member. Each array item contains:
id: Badge identifier.name: Badge name.series: Badge series or collection.startDate: Date and time when the badge became active.endDate: Date and time when the badge expires.state: Current badge state.
couponsLoyalty coupons available to the member. Each array item contains:
discountValue: Monetary discount value.endDate: Coupon expiration date.id: Coupon identifier.name: Coupon name.redemptionCount: Number of times the coupon has been redeemed.redemptionLimit: Maximum number of coupon redemptions.series: Coupon series or campaign.startDate: Date and time when the coupon becomes valid.state: Current coupon state.storeName: Name of the associated store.
giveawaysGiveaway promotions associated with the member. Each array item contains:
endDate: Giveaway end date.id: Giveaway identifier.name: Giveaway name.partnerId: Partner identifier.partnerName: Partner name.series: Giveaway series or campaign.startDate: Giveaway start date.state: Current giveaway state.type: Giveaway type or category.
referralsReferral rewards earned by the member. Each array item contains:
endDate: Referral end date.id: Referral identifier.name: Referral reward name.recipient: Identifier or name of the referred person.series: Referral series or campaign.startDate: Referral start date.state: Current referral state.
Next steps next-steps
Use the following resources when implementing loyalty profile schemas.
- Add this field group to an XDM Individual Profile schema using the Schema Editor field group guide before ingesting loyalty profile data.
- Use the populated example in the XDM repository to validate loyalty payload mappings.
- Consult the full schema for data type constraints and required field definitions.