{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uip.dev/schemas/ucp/shopping/promotions.json",
  "name": "dev.uip.shopping.promotions",
  "version": "2026-01-28",
  "title": "Promotions Extension Response",
  "description": "Extends Checkout with Promotions support, detailing applied coupons, referrals, discounts, and free items.",
  "$defs": {
    "allocation": {
      "type": "object",
      "description": "Breakdown of how a discount is allocated to specific items or costs.",
      "required": [
        "path",
        "amount"
      ],
      "properties": {
        "path": {
          "type": "string",
          "description": "JSONPath to the allocation target (e.g., '$.line_items[0]' or '$.totals.shipping')."
        },
        "amount": {
          "type": "integer",
          "minimum": 0,
          "description": "Amount allocated to this target in minor currency units."
        }
      },
      "examples": [
        {
          "path": "$.line_items[0]",
          "amount": 100
        },
        {
          "path": "$.totals.shipping",
          "amount": 100
        }
      ]
    },
    "promotion_code": {
      "type": "object",
      "description": "A code applied to the session (coupon, referral, etc.).",
      "required": [
        "type",
        "code"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "coupon",
            "referral",
            "giftcard"
          ],
          "description": "The type of the promotion code."
        },
        "code": {
          "type": "string",
          "description": "The actual code applied."
        }
      },
      "examples": [
        {
          "type": "coupon",
          "code": "SUMMER_SALE_20"
        },
        {
          "type": "referral",
          "code": "REF-JOHN-DOE-88"
        },
        {
          "type": "giftcard",
          "code": "GC-X892-LKA1-9922"
        }
      ]
    },
    "discount": {
      "type": "object",
      "description": "Details of a monetary reduction applied to the session.",
      "required": [
        "title",
        "target",
        "amount"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "Human-readable description of the discount."
        },
        "target": {
          "type": "string",
          "enum": [
            "cart",
            "additional_cost",
            "item",
            "bundle"
          ],
          "description": "What the discount is applied to."
        },
        "method": {
          "type": "string",
          "enum": [
            "each",
            "across",
            "one"
          ],
          "description": "How the discount is calculated/distributed for item/bundle targets."
        },
        "amount": {
          "type": "integer",
          "minimum": 0,
          "description": "The total value of the discount in minor currency units."
        },
        "code": {
          "type": "string",
          "description": "JSONPath reference to the specific code triggering this discount (e.g., '$.promotions.codes[1]')."
        },
        "allocations": {
          "type": "array",
          "items": {
            "$ref": "https://uip.dev/schemas/ucp/shopping/promotions.json#/$defs/allocation"
          },
          "description": "Breakdown of where this discount was applied."
        }
      },
      "examples": [
        {
          "title": "10€ session discount",
          "target": "cart",
          "amount": 100
        },
        {
          "title": "10€ session shipping cost discount",
          "target": "additional_cost",
          "amount": 100,
          "allocations": [
            {
              "path": "$.totals.shipping",
              "amount": 100
            }
          ]
        },
        {
          "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
            }
          ]
        },
        {
          "title": "10€ per item discount",
          "target": "item",
          "method": "each",
          "amount": 200,
          "allocations": [
            {
              "path": "$.line_items[0]",
              "amount": 100
            },
            {
              "path": "$.line_items[1]",
              "amount": 100
            }
          ]
        },
        {
          "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
            }
          ]
        },
        {
          "title": "10€ bundle prorata discount",
          "target": "bundle",
          "method": "across",
          "amount": 100,
          "allocations": [
            {
              "path": "$.line_items[0]",
              "amount": 60
            },
            {
              "path": "$.line_items[1]",
              "amount": 40
            }
          ]
        },
        {
          "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": {
      "type": "object",
      "description": "Details of an item added to the cart for free.",
      "required": [
        "title",
        "path",
        "quantity",
        "amount"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "Human-readable description of the free item reward."
        },
        "code": {
          "type": "string",
          "description": "JSONPath reference to the specific code triggering this reward."
        },
        "path": {
          "type": "string",
          "description": "JSONPath to the line item representing the free goods."
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "description": "The quantity of items added."
        },
        "amount": {
          "type": "integer",
          "minimum": 0,
          "description": "The total monetary value of the free items in minor currency units."
        }
      },
      "examples": [
        {
          "title": "Free item with referral",
          "code": "$.promotions.codes[2]",
          "path": "$.line_items[5]",
          "quantity": 4,
          "amount": 200
        }
      ]
    },
    "promotions_object": {
      "type": "object",
      "description": "Container for all promotion-related data.",
      "properties": {
        "codes": {
          "type": "array",
          "items": {
            "$ref": "https://uip.dev/schemas/ucp/shopping/promotions.json#/$defs/promotion_code"
          },
          "description": "List of active codes on the session."
        },
        "discounts": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "https://uip.dev/schemas/ucp/shopping/promotions.json#/$defs/discount"
          },
          "description": "List of monetary discounts applied."
        },
        "free_items": {
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "https://uip.dev/schemas/ucp/shopping/promotions.json#/$defs/free_item"
          },
          "description": "List of free items added to the session."
        }
      }
    },
    "checkout": {
      "title": "Checkout with Promotions Response",
      "description": "Checkout extended with promotions capability.",
      "allOf": [
        {
          "$ref": "https://ucp.dev/schemas/shopping/checkout.json"
        },
        {
          "type": "object",
          "properties": {
            "promotions": {
              "$ref": "https://uip.dev/schemas/ucp/shopping/promotions.json#/$defs/promotions_object"
            }
          }
        }
      ]
    }
  }
}