Promo codes and discounts overview

This guide explains how to handle promotional codes and discounts within the Universal Commerce Protocol (UCP) checkout flow.

When a user initiates a checkout session, Google provides promotional data from multiple sources. Your integration must validate these promotions in real time and return a granular line-item breakdown of the discounts. To receive discount codes, you must advertise discount support in your UCP profile.

Promotion sources

Google provides promotional data from two primary sources:

  • Auto-applied promotions: Offers ingested directly from your Google Merchant Center feeds. Google automatically applies these offers to the cart.
  • User-applied promotions: Promotional codes that users manually enter during checkout, such as public discount codes or personalized email offers. The checkout UI supports a maximum of 10 applied promo codes per session.

Checkout API implementation

When a user creates a checkout session or modifies a promotional code, Google sends a request to your POST /checkout-sessions or PUT /checkout-sessions/{id} endpoints.

Your integration relies on three main arrays to handle discounts:

  • Requested codes (discounts.codes): Google submits the user's promo codes in this array. You must echo this array back in your response to maintain state. The response array index maps validation warnings back to specific codes.
    • Replacement semantics: Submitting this array replaces any previously submitted codes.
    • Clear codes: Sending an empty array ([]) removes all discount codes.
    • Case-insensitive: Your business logic must match codes case-insensitively.
  • Applied discounts (discounts.applied): If a code is valid, include it in this array along with a human-readable title, the positive amount of the discount, and the calculation method.
  • Rejections (messages): If a code is invalid, omit it from the applied array and communicate the failure reason using a canonical warning in the messages array.

Mathematical invariants

To ensure data integrity and proper receipt rendering, your integration must adhere to the following mathematical rules across all UCP versions:

  • Allocation sum: The sum of allocations[].amount must equal the applied_discount.amount.
  • Line-item totals sum: totals[type=items_discount].amount must equal the sum of line_items[].totals[type=items_discount].amount.

Error handling and user feedback

If a promo code or gift card offer isn't applicable, or if a previously applied offer is removed, your API must return clear reason codes. This ensures that Google displays the appropriate feedback to the user.

Operations that affect order totals, or the user's expectation of the total, must use type: "warning". This ensures that errors surface to the user rather than being silently handled by the platform. For example, if a user expects a discount but doesn't receive it because the code expired, you must inform them.

Error code reference

Return the following canonical error codes within the messages array of your response. Use "type": "warning" to communicate promotion eligibility:

Error code Description
discount_code_expired The code is expired.
discount_code_invalid The code isn't found or is malformed.
discount_code_already_applied The code is already applied.
discount_code_combination_disallowed The code can't be combined with another active discount, or a store-specific limit was reached.
discount_code_user_not_logged_in The code requires an authenticated user.
discount_code_user_ineligible The user doesn't meet the eligibility criteria.

Next steps

View the API payloads and technical implementation details for your UCP version:

Previous
Cart overview