# 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 wallet.
3. Store expects quote payload with tx execution fields.
4. Store confirm path expects `entitlement_active` response.

## Quote Response Requirements

1. `quote_id`
2. `wallet`
3. `offer_id`
4. `currency`
5. `amount` or `amount_atomic + decimals`
6. `policy_hash`
7. `expires_at`
8. `tx` execution object or equivalent fields

## Confirm Response Requirements

1. `status = entitlement_active`
2. `entitlement_id`
3. `offer_id`
4. `wallet`
5. `tx_hash`
6. `policy_hash`
7. `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.

## 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`.