Proposal: a state-bound Offer primitive for merchant-proposed cart changes

[arjun2075]

Following up on #694, I wanted to narrow one of the questions there into something more concrete.

The specific gap I'm thinking about is cross-sell / upsell in an agent flow.

UCP already has structured cart state and buyer-initiated cart updates. What seems to be missing is the other side of that interaction:

the business is proposing this specific change to the buyer's current cart

Today, if a merchant suggests an additional product and the buyer agent adds it, the resulting cart tells us what is there now, but not necessarily why that change happened.

These can end up looking very similar:

• the buyer explicitly asked for another item
• the agent independently decided to add something
• the merchant proposed an upsell and the agent applied it

For a normal human checkout, that distinction may not matter much.

For an agent that can spend on someone's behalf, I think it starts to matter.

The idea

My current mental model is that an Offer isn't another product type and isn't another pricing authority.

It's a merchant-proposed transition from one commerce state to another.

Something like:

current cart state
      ↓
 merchant Offer
      ↓
proposed cart change
      ↓
 agent evaluates it
      ↓
Offer is applied
      ↓
business returns authoritative cart state

The important part is that the proposed change is structured.

An agent shouldn't have to read:

"Complete your setup! Add our travel charger for only $20."

and infer what transaction the merchant is asking it to make.

The Offer should say that explicitly.

Rough shape

The field names here are illustrative — I'd expect a real version to reuse existing UCP types and cart-update vocabulary.

{
  "id": "offer_01",
  "revision": "1",

  "applies_to": {
    "cart_id": "cart_123",
    "state_ref": "..."
  },

  "expires_at": "2026-08-10T23:00:00Z",

  "operations": [
    {
      "type": "add",
      "item_id": "charger_65w",
      "quantity": 1
    }
  ],

  "impact": {
    "total_delta": {
      "currency": "USD",
      "amount": "20.00"
    },
    "recurrence": "one_time"
  },

  "presentation": {
    "title": "Add a travel charger",
    "description": "Complete your setup with our compact 65W charger."
  }
}

recurrence there is just illustrating the requirement, not proposing a new recurrence schema. I'd want the actual shape to reuse whatever semantics UCP defines for recurring commerce.

A few design choices in that example matter more to me than the exact field names.

1. Make an Offer revision immutable, and bind it to the state it was evaluated against

There are really two things I think we need to be able to identify later:

Which exact Offer did the agent evaluate?

and:

Which exact commerce state was that Offer generated against?

For the first, I'd treat id + revision as identifying an immutable Offer artifact.

Once offer_01, revision 1 has been issued, its decision-relevant meaning shouldn't change underneath the agent.

If the merchant changes the proposed operation, price impact, recurrence, or other decision-relevant terms, that should be another revision.

Whether id + revision is enough for external evidence to bind to, or whether there should also be a digest over a canonical representation, feels like something worth aligning with the Signals work in #534/#535 rather than defining independently here.

For the source state, if an Offer was generated for a particular cart state and that cart changes before the Offer is applied, I don't think the old Offer should silently apply to the new state.

So the second invariant is:

An Offer describes a transition from a specific source state.

I don't think this proposal needs to invent a new Cart versioning mechanism just for that.

If Cart/Checkout exposes a revision/version, use that. If the appropriate convention is a stable content hash or another state identifier, use that instead.

The important thing is being able to say:

this is the state against which the merchant generated this proposal.

If that state is no longer current, application fails and the merchant can issue a new Offer.

This also gives useful stacking behavior for free

Say the merchant returns three cross-sell Offers, all based on the same cart state.

The agent applies Offer A.

That changes the cart.

Offers B and C are now based on stale state and can't simply be stacked onto the new cart. If the merchant still wants to propose them, it evaluates the new state and reissues them.

I like that property because:

multiple Offers can't silently accumulate against a cart state that no longer exists.

This doesn't answer whether the buyer is authorized to apply $20, then another $20, then another $20. That still looks like an authorization-policy question.

But at the UCP layer, every new proposal is at least evaluated against the actual accumulated commerce state.

2. Keep transaction data separate from presentation text

Anything the buying system is expected to make a purchase decision on should be represented in structured fields.

Human-readable copy is still useful, but I'd treat it as presentation.

For example:

