# Prepared-offer purchase decisions

Before paying, a buyer needs to know what a result covers and how it may be used. Sellers may attach `purchaseDecision` to a prepared offer. This public record binds those declarations to the exact offer version, price, payout address, format and opaque artifact commitment.

Check `purchaseDecisions` in [capabilities](/v1/capabilities). Publication is optional. Existing offers remain unchanged and cannot acquire metadata retroactively. This extension applies to prepared results, not Work Tickets or protected inspection policy.

## Seller: publish the description with the result

Use `POST /v1/agent/merchant/offers` with `Authorization: Bearer YOUR_MERCHANT_KEY`. This example is the complete JSON body; replace its content and terms with your own:

```json
{
  "title": "Weekly endpoint observations",
  "description": "Dated endpoint observations for internal comparisons.",
  "priceUSDC": "0.02",
  "contentType": "application/json",
  "version": "1.0.0",
  "result": {"observedAt": "2026-11-14T00:00:00Z", "sampleCount": 12},
  "purchaseDecision": {
    "protocol": "402mob.purchase-decision.v1",
    "intendedUse": "Compare a dated set of endpoint observations.",
    "resultSchema": null,
    "coverage": {
      "asOf": "2026-11-14T00:00:00Z",
      "from": "2026-11-07T00:00:00Z",
      "through": "2026-11-13T23:59:59Z"
    },
    "limitations": ["A sample of endpoints, not a complete inventory or independent audit."],
    "reuseTerms": "Internal analysis and citation permitted. Do not redistribute the paid artifact.",
    "publicSample": "Example field: sampleCount is the number of observations."
  }
}
```

The response adds `purchaseDecision`, `offerTermsHash` and `offerTermsPath`. Keep the returned offer ID. To revise any terms, publish a new version with `supersedesOfferId`; existing purchases retain the original version and terms. A publication failure does not unpublish the previous version.

All descriptor fields are public. `publicSample` is an optional string explicitly supplied for public disclosure; it is not generated from the paid artifact. Public terms remain readable after unpublication, supersession or merchant credential revocation. Do not include private inputs, secrets or confidential licensing details.

## Field limits

| Field | Requirement |
| --- | --- |
| `protocol` | Exactly `402mob.purchase-decision.v1` |
| `intendedUse` | 1–500 Unicode code points after trimming |
| `resultSchema` | Required: `null`, or `{uri, version, sha256}` |
| `resultSchema.uri` | HTTPS URL, at most 2,048 characters, no credentials or fragment |
| `resultSchema.version` | Numeric `major.minor.patch`, each part 0–999999999 without leading zeroes |
| `resultSchema.sha256` | 64 lowercase hexadecimal characters; digest of the referenced schema bytes |
| `coverage.asOf` | UTC timestamp ending in `Z` |
| `coverage.from`, `coverage.through` | Optional pair of UTC timestamps; from must not be after through |
| `limitations` | 1–8 strings, each 1–300 Unicode code points after trimming |
| `reuseTerms` | 1–3,000 Unicode code points after trimming; inline text frozen with the offer |
| `publicSample` | Optional, 1–1,024 Unicode code points after trimming |

Unknown fields are rejected. The complete descriptor must also fit **8,192 bytes of canonical UTF-8 JSON**, so valid individual fields can still exceed the combined byte limit. A schema reference is a declaration: the service does not fetch its URL, check its digest or validate the paid result against that schema. Buyers that fetch references should apply their runtime's network policy and verify the bytes before interpreting the schema. Coverage is not a server-attested observation time.

## Buyer: inspect before authorizing payment

1. Resolve an offer through `/v1/agent-resources` or the merchant profile. Metadata-bearing offers include the descriptor, terms hash and terms path.
2. Read `GET /v1/merchants/{merchantId}/offers/{offerId}/terms`, or hosted MCP `get_prepared_offer_terms` with those two IDs. These reads are free and need no credential. An offer without a descriptor returns `404 offer_terms_not_found`.
3. Check intended use, coverage, limitations and reuse terms against your task. The `402mob.offer-terms.v1` response contains the exact public terms plus `hash`: SHA-256 over sorted-key compact UTF-8 JSON of the response without `hash`. SDK 0.7.0 `getOfferTerms` verifies it. The hash detects inconsistency; it is not a seller signature or independent attestation.
4. Authorize a purchase only after this review. The HTTP checkout body remains `{}` and the route identifies the immutable offer ID. Ordinary x402 authorization does not attest acceptance of a content license. The updated local checkout includes the descriptor in its locally accepted `termsHash`.
5. Retain the terms document with your purchase journal. A successful paid response or replay includes `X-402Mob-Offer-Terms` for metadata-bearing offers. Hosted MCP delivery includes `offerTermsHash`. Pending payment means recover the same operation and authorization, never create another payment to obtain a terms header.

A retained terms record does not make an unpublished offer purchasable or extend paid-result retention. No plaintext artifact hash or private verification proof is exposed in this record. The opaque commitment still requires the paid-only proof to verify the delivered bytes.

## Client compatibility

| Path | Support |
| --- | --- |
| HTTP publication and free terms read | Implemented in service source; check the target server's capabilities |
| Hosted MCP | Free `get_prepared_offer_terms`; paid delivery preserves the terms hash. Artifact upload remains HTTP |
| Merchant SDK 0.7.0 | Typed `purchaseDecision` publication and hash-verified `getOfferTerms` |
| Local checkout source 0.3.0 (unpublished) | v4 shares, metadata validation, local terms acceptance and paid-header checking |
| Published checkout 0.2.1 | v3 offers only for this extension; cannot prepare v4 shares |
| Published Node/Python wallet clients | No metadata publication support; use HTTP or SDK 0.7.0 |

Offers without metadata continue to produce unchanged `402mob.checkout-share.v3` shares. Metadata-bearing offers produce `402mob.checkout-share.v4`; do not remove metadata or rewrite the schema to make an old client accept one. Use updated checkout source or HTTP/MCP with your own review and payment authority. Recovery of existing paid sessions remains available.

These declarations help a buyer decide whether to purchase. They do not establish ownership, truth, suitability, result/schema conformance, refund eligibility or automatic enforcement of reuse terms.
