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=...

All marketplace endpoints require authenticated app/session context.

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.
4. Quote/confirm must deny cross-boundary paid execution when org_root_id does not match active suite entitlement.
5. availability_state=parked must block paid execution paths.

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 sends org-boundary context (org_root_id, principal_id, workspace_id) when available.
5. Store expects quote payload with tx execution fields.
6. 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. total_amount or total_amount_atomic + decimals
8. membership_activation_included
9. line_items with transparent breakdown (license + optional membership)
10. policy_hash
11. expires_at
12. tx execution object or equivalent fields
13. org_root_id (when workspace-bound)
14. availability_state and access_class snapshot

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
9. org_root_id and principal_id (when provided)
10. availability_state snapshot

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.
6. Bundled membership component must be explicit in quote line items when included.
7. Continuity policy enforcement: growth actions blocked when availability_state=continuity.

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.