{
  "operations": [
    {
      "type": "add",
      "item_id": "charger_65w",
      "quantity": 1
    }
  ]
}

is decision data.

{
  "description": "Complete your setup!"
}

isn't.

This isn't meant to solve prompt injection generally.

It just means an agent doesn't need merchant-authored natural language to determine what commerce operation is actually being proposed.

3. Reuse Cart update semantics rather than inventing another mutation language

UCP already supports buyer-initiated Cart updates, so I think an Offer should reuse those concepts wherever possible.

In that sense, this is basically the merchant-proposed counterpart to an existing buyer-initiated Cart change.

I'd expect the actual operation vocabulary and field names to align with Cart rather than create a parallel mutation language.

Conceptually:

{
  "operations": [
    {
      "type": "add",
      "item_id": "charger_65w",
      "quantity": 1
    },
    {
      "type": "remove",
      "line_item_id": "li_27"
    },
    {
      "type": "update_quantity",
      "line_item_id": "li_31",
      "quantity": 3
    },
    {
      "type": "replace",
      "line_item_id": "li_42",
      "item_id": "laptop_32gb"
    }
  ]
}

add naturally references a catalog item.

remove, replace, and update_quantity should operate against a Cart line_item_id, since multiple lines can refer to the same catalog item.

I'd also make quantity updates absolute:

set quantity to 3

rather than:

increment quantity by 2

That makes retries much easier to reason about.

I'd prefer a small typed operation set over arbitrary JSON Patch unless there's a strong reason otherwise.

4. Let the agent preview impact, but keep the returned Cart authoritative

The agent needs enough information to decide whether an Offer is worth applying.

That probably includes a structured preview of relevant impact — price delta at minimum, and fulfillment or recurrence effects where applicable.

But I wouldn't make the Offer a second pricing authority.

The Offer says:

if this is still valid and you apply it to this state, this is the change I'm proposing.

The business-returned Cart says:

this is the transaction state now.

That seems consistent with the pattern UCP already uses for discounts: input goes in, applied state comes back, and canonical totals remain on the returned commerce object.

5. Recurrence has to be explicit decision data

This is one place where the discussion in #694 changed my thinking.

I initially thought of recurrence as one useful field among several.

I now think it's more fundamental.

These are not equivalent Offers:

Add accessory: $20 once

and:

Add service: $20/month

even though both might change the immediate transaction by $20.

For an autonomous buyer, recurrence changes what is being authorized.

So I think an Offer that creates a recurring obligation has to expose that fact in its authoritative decision data. It can't be something the agent is expected to infer from description text.

I still wouldn't define an Offer-specific subscription model.

If UCP has or develops general recurring-commerce semantics, the Offer should reuse those.

The requirement here is simply:

a recurring obligation must be structurally visible to the evaluating agent before the Offer is applied.

6. Apply, not accept

I'd lean toward something like apply_offer rather than accept_offer.

That wording is intentional.

Applying an Offer means:

apply this merchant-proposed commerce mutation to the Cart.

It does not necessarily mean:

the principal authorized the eventual transaction.

The request could conceptually look like:

{
  "offers": {
    "apply": [
      {
        "id": "offer_01",
        "revision": "1"
      }
    ]
  }
}

and the business could return:

{
  "offers": {
    "applied": [
      {
        "id": "offer_01",
        "revision": "1",
        "affected_line_item_ids": ["li_27"]
      }
    ]
  }
}

I like this because it follows the existing UCP input/applied-output pattern rather than introducing a completely different interaction style.

The business validates that the Offer:

• exists
• is still the referenced revision
• applies to the evaluated source state
• hasn't expired
• is still commercially valid

and then returns the updated Cart.

7. Keep lightweight provenance after application

I'd keep the applied Offer reference on the resulting commerce state, at least long enough to preserve where the mutation came from.

The reason isn't to create another ledger.

It's just to preserve the distinction between:

the buyer/agent changed the Cart

and:

this part of the state resulted from a merchant proposal.

That seems useful for debugging, auditability, downstream agent reasoning, and an authorization layer evaluating how the transaction arrived at its current state.

Claims and evidence

One thing I would explicitly not put inside this primitive is a new attestation mechanism.

The work in #534/#535 seems like the better place for that.

I like the separation @westonale-facet described in #694:

