Digital / intangible goods delivery — in scope for UCP, and if so where?

[gforgab]

Temperature-check before any schema. The spec points two ways on digital goods, and a common flow falls through the gap.

The contradiction: expectation.json lists digital as a well-known method_type (and has since day one), but fulfillment.md says "digital goods do not need to be assigned to a method." So digital is a named delivery method with nowhere to live — and even where it's named, expectation.destination is fixed to postal_address, which can't hold a digital target.

Where it bites (ordinary, high-frequency commerce — top-ups, gift cards, codes; maps cleanly to agent flows):

• delivery needs a non-postal target at checkout (phone for a top-up, email for a voucher, account/device for e-SIM);
• purchase returns a redeemable artifact (code / PIN / license key / link) — UCP has no field for this anywhere on the Order.

Questions:

1. Is digital-goods delivery something UCP wants to model, or deliberately left to businesses? Either way, the digital value and the doc language should be reconciled.
2. Where should the delivered artifact live — the actions primitive (feat: extension-defined Actions primitive #582; feat: add com.mercadopago.payment.render_artifact extension #635 uses it for a Pix display, [Proposal]: Out-of-session payment settlement — order-level actions + order.payment_status #641 would put actions on the Order), or fulfillment_event? Note actions is framed as outstanding (to-do), while a code must persist for later retrieval — and unlike a Pix artifact, a gift-card code is bearer-redeemable, so it needs a tighter read model.

If there's appetite, happy to prototype the no-core-change piece first (a vendor-namespaced delivered-artifact extension, in the #635 mold) and bring the destination/vocabulary parts as focused EPs after.

[westonale-facet]

Your read-model distinction is the part worth pulling on. actions being framed as outstanding work is exactly why it's the wrong primitive here: once the buyer redeems the code, the action is done, and a system that clears completed actions destroys the one record a dispute later needs. fulfillment_event has the opposite problem for the retrieval half. An event is typically a one-shot notification, not something a merchant or a stranger auditing months later can query on demand, and "has this code been redeemed yet" is exactly that kind of standing question.

The two things I'd build in from day one on the vendor-namespaced extension, since retrofitting either is painful: a persistent read path independent of order or action status, so an order can complete and archive while the code itself stays queryable, and an explicit redeemed state transition rather than treating delivery as terminal. A gift-card code that's bearer-redeemable with no notion of already spent is a double-spend bug waiting to be found, and it's a much smaller problem to model at the schema level now than to patch onto a shipped extension later.

The prototype-first path seems right: land the delivered-artifact shape as a vendor extension, prove the redemption lifecycle against a real implementation, and bring destination/vocabulary as focused EPs once there's something running to point at rather than a hypothetical.

[gforgab]

Thanks @westonale-facet — sharpest framing so far, agreed on the core.

Primitive: neither fits. actions models outstanding work (a system that clears completed actions erases the record a dispute needs); fulfillment_event is one-shot and can't answer "redeemed yet?" on demand. The artifact needs its own durable, queryable read path, independent of order/action status.

Lifecycle: taking your correction — delivery is not terminal. delivered and redeemed are distinct states, redeemed meaning actually spent at the issuer; without it a bearer code has no double-spend guard. (Redemption can also be partial — gift-card balances draw down — and the issuer, not the checkout, is the source of truth.)

Scope — "digital goods" isn't one shape. This nails bearer artifacts (gift cards, vouchers, top-ups, keys). But entitlement/access — a course, platform/SaaS access — has no bearer code and no "redeem": access is provisioned to the buyer, and the question is "still valid, until when?" (active → expired/revoked), not "spent?". So I'd give the read model a kind discriminator (redeemable_artifact | entitlement | …) with a per-kind lifecycle from day one, so entitlement lands later without retrofit. Its time-boxed/renewable half overlaps #587 and #629 — I'd defer renewal/scheduling there rather than reinvent it here.

Path: prototype-first. v1 lands the redeemable-artifact shape (redemption lifecycle + order-independent read path) as a vendor extension in the #635 mold; entitlement is reserved via kind but not modeled yet. I'll draft it and tag you.

[westonale-facet]

Both corrections land, and the second is the more important one: I collapsed two shapes into one and you have separated them correctly. Bearer artifacts and entitlements are not variants of a single "digital good" type, and a spec that models them as one will be wrong for whichever one it did not have in mind.

The line I would draw is not bearer versus not. It is what question the buyer's agent has to be able to ask six months later. For a bearer artifact: how much is left? State is a quantity that decrements, and anyone holding the code can decrement it. For an entitlement: is this still good, and until when? State is a validity window that can be revoked for reasons the order knows nothing about, a chargeback, a ToS termination, the issuer sunsetting the product.

That difference drives the one thing I would most want the spec to get right, and it follows directly from your point that the issuer is the source of truth: do not carry the mutable state in the protocol payload. If UCP puts remaining_value, or status: active, on the checkout or order object, every integrator will read it as authoritative when it is a cached copy of state owned by a third party that can change without the order ever being touched. That is the double-spend seam moved rather than closed: not two people spending one code, but one integrator trusting a stale balance. What the artifact needs is a durable reference plus a defined way to ask the issuer, with the answer carrying its own timestamp. The order stores the pointer, never the balance.

On lifecycle, one thing worth taking from the money leg, because it is structurally the same problem: separate who authorizes a state transition from when it is submitted. On escrow we let the buyer pre-authorize the redeem and let it be submitted later, immediate or deferred, because "the buyer agreed to this" and "the release happened" are genuinely different events with different timing. Your delivered to redeemed split is that same shape.

And if redemption is partial, it is not a transition at all. It is an append-only sequence of draws against the artifact. Modelling that as a status enum loses exactly the history a dispute needs, which was the original objection to actions and applies to a naive redeemed flag just as much.

The reason I care where this lands: if delivery is not terminal, then delivery finality and settlement finality are different events. A rail that releases funds on delivered has paid out for a code that may never be redeemed, or that gets revoked next week. That is workable if everyone knows it, and a real problem if the spec implies otherwise.

To be clear about what I am speaking from: we run the escrow and redeem lifecycle in production for physical fulfilment, not a bearer-artifact implementation. Take the second half as an argument from the adjacent problem rather than from a running one.

[gforgab]

This is really helpful — the "what question the buyer's agent has to be able to ask six months later" framing is the right axis, and it changes what I'd put in the schema. Taking your points as design principles for the prototype:

1. The order stores a pointer, never the state. This is the one I'd fix as an invariant. The artifact carries a durable reference plus a defined way to ask the issuer, and the issuer's answer carries its own timestamp. remaining_value / status: active never sit on the order or checkout as authoritative fields — at most as a clearly-marked, timestamped cached read. Issuer stays the single source of truth, and — as you put it — we don't just relocate the double-spend seam to "one integrator trusting a stale balance."

2. Partial redemption is an append-only ledger, not a status enum. Agreed — a sequence of draws against the artifact, so the dispute history is the data model rather than something a terminal flag discards. A boolean redeemed was the naive shape I'd have reached for, and it has the exact defect that ruled out actions.

3. kind splits bearer vs entitlement, and the question drives the state. bearer → a decrementing quantity anyone holding the code can draw down; entitlement → a validity window revocable for reasons the order never sees (chargeback, ToS termination, sunset). Same durable-reference + ask-the-issuer mechanism, different per-kind read shape.

4. Delivery finality ≠ settlement finality. This is the one I most want the spec to say out loud. If delivery isn't terminal, a rail that releases funds on delivered has paid for a code that may never be redeemed, or gets revoked next week. The extension should state that explicitly rather than let it be implied, so a settlement integrator doesn't wire "delivered" to "release."

On weighting, to be fair to your own caveat: I'll take the ledger and the delivery-vs-settlement points as strong priors from the adjacent escrow/redeem problem you run in production, and treat the bearer-artifact specifics as what the prototype actually has to prove — I'd rather validate the redemption lifecycle against a real bearer implementation than assert it. The pointer-not-balance rule (1) I'm comfortable fixing now regardless.

Prototype-first still the plan: a vendor-namespaced delivered-artifact extension in the #635 mold — kind + durable reference + issuer-query from day one, redemption as append-only draws — with destination/vocabulary as focused EPs once there's something running to point at. Your escrow cue (separate who authorizes a transition from when it's submitted) is a good structural fit for the redeem step; I'll carry it in. Will tag you on the draft.

[gforgab]

Drafted the prototype as promised: #719 — a vendor-namespaced com.mercadopago.shopping.digital_delivery extension on the Order.

It carries what we converged on here:

• kind splits redeemable_artifact vs entitlement — the "how much is left?" vs "still valid, until when?" question drives the shape.
• The Order stores only a durable reference + a lookup to query the issuer — no cached balance or status (pointer, never the balance). We went strict and dropped even a timestamped cached snapshot.
• Redemption, including partial, lives at the issuer as an append-only ledger, obtained via lookup — never a status flag on the Order.
• Delivery ≠ settlement is stated explicitly: a rail must not release funds on delivered.

Destination/vocabulary and the digital method_type reconciliation stay out of scope here, as separate core EPs once the prototype has traction.

@westonale-facet — would value your read, especially on the pointer-only decision and the delivered-vs-settlement wording. Tagging you as promised.