Ce guide fournit la documentation de référence technique de l'API et les schémas de charge utile nécessaires pour gérer les programmes de fidélité, les abonnements, les avantages et les prévisions de récompenses dans la version 2026-04-08 de l'Universal Commerce Protocol (UCP).
Avant de créer vos points de terminaison, assurez-vous d'avoir consulté la présentation du programme de fidélité pour comprendre les concepts généraux et les dépendances.
Discovery
Pour prendre en charge les fonctionnalités liées au programme de fidélité, vous devez indiquer la capacité "loyalty" dans votre profil UCP. Étant donné que les avantages fidélité ont souvent un impact sur le prix, vous devez également activer les remises.
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.common.loyalty": [
{
"version": "2026-04-08",
"extends": [
"dev.ucp.shopping.checkout"
],
"spec": "https://ucp.dev/2026-04-08/specification/loyalty",
"schema": "https://ucp.dev/2026-04-08/schemas/common/loyalty.json"
}
],
"dev.ucp.shopping.discount": [
{
"version": "2026-04-08",
"extends": [
"dev.ucp.shopping.cart",
"dev.ucp.shopping.checkout"
],
"spec": "https://ucp.dev/2026-04-08/specification/discount",
"schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
}
]
}
}
}
Exemples d'API pour les programmes de fidélité
Les exemples suivants montrent comment gérer les prix réservés aux membres validés et les prévisions de récompenses.
Prix réservés aux membres validés
Lorsque vous validez l'adhésion d'un utilisateur au programme de fidélité, appliquez la remise inconditionnelle sur le prix réservé aux membres (provisional: false) et renvoyez un display_id masqué pour cette adhésion. Utilisez l'association d'identités comme méthode principale pour valider l'adhésion à un programme de fidélité.
Exemple de requête :
{
"line_items": [
{
"item": {
"id": "prod_1"
},
"quantity": 1
}
]
}
Exemple de réponse :
{
"discounts": {
"applied": [
{
"title": "Loyalty benefit 1",
"amount": 10,
"provisional": false,
"allocations": [
{"path": "$.line_items[0]", "amount": 10}
]
}
]
},
"loyalty": {
"com.example.retail_club": {
"id": "membership_1",
"display_id": "****5678",
"name": "My Loyalty Program",
"tiers": [
{
"id": "tier_1",
"name": "Retail Club Member",
"benefits": [
{
"id": "BEN_001",
"description": "Get $10 off with $500+ purchase."
},
{ "id": "BEN_002", "description": "Early access to sales" }
]
}
],
"provisional": false
}
}
}
Plusieurs avantages ayant un impact sur le prix
Le programme de fidélité peut gérer plusieurs abonnements simultanément. Dans cet exemple, l'utilisateur bénéficie d'une remise supplémentaire de 15 % et de la livraison gratuite, car il est membre de Retail Club et de Retail Rewards.
Exemple de requête :
{
"line_items": [
{
"item": {
"id": "prod_1"
},
"quantity": 1
}
]
}
Exemple de réponse :
{
"line_items": [
{
"id": "li_1",
"item": {
"id": "prod_1",
"title": "T-Shirt",
"price": 1000
},
"quantity": 1,
"totals": [
{"type": "subtotal", "amount": 1000},
{
"type": "items_discount",
"display_text": "Club member benefit",
"amount": -150
},
{"type": "total", "amount": 850}
]
}
],
"discounts": {
"applied": [
{
"title": "Club Members get 15% Bonus",
"amount": 150,
"method": "each",
"provisional": false,
"allocations": [
{"path": "$.line_items[0]", "amount": 150}
]
},
{
"title": "Free shipping for Retail Rewards member",
"amount": 199,
"automatic": true,
"provisional": false
}
]
},
"loyalty": {
"com.example.retail_club": {
"id": "membership_1",
"display_id": "****5678",
"name": "Retail Club",
"provisional": false,
"tiers": [
{
"id": "gold",
"name": "Gold Member",
"benefits": [
{ "id": "BEN_001", "description": "Early access to sales" }
]
}
]
},
"com.example.retail_rewards": {
"id": "membership_2",
"display_id": "****1234",
"name": "Retail Rewards",
"provisional": false,
"tiers": [
{
"id": "rewards_member",
"name": "Retail Rewards",
"benefits": [
{ "id": "BEN_002", "description": "Exclusive customer support" }
]
}
]
}
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 1000},
{
"type": "items_discount",
"display_text": "Club member benefit",
"amount": -150
},
{
"type": "discount",
"display_text": "Free shipping for Retail Rewards member",
"amount": -199
},
{"type": "fulfillment", "display_text": "Shipping", "amount": 0},
{"type": "total", "display_text": "Estimated Total", "amount": 651}
]
}
Prévision des récompenses
Afficher les prévisions de récompenses aide les utilisateurs à comprendre la valeur qu'ils retirent d'une transaction. Utilisez l'objet earning_forecast pour lister le montant total des récompenses et le tableau breakdown pour indiquer de manière transparente comment ce montant a été calculé.
Exemple de requête :
{
"line_items": [
{
"item": {
"id": "prod_1"
},
"quantity": 1
}
]
}
Exemple de réponse :
{
"line_items": [
{
"id": "li_1",
"item": {
"id": "prod_1",
"title": "T-Shirt",
"price": 1000
},
"quantity": 1,
"totals": [
{"type": "subtotal", "amount": 1000},
{"type": "total", "amount": 1000}
]
}
],
"loyalty": {
"com.example.retail_club": {
"id": "membership_1",
"display_id": "****5678",
"name": "Retail Club",
"provisional": false,
"tiers": [
{
"id": "gold",
"name": "Gold",
"benefits": [
{ "id": "BEN_001", "description": "1 point per $1 on everything" },
{
"id": "BEN_002",
"description": "2 extra point/dollar on footwear"
}
]
}
],
"rewards": [
{
"currency": {
"name": "LoyaltyStars",
"code": "LST"
},
"earning_forecast": {
"amount": 30,
"breakdown": [
{
"id": "RULE_1",
"description": "1 point/dollar on everything",
"amount": 10,
"benefit_id": "BEN_001"
},
{
"id": "RULE_2",
"description": "2 extra point/dollar on footwear",
"amount": 20,
"benefit_id": "BEN_002"
}
]
}
}
]
}
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 1000},
{"type": "total", "display_text": "Estimated Total", "amount": 1000}
]
}