Questa guida fornisce il riferimento API tecnico e gli schemi dei payload per la gestione dei codici promozionali e degli sconti nella versione 2026-04-08 dell'Universal Commerce Protocol (UCP).
Prima di creare gli endpoint, assicurati di aver esaminato la panoramica dei codici promozionali e degli sconti per i concetti di alto livello, gli invarianti matematici e le regole di gestione degli errori.
Discovery
Per ricevere codici sconto da Google, devi pubblicizzare il supporto per gli sconti nel tuo profilo. Nella versione 2026-04-08, le piattaforme verificano se la funzionalità di pagamento è estesa prima di inviare i codici sconto.
{
"ucp": {
"version": "2026-04-08",
"capabilities": {
"dev.ucp.shopping.discount": [
{
"version": "2026-04-08",
"extends": ["dev.ucp.shopping.checkout"],
"spec": "https://ucp.dev/2026-04-08/specification/discount",
"schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
}
]
}
}
}
Impatto su elementi pubblicitari e totali
Gli sconti applicati vengono visualizzati nei campi di pagamento principali utilizzando due tipi di totale distinti. Se uno sconto ha allocations che rimandano agli elementi pubblicitari, contribuisce a items_discount. Gli sconti senza allocazioni o con allocazioni a spedizione o commissioni contribuiscono a discount.
| Tipo di sconto | Tipo di totale | Dove viene visualizzato |
|---|---|---|
| Sconto elemento pubblicitario | items_discount |
line_items[].totals[type=items_discount] |
| Sconto a livello di ordine | discount |
totals[type=discount] |
Requisito di versione:
Per la versione 2026-04-08, le voci di sconto in totals[] e
line_items[].totals[] devono utilizzare valori negativi per riflettere il loro
effetto di sottrazione sulla ricevuta. Gli importi all'interno degli array discounts.applied e allocations rimangono sempre numeri interi positivi.
Esempi di API per le promozioni applicate automaticamente
Gli esempi seguenti mostrano gli sconti applicati automaticamente. I payload delle richieste non contengono un array discounts.codes, ma le risposte includono
"automatic": true e omettono il campo code.
Sconto a livello di articolo applicato automaticamente
Una vendita del 10% su tutto il sito applicata automaticamente a un elemento pubblicitario specifico.
Esempio di richiesta:
{
"line_items": [
{
"id": "li_1",
"item": { "title": "Sneakers", "price": 10000 },
"quantity": 1
}
]
}
Esempio di risposta:
{
"line_items": [
{
"id": "li_1",
"item": { "title": "Sneakers", "price": 10000 },
"quantity": 1,
"totals": [
{"type": "subtotal", "amount": 10000},
{"type": "items_discount", "amount": -1000},
{"type": "total", "amount": 9000}
]
}
],
"discounts": {
"applied": [
{
"title": "10% Off Sitewide Sale",
"amount": 1000,
"automatic": true,
"method": "each",
"allocations": [
{"path": "$.line_items[0]", "amount": 1000}
]
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
{"type": "items_discount", "display_text": "Item Discounts", "amount": -1000},
{"type": "total", "display_text": "Total", "amount": 9000}
]
}
Sconto a livello di ordine applicato automaticamente
Una regola promozionale (ad es. "10 € di sconto sugli ordini superiori a 50 €") applicata all'ordine nel suo complesso senza allocazioni specifiche per gli elementi pubblicitari.
Esempio di richiesta:
{
"line_items": [ ... ]
}
Esempio di risposta:
{
"line_items": [ ... ],
"discounts": {
"applied": [
{
"title": "$10 Off Orders Over $50",
"amount": 1000,
"automatic": true
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 6000},
{"type": "discount", "display_text": "Order Promo", "amount": -1000},
{"type": "total", "display_text": "Total", "amount": 5000}
]
}
Esempi di API per le promozioni applicate dall'utente
Gli esempi seguenti mostrano gli sconti attivati da un utente che inserisce un codice promozionale. I payload delle richieste includono i codici richiesti e le risposte li riproducono durante l'allocazione degli importi applicati.
Sconto a livello di ordine
Uno sconto fisso applicato al totale dell'ordine. Non sono necessarie allocazioni; lo
sconto si applica all'ordine nel suo complesso e utilizza type: "discount".
Esempio di richiesta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SAVE10"]
}
}
Esempio di risposta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SAVE10"],
"applied": [
{
"code": "SAVE10",
"title": "$10 Off Your Order",
"amount": 1000
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
{"type": "discount", "display_text": "Order Discount", "amount": -1000},
{"type": "total", "display_text": "Total", "amount": 4000}
]
}
Sconti misti (a livello di articolo e ordine)
Questo esempio mostra entrambi i tipi di sconto: uno sconto per articolo (20% di sconto) allocato agli elementi pubblicitari e uno sconto automatico sulla spedizione a livello di ordine.
Esempio di richiesta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SUMMER20"]
}
}
Esempio di risposta:
{
"line_items": [
{
"id": "li_1",
"item": { "title": "T-Shirt", "price": 2000 },
"quantity": 2,
"totals": [
{"type": "subtotal", "amount": 4000},
{"type": "items_discount", "amount": -800},
{"type": "total", "amount": 3200}
]
}
],
"discounts": {
"codes": ["SUMMER20"],
"applied": [
{
"code": "SUMMER20",
"title": "Summer Sale 20% Off",
"amount": 800,
"allocations": [
{"path": "$.line_items[0]", "amount": 800}
]
},
{
"title": "Free shipping on orders over $30",
"amount": 599,
"automatic": true
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
{"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
{"type": "discount", "display_text": "Order Discounts", "amount": -599},
{"type": "fulfillment", "display_text": "Shipping", "amount": 0},
{"type": "total", "display_text": "Total", "amount": 2601}
]
}
Codice sconto rifiutato
Quando un codice non è valido, viene riprodotto in codes, ma omesso da applied. Il rifiuto viene comunicato tramite un warning nell'array messages[].
Esempio di richiesta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SAVE10", "EXPIRED50"]
}
}
Esempio di risposta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SAVE10", "EXPIRED50"],
"applied": [
{
"code": "SAVE10",
"title": "$10 Off Your Order",
"amount": 1000
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
{"type": "discount", "display_text": "Order Discount", "amount": -1000},
{"type": "total", "display_text": "Total", "amount": 4000}
],
"messages": [
{
"type": "warning",
"code": "discount_code_expired",
"path": "$.discounts.codes[1]",
"content": "Code 'EXPIRED50' expired on December 1st"
}
]
}
Sconti cumulabili con allocazioni
Più sconti applicati con suddivisioni complete delle allocazioni.
Esempio di richiesta:
{
"line_items": [ ... ],
"discounts": {
"codes": ["SUMMER20", "EXTRA5"]
}
}
Esempio di risposta:
{
"line_items": [
{
"id": "li_1",
"item": { "title": "T-Shirt", "price": 6000 },
"quantity": 1,
"totals": [
{"type": "subtotal", "amount": 6000},
{"type": "items_discount", "amount": -1500},
{"type": "total", "amount": 4500}
]
},
{
"id": "li_2",
"item": { "title": "Socks", "price": 4000 },
"quantity": 1,
"totals": [
{"type": "subtotal", "amount": 4000},
{"type": "items_discount", "amount": -1000},
{"type": "total", "amount": 3000}
]
}
],
"discounts": {
"codes": ["SUMMER20", "EXTRA5"],
"applied": [
{
"code": "SUMMER20",
"title": "Summer Sale 20% Off",
"amount": 2000,
"method": "each",
"priority": 1,
"allocations": [
{"path": "$.line_items[0]", "amount": 1200},
{"path": "$.line_items[1]", "amount": 800}
]
},
{
"code": "EXTRA5",
"title": "Extra $5 Off",
"amount": 500,
"method": "across",
"priority": 2,
"allocations": [
{"path": "$.line_items[0]", "amount": 300},
{"path": "$.line_items[1]", "amount": 200}
]
}
]
},
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
{"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
{"type": "total", "display_text": "Total", "amount": 7500}
]
}