• merchant assertion: stays with the Offer; no additional trust machinery implied
• something the agent can recompute: the agent verifies it itself — for example, a stated price delta against the commerce state it already has
• third-party evidence: rides the Signals envelope

That keeps the Offer responsible for describing the proposal, without making it responsible for defining the trust model for every claim the merchant might attach to it.

It also makes Offer identity more important: evidence isn't very useful if it can't be tied back to the exact immutable artifact the agent evaluated.

Whether Signals should identify that artifact through id + revision, a canonical digest, or both is something I'd prefer to align with the Signals design rather than solve separately here.

Relationship to AP2

I think this boundary should stay pretty clean.

UCP answers:

What did the merchant propose, and what did applying that proposal do to the commerce state?

AP2 can answer:

Was the agent/principal actually permitted to complete the resulting transaction?

So I don't think an Offer needs its own authorization semantics.

For example, whether an agent may apply accessories below a certain amount — or whether multiple sequential Offers exceed a cumulative limit — feels like an AP2 policy question.

The UCP primitive just needs to make each proposal and resulting state explicit enough for that policy to be evaluated.

That separation is also why I prefer apply over accept.

Relationship to bundles

#448 looks like adjacent but different work.

A bundle describes a merchandising/product construct.

An Offer describes a merchant-proposed transition to a particular buyer's current commerce state.

A bundle can absolutely be the subject of an Offer.

For example:

Current cart:
  laptop
  mouse

Merchant proposal:
  replace those lines with bundle_123

So I'd expect the concepts to compose rather than compete.

Relationship to quotes / time-bound offers

There's also related discussion in #328 around time-bound offers/quotes, holds, and validity windows.

I see that as useful adjacent work rather than the same primitive.

A quote or hold can answer something like:

these commercial terms are valid for the next N minutes.

The gap I'm trying to address here is:

given the buyer's current commerce state, what specific mutation is the merchant proposing?

Those concepts can compose too. A state-bound Offer may expire or reference time-bound commercial terms.

I wouldn't try to redefine quote/hold semantics here.

Failure cases

A few failures seem useful to distinguish:

offer_expired
offer_revision_mismatch
offer_source_state_mismatch
offer_no_longer_applicable
offer_conflict

The behavior I care about is:

Don't silently reinterpret or mutate an Offer the agent already evaluated.

If the proposal materially changes, issue another revision and let the agent evaluate it again.

Where Offers surface

I'm deliberately leaving transport/discovery out of this first proposal.

Offers could eventually surface inside Cart/Checkout responses, through a capability endpoint, or somewhere else.

I'd rather take guidance from existing UCP capability conventions once there's agreement on whether the semantic primitive itself is useful.

Things I'd leave out initially

I wouldn't try to solve all of the questions from #694 here.

In particular:

• defining a new attestation/trust mechanism
• cumulative AP2 authorization policy
• buyer-agent solicitation
• disclosure policy for buyer constraints
• offer-specific signing
• a new recurrence/subscription model
• cross-business Offer composition
• multi-checkout authorization

For evidence, I'd compose with Signals.

For pricing, fulfillment, recurrence, and similar commerce concepts, I'd reuse existing or future general UCP primitives rather than define Offer-specific versions.

And cross-business planning / authorization feels like a separate problem above an individual merchant Cart.

Why introduce a primitive at all?

The invariants I care about are:

A buying system should be able to determine the complete commerce mutation being proposed without interpreting merchant presentation text.

The Offer revision the agent evaluates should have stable, immutable meaning.

A merchant proposal should be bound to the commerce state it was evaluated against, rather than silently applying to a different state later.

Any recurring obligation created by the proposal should be explicit before the agent applies it.

And after application:

It should remain possible to distinguish a merchant-proposed mutation from an independently buyer-originated Cart change.

If those invariants are useful at the protocol layer, then I think there's a case for a small primitive here.

If they aren't, this probably belongs higher in the implementation stack.

If the direction makes sense, I'm happy to put together a small namespaced schema next using the actual UCP Cart types and conventions.

Beyond #328, #448, and the Signals work in #534/#535, pointers to related prior discussions or primitives I've missed are very welcome.

[westonale]

Answering the question you carried over from #694, since you left it open here deliberately: a digest, and not as a belt-and-braces addition to id plus revision. The two identify different things.

