Discount Extension

Basic Information

Capability Name: dev.ucp.shopping.discount
Version: 2026-01-11
Official Specification: discount.md

Overview

The Discount extension allows businesses to indicate support for discount codes on checkout sessions.

Key features:

Submit one or more discount codes
Receive applied discounts with human-readable titles and amounts
Rejected codes communicated via messages[] with detailed error codes
Automatic discounts surfaced alongside code-based discounts

Dependencies:

Checkout Capability

Discovery

Businesses advertise discount support in their profile:

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.discount",
        "version": "2026-01-11",
        "extends": "dev.ucp.shopping.checkout",
        "spec": "https://ucp.dev/specification/discount",
        "schema": "https://ucp.dev/schemas/shopping/discount.json"
      }
    ]
  }
}

Allocation Details

The applied array explains how discounts were calculated and distributed.

Method	Meaning	Example
`each`	Applied independently per eligible item	“10% off each item” → 10% × item price
`across`	Split proportionally by value	“$10 off order” → $6 to $60 item, $4 to $40 item

Stacking Order

When multiple discounts are applied, priority indicates the calculation order. Lower numbers are applied first:

Cart: $100
Discount A (priority: 1): 20% off → $100 × 0.8 = $80
Discount B (priority: 2): $10 off → $80 - $10 = $70

Operations

Discount codes are submitted via standard checkout create/update operations.

Request behavior:

Replacement semantics: Submitting discounts.codes replaces any previously submitted codes
Clear codes: Send empty array "codes": [] to remove all discount codes
Case-insensitive: Codes are matched case-insensitively

Response behavior:

discounts.applied contains all active discounts (code-based + automatic)
Rejected codes communicated via messages[]

Rejected Codes

When a submitted discount code cannot be applied, businesses communicate this via the messages[] array:

{
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[0]",
      "content": "Code 'SUMMER20' expired on December 1st"
    }
  ]
}

Error codes for rejected discounts:

Code	Description
`discount_code_expired`	Code has expired
`discount_code_invalid`	Code not found or malformed
`discount_code_already_applied`	Code is already applied
`discount_code_combination_disallowed`	Cannot combine with another active discount
`discount_code_user_not_logged_in`	Code requires authenticated user
`discount_code_user_ineligible`	User does not meet eligibility criteria

Automatic Discounts

Businesses may apply discounts automatically based on cart contents, customer segment, or promotional rules:

Appear in discounts.applied with automatic: true and no code field
Applied without platform action
Cannot be removed by the platform

Examples

Order-level discount

Request:

{
  "discounts": {
    "codes": ["SAVE10"]
  }
}

Response:

{
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "amount": 5000},
    {"type": "discount", "amount": 1000},
    {"type": "total", "amount": 4000}
  ]
}