web/docs/handoff/marketplace-backend-checklist.md

Backend Handoff Checklist: Marketplace Checkout and Entitlements

This checklist maps store behavior to required marketplace backend implementation.

Required Endpoints

1. GET /marketplace/offers
2. GET /marketplace/offers/{offer_id}
3. POST /marketplace/checkout/quote
4. POST /marketplace/checkout/confirm
5. GET /marketplace/entitlements?wallet=...

Required Gate Behavior

1. Quote endpoint must deny checkout when membership is not active.
2. Confirm endpoint must verify quote policy hash and tx match.
3. Entitlement state must default fail-closed for unknown values.

Store Dependency Mapping

1. Store catalog requests /marketplace/offers (fallback to local JSON until live).
2. Store quote action posts selected offer_id and ownership wallet.
3. Optional payer wallet may differ and must include ownership proof.
4. Store expects quote payload with tx execution fields.
5. Store confirm path expects entitlement_active response.

Quote Response Requirements

1. quote_id
2. wallet (ownership wallet)
3. payer_wallet (optional)
4. offer_id
5. currency
6. amount or amount_atomic + decimals
7. policy_hash
8. expires_at
9. tx execution object or equivalent fields

Confirm Response Requirements

1. status = entitlement_active
2. entitlement_id
3. offer_id
4. wallet (ownership wallet)
5. payer_wallet (optional)
6. tx_hash
7. policy_hash
8. activated_at

Persistence Requirements

1. Quote record with policy hash and expiry.
2. Confirm record linked to tx hash and entitlement id.
3. Entitlement lifecycle state with immutable issued event evidence.

Security Requirements

1. Membership gate check on quote and confirm paths.
2. Quote TTL enforcement.
3. Tx chain, amount, and destination validation.
4. Idempotent confirm handling for repeated tx hash submissions.
5. Ownership wallet proof validation when payer wallet differs.

Done Criteria

1. Store can request quotes for active members only.
2. Confirm endpoint issues active entitlements deterministically.
3. Entitlement listing endpoint returns current state records.
4. API matches docs/api/marketplace.openapi.yaml.