feat: eligibility claims & verification contract (Universal-Commerce-Protocol#250)

* feat: eligibility claims & verification contract

  Introduce `context.eligibility` — buyer claims about eligible benefits
  (loyalty membership, payment instrument perks, etc.) that Businesses
  can act on across the shopping lifecycle.

  Processing model:
  - Platform provides claims via context.eligibility on any request
  - Business MAY act on recognized claims (adjust pricing, product
    access, provisional discounts); MUST ignore unrecognized claims
  - At checkout completion, all claims that influenced the checkout
    MUST be resolved: verified against proof, or rescinded by Platform
  - Unresolved claims block completion (invalid_eligibility error)
  - Business MUST NOT mutate checkout on verification failure

  Layering:
  - context.json: eligibility array with reverse-domain $ref validation
  - checkout.md: normative verification contract (core obligation)
  - discount.json: provisional + eligibility fields on applied_discount
    for structured attribution when discount extension is active
  - catalog/index.md: MAY adjust price/list_price for eligible claims
  - error_code.json: invalid_eligibility standard error

  Key design decision: eligibility lives on context (not PaymentInstrument)
  enabling full-funnel coverage from catalog through checkout. Verification
  is a core checkout concern; the discount extension adds attribution.

* align error code to noun_adjective pattern

* fix: address PR Universal-Commerce-Protocol#250 review feedback

  Terminology:
  - "claims that influenced the checkout" → "accepted claims" throughout,
    aligning with the accepted/not-accepted partition (maximenajim, ACSchil)
  - "not applied" → "not accepted" for consistency

  Verification semantics:
  - Clarify that verification failure MUST only affect the messages array,
    not checkout state (line items, totals, discounts, etc.) (maximenajim)
  - Add path field to eligibility_invalid example for machine-readable
    partial failure identification (ACSchil)

  Messages contract:
  - Add MAY use type: "info" to explain effects of accepted claims,
    complementing SHOULD warn on rejection (maximenajim)

  Catalog:
  - Add non-binding pricing contract to "Relationship to Checkout" section:
    catalog responses are not transactional commitments, checkout is
    authoritative, responses SHOULD NOT be reused across sessions
    without re-validation (maximenajim)

* add eligibility message codes for warning and info

  Standardize codes for the three eligibility message types:
  eligibility_not_accepted (warning), eligibility_accepted (info),
  and eligibility_invalid (error at completion).

* remove display MUST from provisional

  Per TC discussion, this is already captured via messages flow.

---------

Co-authored-by: Alex Schillinger <alexcschillinger@gmail.com>

Author: igrigorik

docs/specification/catalog/index.md

@@ -48,6 +48,11 @@ Catalog operations return product and variant IDs that can be used directly in
 checkout `line_items[].item.id`. The variant ID from catalog retrieval should match
 the item ID expected by checkout.
 
+Catalog responses (pricing, availability, etc.) reflect the Business's current
+terms for the given request but are not transactional commitments — checkout
+is authoritative. Responses can be session-specific and **SHOULD NOT** be
+reused across sessions without re-validation.
+
 ## Shared Entities
 
 ### Context
@@ -69,6 +74,11 @@ the presentment currency differs, businesses SHOULD convert before applying
 (see [Price Filter](search.md#price-filter)). Response prices include
 explicit currency codes confirming the resolution.
 
+When `context.eligibility` claims are present, Businesses that accept them
+**MAY** adjust `price` / `list_price` directly for strikethrough display and
+**MAY** use `messages` with `code: "eligibility_benefit"` to attribute the
+adjustment to a specific claim.
+
 {{ schema_fields('types/context', 'catalog') }}
 
 ### Signals

docs/specification/checkout.md

@@ -240,6 +240,7 @@ handle with specific, appropriate UX rather than generic error treatment.
 | `item_unavailable`       | Item cannot be purchased (e.g. delisted)                                   |
 | `address_undeliverable`  | Cannot deliver to the provided address                                     |
 | `payment_failed`         | Payment processing failed                                                  |
+| `eligibility_invalid`    | Eligibility claim could not be verified at completion                      |
 
 Businesses **SHOULD** mark standard errors with `severity: recoverable` to
 signal that platforms should provide appropriate UX (out-of-stock messaging,
@@ -249,6 +250,82 @@ messages or deferring to checkout completion.
 Example: `out_of_stock` requires specific upfront UX, whereas
 `payment_required` can be handled generically at submission.
 
+#### Eligibility Verification at Completion
+
+Platforms provide `context.eligibility` — buyer claims about eligible benefits
+such as loyalty membership, payment instrument perks, and similar. These are
+claims, not verified facts. Businesses **MAY** act on recognized claims during
+the session (adjusting pricing, granting product access, applying provisional
+discounts), but all accepted claims **MUST** be resolved before the
+transaction can complete.
+
+Unrecognized or inapplicable claims **MUST NOT** block the checkout.
+Businesses **SHOULD** notify the buyer via `messages` with `type: "warning"`
+when a claim is not accepted, and **MAY** use `type: "info"` to explain
+the effects of accepted claims. At completion, accepted claims that remain
+unverified **MUST** result in `type: "error"` with
+`code: "eligibility_invalid"` (see below).
+
+**Eligibility message codes:**
+
+| Type      | Code                       | When                                               |
+| --------- | -------------------------- | -------------------------------------------------- |
+| `warning` | `eligibility_not_accepted` | Claim not recognized or not applicable             |
+| `info`    | `eligibility_accepted`     | Effect of an accepted claim                        |
+| `error`   | `eligibility_invalid`      | Accepted claim could not be verified at completion |
+
+A claim is resolved when it is either **verified** or **rescinded**:
+
+* **Verified**: The Business confirms the claim against a proof provided at
+  completion time. UCP does not prescribe how verification occurs — proof
+  may come from the payment credential, an identity verification capability,
+  or any other mechanism negotiated between Platform and Business.
+* **Rescinded**: The Platform removes the claim from `context.eligibility`
+  before completion (e.g., buyer changes payment method, withdraws a
+  membership claim). Once removed, the Business recalculates without it.
+
+Businesses **MUST NOT** complete a transaction with unresolved eligibility
+claims. Unverified claims may result in incorrect pricing or unauthorized
+access to restricted products.
+
+**When verification fails:**
+
+Verification failure **MUST** only affect the `messages` array. The
+Business **MUST** return an error in `messages` with
+`code: "eligibility_invalid"` and `severity: "recoverable"`. Messages
+**SHOULD** use the `path` field to identify which specific claim(s) could
+not be verified. The Platform **MAY** then provide valid proof and
+resubmit, restructure the checkout (e.g., remove ineligible items, update
+claims), or abandon the attempt.
+
+For example, the Platform claims a store card benefit via
+`context.eligibility`. The Business applies member pricing during the session.
+At completion, the payment credential does not match the claimed instrument:
+
+```json
+{
+  "ucp": { "version": "2026-01-11", "status": "success" },
+  "id": "checkout_abc",
+  "status": "ready_for_complete",
+  "line_items": [ "..." ],
+  "totals": [ "..." ],
+  "messages": [
+    {
+      "type": "error",
+      "code": "eligibility_invalid",
+      "severity": "recoverable",
+      "content": "Payment credential does not match the claimed store card benefit.",
+      "path": "$.context.eligibility[0]"
+    }
+  ]
+}
+```
+
+The Platform can resolve this by having the buyer switch to the qualifying
+payment instrument, or by removing the claim from `context.eligibility` to
+renegotiate the checkout (obtaining updated pricing, availability, etc.)
+and then resubmitting for completion.
+
 ## Continue URL
 
 The `continue_url` field enables checkout handoff from platform to business UI,

docs/specification/discount.md

@@ -188,6 +188,101 @@ segment, or promotional rules:
 - Cannot be removed by the platform
 - Surfaced for transparency (platform can explain to user why discount was applied)
 
+## Eligibility Claims
+
+Eligibility claims are buyer claims about eligible benefits (see
+[Context](checkout.md#context)) such as loyalty membership, payment instrument
+perks, and similar. When the discount extension is active, Businesses that
+choose to accept eligibility claims **MUST** surface their effect on pricing
+as provisional discounts in the `applied` array. Platforms **MUST** display
+provisional discounts to the buyer.
+
+### Discount Behavior
+
+Platforms send buyer claims via `context.eligibility` on cart or checkout
+requests (see [Context](checkout.md#context)). When a Business recognizes a
+claim and it affects pricing, it **MUST** surface a corresponding provisional
+discount in the `discounts.applied` array. This gives the Platform structured
+attribution to display to the buyer.
+
+Eligibility-triggered discounts use the following fields:
+
+| Field         | Value                      | Purpose                                 |
+| ------------- | -------------------------- | --------------------------------------- |
+| `automatic`   | `true`                     | No code required                        |
+| `provisional` | `true`                     | Requires verification at completion     |
+| `eligibility` | `"com.example.store_card"` | The accepted claim                      |
+| `code`        | *(omitted)*                | Not code-based                          |
+
+Standard `priority`, `method`, and `allocations` fields apply for stacking with
+other discounts.
+
+### Verification at Checkout
+
+Discounts from accepted but unverified claims carry `provisional: true`.
+Provisional discounts remain until the claim is verified, rescinded, or
+replaced during the session. At checkout completion, all remaining provisional
+claims **MUST** be resolved (see
+[Eligibility Verification at Completion](checkout.md#eligibility-verification-at-completion)).
+
+### Example: Provisional Discount with Attribution
+
+Building on the store card example from
+[Eligibility Verification at Completion](checkout.md#eligibility-verification-at-completion),
+the discount extension provides structured attribution. The Platform claims a
+store card benefit; the Business surfaces the provisional discount with full
+stacking and allocation details:
+
+=== "Request"
+
+    ```json
+    {
+      "context": {
+        "eligibility": ["com.example.store_card"]
+      },
+      "line_items": [
+        {
+          "item": {
+            "id": "prod_shirt",
+            "quantity": 2,
+            "price": 2500
+          }
+        }
+      ]
+    }
+    ```
+
+=== "Response"
+
+    ```json
+    {
+      "discounts": {
+        "applied": [
+          {
+            "title": "Store Card 5% Off",
+            "amount": 250,
+            "automatic": true,
+            "provisional": true,
+            "eligibility": "com.example.store_card",
+            "priority": 1,
+            "method": "each",
+            "allocations": [
+              {"path": "$.line_items[0]", "amount": 250}
+            ]
+          }
+        ]
+      },
+      "totals": [
+        {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
+        {"type": "items_discount", "display_text": "Discounts", "amount": 250},
+        {"type": "total", "display_text": "Total", "amount": 4750}
+      ]
+    }
+    ```
+
+The Platform can now render: "Store Card 5% Off: -$2.50 *(verified at
+purchase)*" with full confidence in the attribution, amount, and allocation.
+
 ## Impact on Line Items and Totals
 
 Applied discounts are reflected in the core cart or checkout fields using two

source/schemas/shopping/discount.json

@@ -3,7 +3,7 @@
   "$id": "https://ucp.dev/schemas/shopping/discount.json",
   "name": "dev.ucp.shopping.discount",
   "title": "Discount Extension",
-  "description": "Extends Cart and Checkout with discount code support, enabling agents to apply promotional, loyalty, referral, and other discount codes.",
+  "description": "Extends Cart and Checkout with discount support, including discount codes, automatic discounts, and eligibility-triggered provisional discounts.",
   "$defs": {
     "allocation": {
       "type": "object",
@@ -61,6 +61,15 @@
           "minimum": 1,
           "description": "Stacking order for discount calculation. Lower numbers applied first (1 = first)."
         },
+        "provisional": {
+          "type": "boolean",
+          "default": false,
+          "description": "True if this discount requires additional verification."
+        },
+        "eligibility": {
+          "$ref": "types/reverse_domain_name.json",
+          "description": "The eligibility claim accepted by the Business for this discount. Corresponds to a value from context.eligibility. Omitted for code-based and non-eligibility automatic discounts."
+        },
         "allocations": {
           "type": "array",
           "items": {

source/schemas/shopping/types/context.json

@@ -29,6 +29,14 @@
     "currency": {
       "type": "string",
       "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD'). Businesses determine presentment currency from context and authoritative signals; this hint MAY inform selection in multi-currency markets. Also serves as the denomination for price filter values — platforms SHOULD include this field when sending price filters. Response prices include explicit currency confirming the resolution."
+    },
+    "eligibility": {
+      "type": "array",
+      "description": "Buyer claims about eligible benefits such as loyalty membership, payment instrument perks, and similar. Recognized claims MAY inform the Business response (e.g., member-only product availability, adjusted pricing in catalog, provisional discounts at cart or checkout). Businesses MUST ignore unrecognized values without error. Values MUST use reverse-domain naming (e.g., 'com.example.loyalty_gold', 'org.school.student') and MUST be non-identifying.",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "reverse_domain_name.json"
+      }
     }
   }
 }

source/schemas/shopping/types/error_code.json

@@ -8,6 +8,7 @@
     "out_of_stock",
     "item_unavailable",
     "address_undeliverable",
-    "payment_failed"
+    "payment_failed",
+    "eligibility_invalid"
   ]
 }