Commerce Claims — Implementation Guide
Audience: Marketplace operators, merchants, payment providers, implementation teams. Vertical: Commerce & Retail — online marketplaces, retail chains, direct-to-consumer brands. Status: Configuration-only design; escrow-backed settlement; no bespoke tables. Substrate: Reuses Jijibora community sourcing, PoCE escrow, solver-gateway basket split.
1. Claim Types — Commerce
| Claim Type | CNS URI | Bound To | Typical Evidence Required |
|---|
| Order Claim | cns://claim/type/commerce/order_claim | resource:order | Order confirmation, delivery proof, item condition photos |
| Refund Claim | cns://claim/type/commerce/refund_claim | claim:order_claim | Refund request, return tracking, inspection report |
| Warranty Claim | cns://claim/type/commerce/warranty_claim | resource:product | Purchase proof, defect evidence, warranty terms |
| Vendor Dispute | cns://claim/type/commerce/vendor_dispute | integration_entity:vendor | Contract, SLA breach evidence, delivery records |
| Payment Dispute | cns://claim/type/commerce/payment_dispute | claim:payment | Transaction record, payment proof, bank statement |
2. Escrow-Backed Settlement
Commerce claims use escrow hold/release via fn::escrow::hold / fn::escrow::disburse / fn::escrow::rollback (s206_claim_dependency_cascade). No payment moves without verified proof.
| Escrow Stage | Trigger | Condition |
|---|
| Hold | Claim created (refund/warranty/dispute) | Amount locked, release condition declared |
| Release | Claim settled with proof | Photo/delivery/inspection evidence verified |
| Rollback | Claim rejected or cancelled | Funds returned to holder |
3. Guard Policies — Commerce
3.1 Separation of Duties
| Claim Type | Creator May Approve? | Barred Pairs | Notes |
|---|
| Order Claim | No | Buyer ↔ Seller | Different parties; marketplace mediates |
| Refund Claim | No | Buyer ↔ Refund Approver | Different parties |
| Warranty Claim | No | Buyer ↔ Warranty Approver | Independent verification |
| Vendor Dispute | No | Vendor ↔ Dispute Resolver | Different parties |
| Payment Dispute | No | Payer ↔ Payment Approver | Different parties |
3.2 Quorum Bands
| Amount Range | Risk | Quorum | Approver Roles |
|---|
| < $100 | Low | One-person standard | Customer service agent |
| $100 – $1,000 | Mid | Two-person | CS agent + marketplace operations |
| > $1,000 | High | Three-person | CS agent + operations + finance |
| Vendor Dispute | Any | Three-person | Marketplace legal + finance + vendor rep |
3.3 Evidence Requirements
| Claim Type | Required Evidence | Source |
|---|
| Order Claim | Order confirmation, delivery proof, item condition photos | Order management system + delivery integration |
| Refund Claim | Refund request, return tracking, inspection report | Returns management + warehouse inspection |
| Warranty Claim | Purchase proof, defect evidence, warranty terms | CRM + warranty registry |
| Vendor Dispute | Contract, SLA breach evidence, delivery records | Procurement system + vendor portal |
| Payment Dispute | Transaction record, payment proof, bank statement | Payment gateway + bank integration |
4. Panel Roles — Commerce
| Role | Capabilities Required | Attestation | Lease TTL | Claim Types |
|---|
| Customer Service Agent | intake, dispute_assess, refund_initiate | Yes | 1 hour | All |
| Marketplace Operations | order_verify, delivery_confirm, inspection_review | Yes | 1 hour | Order, refund, warranty |
| Finance | escrow_release, payment_approve, chargeback_review | Yes | 8 hours | Refund, payment dispute, vendor dispute |
| Vendor Representative | delivery_evidence, sla_response, contract_review | Yes | 8 hours | Vendor dispute |
All roles require: approved affiliation + active status + attestation. Fail-closed.
5. SLA Windows — Commerce
| Claim Type | Severity | Default Window | Escalation To |
|---|
| Order Claim | Urgent | 24 hours | Customer service |
| Order Claim | Standard | 7 days | Marketplace operations |
| Refund Claim | Standard | 14 days | Finance |
| Warranty Claim | Standard | 30 days | Marketplace operations |
| Vendor Dispute | Standard | 60 days | Marketplace legal + finance |
| Payment Dispute | Urgent | 48 hours | Finance |
6. Intake Maps — Commerce
| Map ID | Target | Fields Mapped | Source Channels |
|---|
intake:commerce:order | claim creation | order_id, buyer_id, seller_id, item_ids, delivery_proof, condition | Marketplace API, mobile app, API |
intake:commerce:refund | claim creation | order_id, refund_reason, return_tracking, item_condition | Returns portal, customer service |
intake:commerce:warranty | claim creation | product_id, purchase_proof, defect_evidence, warranty_terms | CRM, warranty registry |
intake:commerce:vendor | claim creation | vendor_id, contract_id, sla_breach, delivery_records | Procurement system |
7. PoCE Integration Points
| Transition | PoCE Trigger | Evidence Recorded |
|---|
| Order claim filed | fn::lifecycle::start_poce_session | buyer, order, items, delivery proof |
| Refund inspected | fn::lifecycle::record_poce_step | inspector, return condition, inspection report |
| Refund approved | fn::lifecycle::record_poce_step | finance approver, amount, payment method |
| Warranty settled | fn::lifecycle::finalize_poce_session | replacement/repair, customer acceptance |
| Vendor dispute resolved | fn::lifecycle::record_poce_step | resolver, settlement terms, vendor acceptance |
| Payment dispute settled | fn::lifecycle::record_poce_step | payer, payee, amount, transaction proof |
8. Worked Example — Order Claim with Escrow
- Buyer files claim — item not as described, photos attached, delivery proof from logistics provider.
- Claim created:
cns://claim/type/commerce/order_claim, bound to resource:order, escrow hold placed on order amount. - Customer service agent assigned via panel (one-person quorum for amounts < $100).
- Seller responds with delivery evidence and condition statement.
- Marketplace operations inspects — compares photos, checks delivery log, verifies item condition.
- Claim approved — escrow released to buyer (refund) or seller (claim denied) based on evidence.
- Claim finalized with PoCE receipt: buyer → CS agent → operations inspector → escrow release chain.
Guard check: Buyer ≠ Seller (SOD enforced). Escrow releases only against verified proof. No auto-settlement — finance or operations approver confirms.
9. What We Do Not Build
- No payment gateway. Payment processors remain the payment system of record; Sovereign OS orchestrates escrow hold/release against proof.
- No marketplace replacement. Marketplaces remain the commerce platform; Sovereign OS adds governed claims and audit.
- No synthetic "optimal" refund amount. Solver down → 502/503 fail closed.
- No fake metrics (e.g., "99% auto-refund rate"). Live data or honest empty states.
10. Deployment
- Deploy strata:
s214_claim_arbitration (escrow functions), s282_processing_claim, s233_unified_claims - Seed CNS types:
cns://claim/type/commerce/* - Seed lookups: guard policies, quorum bands, SLA windows, panel roles, intake maps in NATS KV
- Seed scenario packs: order claim, refund claim, warranty claim, vendor dispute packs
- Configure escrow: release conditions per claim type in NATS KV
- Test:
GET /v1/claims/processing/readiness — all probes must pass before LIVE