Обзор промокодов и скидок

В этом руководстве объясняется, как обрабатывать промокоды и скидки в процессе оформления заказа по протоколу Universal Commerce Protocol (UCP).

Когда пользователь начинает оформление заказа, Google предоставляет рекламные данные из нескольких источников. Ваша интеграция должна проверять эти акции в режиме реального времени и возвращать подробную разбивку скидок по каждой позиции. Чтобы получать коды скидок, вы должны указать поддержку скидок в своем профиле UCP.

Источники продвижения

Google предоставляет данные о рекламных акциях из двух основных источников:

• Автоматически применяемые акции: предложения, поступающие непосредственно из ваших фидов Google Merchant Center. Google автоматически применяет эти предложения к корзине покупок.
• Промокоды, применяемые пользователями: промокоды, которые пользователи вводят вручную при оформлении заказа, например, общедоступные коды скидок или персонализированные предложения по электронной почте. Интерфейс оформления заказа поддерживает максимум 10 примененных промокодов за сессию.

Реализация API оформления заказа

Когда пользователь создает сессию оформления заказа или изменяет промокод, Google отправляет запрос на ваши конечные точки POST /checkout-sessions или PUT /checkout-sessions/{id} .

Ваша интеграция использует три основных массива для обработки скидок:

• Запрошенные коды ( discounts.codes ): Google отправляет промокоды пользователя в этом массиве. Для сохранения состояния необходимо вывести этот массив обратно в ответе. Индекс массива ответа сопоставляет предупреждения проверки с конкретными кодами.
  • Семантика замены: отправка этого массива заменяет любой ранее отправленный код.
  • Очистить коды: отправка пустого массива ( [] ) удаляет все коды скидок.
  • Регистронезависимый режим: Ваша бизнес-логика должна соответствовать коду без учета регистра.
• Примененные скидки ( discounts.applied ): Если код действителен, включите его в этот массив вместе с удобочитаемым title , положительным amount скидки и method расчета.
• Отклонения ( messages ): Если код недействителен, исключите его из массива applied и сообщите причину ошибки, используя каноническое предупреждение в массиве messages .

Математические инварианты

Для обеспечения целостности данных и корректного отображения чеков ваша интеграция должна соответствовать следующим математическим правилам во всех версиях UCP:

• Сумма распределения: Сумма allocations[].amount должна равняться applied_discount.amount .
• Сумма итоговых значений по позициям: totals[type=items_discount].amount должна равняться сумме line_items[].totals[type=items_discount].amount .

Обработка ошибок и обратная связь с пользователями

Если промокод или предложение подарочной карты недействительны, или если ранее примененное предложение аннулировано, ваш API должен возвращать четкие коды причин. Это гарантирует, что Google отобразит пользователю соответствующую обратную связь.

Для операций, влияющих на общую сумму заказа или на ожидания пользователя относительно этой суммы, необходимо использовать type: "warning" . Это гарантирует, что ошибки будут отображаться пользователю, а не обрабатываться платформой незаметно. Например, если пользователь ожидает скидку, но не получает её из-за истечения срока действия кода, необходимо сообщить ему об этом.

Справочник кодов ошибок

В массиве messages вашего ответа верните следующие канонические коды ошибок. Используйте "type": "warning" для обозначения права на получение повышения:

Следующие шаги

Просмотрите данные API и технические характеристики реализации для вашей версии UCP:

• Версия 2026-04-08 Промокоды и скидки
• Версия 2026-01-23 Промокоды и скидки

В этом руководстве объясняется, как обрабатывать промокоды и скидки в процессе оформления заказа по протоколу Universal Commerce Protocol (UCP).

Когда пользователь начинает оформление заказа, Google предоставляет рекламные данные из нескольких источников. Ваша интеграция должна проверять эти акции в режиме реального времени и возвращать подробную разбивку скидок по каждой позиции. Чтобы получать коды скидок, вы должны указать поддержку скидок в своем профиле UCP.

Источники продвижения

Google предоставляет данные о рекламных акциях из двух основных источников:

• Автоматически применяемые акции: предложения, поступающие непосредственно из ваших фидов Google Merchant Center. Google автоматически применяет эти предложения к корзине покупок.
• Промокоды, применяемые пользователями: промокоды, которые пользователи вводят вручную при оформлении заказа, например, общедоступные коды скидок или персонализированные предложения по электронной почте. Интерфейс оформления заказа поддерживает максимум 10 примененных промокодов за сессию.

Реализация API оформления заказа

Когда пользователь создает сессию оформления заказа или изменяет промокод, Google отправляет запрос на ваши конечные точки POST /checkout-sessions или PUT /checkout-sessions/{id} .

Ваша интеграция использует три основных массива для обработки скидок:

• Запрошенные коды ( discounts.codes ): Google отправляет промокоды пользователя в этом массиве. Для сохранения состояния необходимо вывести этот массив обратно в ответе. Индекс массива ответа сопоставляет предупреждения проверки с конкретными кодами.
  • Семантика замены: отправка этого массива заменяет любой ранее отправленный код.
  • Очистить коды: отправка пустого массива ( [] ) удаляет все коды скидок.
  • Регистронезависимый режим: Ваша бизнес-логика должна соответствовать коду без учета регистра.
• Примененные скидки ( discounts.applied ): Если код действителен, включите его в этот массив вместе с удобочитаемым title , положительным amount скидки и method расчета.
• Отклонения ( messages ): Если код недействителен, исключите его из массива applied и сообщите причину ошибки, используя каноническое предупреждение в массиве messages .

Математические инварианты

Для обеспечения целостности данных и корректного отображения чеков ваша интеграция должна соответствовать следующим математическим правилам во всех версиях UCP:

• Сумма распределения: Сумма allocations[].amount должна равняться applied_discount.amount .
• Сумма итоговых значений по позициям: totals[type=items_discount].amount должна равняться сумме line_items[].totals[type=items_discount].amount .

Обработка ошибок и обратная связь с пользователями

Если промокод или предложение подарочной карты недействительны, или если ранее примененное предложение аннулировано, ваш API должен возвращать четкие коды причин. Это гарантирует, что Google отобразит пользователю соответствующую обратную связь.

Для операций, влияющих на общую сумму заказа или на ожидания пользователя относительно этой суммы, необходимо использовать type: "warning" . Это гарантирует, что ошибки будут отображаться пользователю, а не обрабатываться платформой незаметно. Например, если пользователь ожидает скидку, но не получает её из-за истечения срока действия кода, необходимо сообщить ему об этом.

Справочник кодов ошибок

В массиве messages вашего ответа верните следующие канонические коды ошибок. Используйте "type": "warning" для обозначения права на получение повышения:

Следующие шаги

Просмотрите данные API и технические характеристики реализации для вашей версии UCP:

• Версия 2026-04-08 Промокоды и скидки
• Версия 2026-01-23 Промокоды и скидки