Schema dev.uip.shopping.promotions

UCP Promotions Extension

Capability Name: dev.uip.shopping.promotions
Version: 2026-01-28

Extends the Universal Commerce Protocol (UCP) Checkout schema with robust promotions support. This specification details active codes (coupons, referrals, gift cards), monetary discounts, free item rewards, and granular allocation of savings.

JSON Schema ID

https://uip.dev/schemas/ucp/shopping/promotions.json

Checkout

Entry Point

The entry point for the extension. It adds a promotions object to the standard checkout response.

Property	Type	Description
promotions	promotions_object	Container for all promotion-related data.

promotions_object

Object

The main container holding active codes and resulting rewards (discounts, free items).

Properties

Property	Type	Description
codes	Array<Promotion Code>	List of active codes (coupons, referrals) on the session.
discounts	Array<Discount>	Read Only List of monetary discounts applied.
free_items	Array<Free Item>	Read Only List of free items added to the session.

Discount

Details of a monetary reduction applied to the session.

Property	Type	Description
title Required	string	Human-readable description of the discount.
target Required	enum	What the discount is applied to. cart additional_cost item bundle
amount Required	integer	Total value of the discount. ⚠ Represented in minor currency units
method	enum	Distribution method for item/bundle targets. each across one
code	string	JSONPath reference to the code triggering this discount.
allocations	Array<Allocation>	Breakdown of where this discount was applied.

Examples

Session Discount

{
  "title": "10€ session discount",
  "target": "cart",
  "amount": 100
}

Shipping Discount

{
  "title": "10€ session shipping cost discount",
  "target": "additional_cost",
  "amount": 100,
  "allocations": [
    {
      "path": "$.totals.shipping",
      "amount": 100
    }
  ]
}

Prorata Item Discount

{
  "title": "10€ prorata discount for coupon",
  "target": "item",
  "method": "across",
  "amount": 100,
  "code": "$.promotions.codes[1]",
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 60
    },
    {
      "path": "$.line_items[1]",
      "amount": 40
    }
  ]
}

Per Item Discount

{
  "title": "10€ per item discount",
  "target": "item",
  "method": "each",
  "amount": 200,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 100
    },
    {
      "path": "$.line_items[1]",
      "amount": 100
    }
  ]
}

Per Item in Bundle

{
  "title": "10€ per item in bundle discount",
  "target": "bundle",
  "method": "each",
  "amount": 200,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 100
    },
    {
      "path": "$.line_items[1]",
      "amount": 100
    }
  ]
}

Bundle Prorata

{
  "title": "10€ bundle prorata discount",
  "target": "bundle",
  "method": "across",
  "amount": 100,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 60
    },
    {
      "path": "$.line_items[1]",
      "amount": 40
    }
  ]
}

Bundle One Item

{
  "title": "10€ bundle one item discount",
  "target": "bundle",
  "method": "one",
  "amount": 100,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 100
    },
    {
      "path": "$.line_items[1]",
      "amount": 0
    }
  ]
}

Free Item

Details of an item added to the cart for free.

title Required	string	Human-readable description.
path Required	string	JSONPath to the line item representing the free goods.
quantity Required	integer	The quantity of items added.
amount Required	integer	Total monetary value of free items in minor currency units.
code	string	JSONPath reference to the triggering code.

Example

{
  "title": "Free item with referral",
  "code": "$.promotions.codes[2]",
  "path": "$.line_items[5]",
  "quantity": 4,
  "amount": 200
}

Promotion Code

A code applied to the session (coupon, referral, etc.).

type Required	enum	The type of the promotion code. coupon referral giftcard
code Required	string	The actual code applied.

Examples

Coupon

{
  "type": "coupon",
  "code": "SUMMER_SALE_20"
}

Referral

{
  "type": "referral",
  "code": "REF-JOHN-DOE-88"
}

Gift Card

{
  "type": "giftcard",
  "code": "GC-X892-LKA1-9922"
}

Allocation

Breakdown of how a discount was allocated to specific items or costs.

path Required	string	JSONPath to the allocation target (e.g., `$.line_items[0]`).
amount Required	integer	Amount allocated to this target in minor currency units.

Examples

Item Allocation

{
  "path": "$.line_items[0]",
  "amount": 100
}

Shipping Allocation

{
  "path": "$.totals.shipping",
  "amount": 100
}