id plus revision is a label the merchant assigns. It identifies the offer inside the merchant's own namespace and it is exactly as trustworthy as the merchant is. That is fine for the merchant's own bookkeeping, and it is fine for a claim the merchant makes about its own offer, because there the issuer and the labeller are the same party. It stops being fine the moment a third party attests to something about that artifact, because now the verifier has to take the merchant's word that revision 1 today is the revision 1 the attestation was made against. Nothing in the label prevents a merchant from reissuing revision 1 with different terms, and nothing lets an agent detect it afterwards.

A digest over a canonical serialization of the decision-relevant fields removes the merchant from that step. The agent holds an offer, computes the digest itself, and compares it to the one inside the signed envelope. If they match, the artifact in hand is the artifact attested, and nobody has to be trusted for that comparison. If the merchant reissues, the digest changes and the old attestation stops matching, which is the behaviour you want rather than a failure mode.

Keep both. id plus revision is the operational handle, the thing that appears in a log, a support ticket and a reconciliation report. The digest is what evidence binds to. Different readers, different jobs.

Two notes on making a digest actually work, because this is where it usually goes wrong in practice.

Canonicalization has to be specified rather than assumed. If two honest implementations serialize the same offer differently, they compute different digests, every attestation fails to match, and the mechanism degrades into noise that implementers learn to ignore. Whatever gets picked matters less than it being pinned in the text.

And the digest should cover exactly the decision-relevant fields you already named (operations, impact, recurrence, the source state reference) and deliberately exclude presentation. If presentation copy is inside the digest, a merchant fixing a typo in a description invalidates every outstanding attestation against that offer, and you have coupled trust machinery to marketing edits for no benefit. Your instinct to separate transaction data from presentation text already draws that line in the right place; this is the same line, load bearing for a second reason.

For what it is worth, I think your source-state invariant is the more important of the two ideas here. Immutability makes an offer identifiable. Binding it to the state it was generated against is what stops three stale offers silently stacking onto a cart that has already moved, and that is the property that actually protects an autonomous buyer. The stacking behaviour you get for free from it is the strongest argument in the proposal.

One thing I would push on. expires_at is doing quiet double duty. If an offer is bound to a source state, then a state change already invalidates it, and expiry is a second, weaker invalidation on a different axis. Worth being explicit about which one is authoritative when they disagree, because an offer that is still inside its expiry window but was generated against a stale cart is the exact case an implementer will get wrong.

[arjun2075]

Thanks — this is very helpful, and I think we’re aligned on the model.

I agree that id + revision and the digest are doing different jobs:

• id + revision stays as the operational/merchant-facing handle.
• Evidence binds to a digest over the canonical representation of the decision-relevant offer fields.

I’ll tighten the proposal so canonicalization is normative rather than implied, and so the digest coverage is explicit. My current intent is for it to cover the transaction-relevant fields such as operations, impact, recurrence, and the source-state reference, while deliberately excluding presentation.

I also agree that the source-state invariant is the key validity property. On the expires_at point, I think the right rule is that source-state validity and expiry are independent and conjunctive rather than one taking precedence over the other.

In other words, an offer is applicable only if:

1. it still refers to the current source state, and
2. it has not expired.

So if the cart has changed, the offer is invalid even if expires_at is still in the future. Conversely, an offer generated against the current state is still invalid once it has expired.

I’ll make that explicit in the text and add the stale-but-unexpired case as an example/test case, since I agree that’s exactly where implementations could otherwise diverge.

I’m planning to update the proposal with:

• normative canonicalization rules;
• explicit digest coverage/exclusions;
• the separation between operational identity (id + revision) and evidence identity (digest);
• an explicit source-state validity invariant;
• conjunctive source-state + expiry semantics;
• examples covering stale offers, including multiple offers generated from the same prior cart state.

If that matches what you had in mind, I think the remaining design question is mostly the concrete canonicalization mechanism rather than the validity model itself.

[arjun2075]

Following up on the last part of the proposal, here’s the smallest v0 shape I get after mapping this onto the current Cart model and incorporating the feedback above.

There are two changes from the illustrative shape in the original post that I think are worth making immediately.

First, I would drop the Offer-specific add / remove / update_quantity / replace vocabulary for v0. Current Cart update semantics already treat line_items as full replacement, so the Offer can describe the proposed target line-item state using the same Cart/Line Item concepts rather than creating a second mutation language.

Second, I would keep the source-state identifier opaque to this extension. I found #113 while mapping this onto the current schemas; that looks directly adjacent to the source-state problem here. I don’t think Offer should independently invent a second Cart revision/version mechanism. It just needs a stable reference to the exact Cart state the proposal was generated against.

So, conceptually, I’m thinking of a capability along these lines:

dev.ucp.shopping.offer
  extends dev.ucp.shopping.cart

with a Cart response surface roughly like:

{
  "offers": {
    "available": [
      {
        "id": "offer_01",
        "revision": "1",

        "applies_to": {
          "cart_id": "cart_123",
          "state_ref": "..."
        },

        "expires_at": "2026-08-10T23:00:00Z",

        "proposed_update": {
          "line_items": [
            "... same line-item concepts as an Update Cart request ..."
          ]
        },

        "impact": {
          "total_delta": 2000
        },

        "recurrence": {
          "...": "shared UCP recurring-commerce semantics"
        },

        "presentation": {
          "title": "Add a travel charger",
          "description": "Complete your setup with our compact 65W charger."
        }
      }
    ],

    "applied": [
      {
        "id": "offer_00",
        "revision": "2",
        "affected_line_item_ids": ["li_27"]
      }
    ]
  }
}

A few details in that sketch are intentional:

• proposed_update.line_items is the transaction proposal. For this initial use case I would keep the mutation surface narrow and reuse Cart line-item semantics rather than define generic patch operations.
• impact.total_delta is a signed amount in the parent Cart currency, in UCP minor units. It is a preview for agent evaluation; the Cart returned after application remains authoritative.
• recurrence is structurally part of the decision data, but I’m deliberately not proposing an Offer-specific recurrence model. It should reference whatever shared recurring-commerce semantics UCP adopts.
• presentation is non-authoritative display copy.
• applied preserves lightweight provenance after the mutation without turning Offers into a separate ledger.

Validity

Following the point above about expires_at, I think applicability should be explicitly conjunctive:

applicable =
    source_state_matches
    AND not_expired
    AND commercially_valid

No condition overrides another.

In particular:

source state stale + offer unexpired = invalid
source state current + offer expired = invalid

So applying Offer A to state S0 and receiving state S1 automatically makes other Offers bound to S0 inapplicable, even if their expiry windows are still open.

Application

One thing I don’t want to paper over in the schema: current update_cart requires line_items, so I’m not sure we should force an offers.apply control into the existing Cart update request and make the Platform echo both the Cart and the Offer handle.

The cleaner operation may be conceptually:

apply_offer(
    cart_id,
    offer_id,
    revision
)

The Business would validate the referenced Offer against the current Cart state, expiry, and current commercial validity, apply the stored proposal, and return the new authoritative Cart.

I’d like guidance on whether there is an existing UCP extension/operation convention that should be reused for that before pinning the transport shape.

Evidence binding

I also agree with @westonale-facet’s distinction above:

id + revision = operational identity
digest        = evidence identity

I don’t think the Offer itself necessarily needs to carry its own digest. An agent can derive the digest and third-party evidence in Signals can bind to it.

For a concrete starting point, I would define the digest subject as the canonical serialization of the decision/validity-relevant fields:

applies_to
proposed_update
impact
recurrence
expires_at

and explicitly exclude:

presentation

I included expires_at in that subject because changing the validity window changes the artifact an agent is evaluating; otherwise the same evidence digest could continue to match after the merchant changed the expiry.

For canonicalization, RFC 8785/JCS + SHA-256 seems like the obvious starting point given the Signals discussion in #534/#535, but I’d rather align with whatever that work standardizes than create an Offer-specific convention.

So the two things I’d most like feedback on before turning this into an actual JSON Schema/PR are:

1. Is a target line_items state the right way to reuse current Cart update semantics, or is there a better existing UCP representation for the proposed mutation?
2. What should state_ref bind to — especially in light of [Spec] Concurrent checkout updates can cause silent data loss - need ETag/If-Match support #113 — so Offer uses the general Cart/Checkout state-identity mechanism rather than inventing its own?

[westonale]

This tightened up well, the conjunctive validity rule and the digest coverage are exactly right, and the stale-but-unexpired example is the one implementations would actually diverge on without it written down. Taking your two open questions in order.

On line_items: yes, reuse Cart's semantics, don't invent a second mutation language. Same reasoning you gave for not inventing a second revision mechanism applies here too, every parallel vocabulary is something two implementations can drift on independently.

On state_ref: keep it opaque and platform assigned for v0. I went looking for the general Cart/Checkout state identity mechanism you'd want to bind to, and it doesn't exist yet. #113 proposed exactly that, an ETag/If-Match revision field, and it was shelved as future roadmap and never shipped. So there's nothing live to point at today, and I don't think Offer should be the one to invent it either, for the same reason you don't want to invent a second mutation language. If a third extension shows up needing the same primitive, that's the signal to revive #113 as something shared rather than something each extension quietly reinvents on its own.

On the transport shape for applying an offer: I checked how this is handled elsewhere in the spec before answering, since I didn't want to guess at precedent. Discounts are the closest existing case, and they go through the standard cart or checkout update request, discounts.codes is just a field that replaces on submission. That's the established convention, but I don't think it maps cleanly onto Offer, and you already named the reason: update_cart requires line_items, so folding offers.apply into it would force the platform to echo back the exact line_items your server already computed for that offer. Discounts avoid that because a code is just a string, there's nothing precomputed to echo. Offer's whole value is that the server already worked out the resulting state, so a request shape that makes the client resubmit it duplicates data that can drift from what the server actually applies. A narrow apply_offer(cart_id, offer_id, revision) sidesteps that cleanly, the server already has the proposal stored against that id and revision, the client is only referencing it. I'd go with your instinct here over the discount precedent, and say explicitly in the writeup why it diverges, so the next reader doesn't wonder why Offer doesn't follow the pattern that's already in the spec.

[arjun2075]

Thanks — this resolves the remaining questions for me.

I’ll take the v0 shape forward with:

proposed_update.line_items using the existing Cart replacement semantics
opaque, implementation-assigned state_ref
a dedicated apply_offer(cart_id, offer_id, revision) operation rather than routing application through update_cart

I’ll also call out explicitly why Offer diverges from the discount precedent: the client is referencing a server-computed proposal, so requiring it to resubmit the resulting line_items would duplicate authoritative state and create an opportunity for drift.

One transport detail I’ll make explicit in the PR is retry/idempotency behavior for apply_offer, so a lost response + retry can’t accidentally double-apply an offer or turn a successful application into an ambiguous stale-state failure.

I agree on leaving the general state identity mechanism out of scope for now. If another extension ends up needing the same primitive, that seems like the right point to revisit #113 as shared infrastructure rather than solving it inside Offer.

I’ll turn this into the schema/transport/docs shape next.

[arjun2075]

Following up on the v0 shape above, I started by turning the agreed semantics into the smallest executable slice before pinning the transport shape:

https://github.com/arjun2075/ucp-offer-v0

Release: https://github.com/arjun2075/ucp-offer-v0/releases/tag/v0.1.0

The prototype includes an experimental JSON Schema, a small reference apply_offer implementation, and executable conformance vectors covering the invariants we discussed:

• target line_items reuse Cart full-replacement semantics rather than introducing another mutation language;
• state_ref remains opaque and binds the Offer to the source Cart state;
• source-state validity and expiry are independent and conjunctive;
• id + revision remains the operational identity, while RFC 8785 + SHA-256 provides a deterministic evidence identity over the decision-relevant fields;
• presentation is excluded from that digest;
• applying one of multiple Offers generated from the same source state makes the others stale;
• exact retries are idempotent, while a new application attempt is revalidated against the current state.

There are 12 conformance vectors, including the stale-but-unexpired case and lost-response/retry behavior, and the GitHub Actions test run is green.

I deliberately left transport binding, generic Cart versioning, recurring-commerce semantics, Signals/AP2 integration, and the dev.ucp.* namespace out of this prototype so those don't get conflated with the core state-bound transition semantics.

Does this look like the right semantic/conformance slice to take into the UCP enhancement/upstream process? In particular, is there anything in this minimal model you would change before I work on the UCP-native schema/operation shape?