Shipping Protection & Extended Warranty

Paid pluginsize Mplanned, not built

Indicative price, not an offer: $9-29/mo + 1-2% transaction fee for claims reserve

Generated from docs/plan/paid/shipping-protection-extended-warranty/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Orders arrive damaged or lost, causing chargebacks and negative reviews. This paid module enables merchants to offer shipping protection and extended warranty to customers, reducing claims.

The problem

I lose money when packages arrive damaged or don’t arrive — chargebacks cost me 2-3x the order value. I need to offer shipping protection so I can recover costs from an insurance partner instead of taking the loss.

What it does

• Add shipping_protection collection: {id, order_id, provider (partnername), premium_amount_minor, status (active|claimed|denied|payout), claim_id}
• At checkout, offer shipping protection as add-on (e.g., ’+$2 for $200 protection on $100 order’)
• Store protection premium as line item in order_items (protection_service)
• Customer can file claim after delivery if package is lost or damaged
• Claim workflow: customer uploads photo evidence, staff reviews, provider decides approval
• Approved claim triggers payout from provider (automatically or manual reconciliation)
• Admin dashboard shows: claims filed, approval rate, payout status, claims reserve balance

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Underwriting or claims adjudication (that is provider’s job, not core) — core only logs claim and payout status
• Multi-party claims (e.g., customer + merchant + provider negotiate) — that is litigation, not e-commerce
• Extended warranty (product defects, accidental damage) — that is separate insurance product, not shipping protection
• Fraud scoring/ML to detect fraudulent claims — that is optional plugin; core takes all claims at face value

Data model

shipping_protection collection: {id, order_id, provider, premium_amount_minor, status, claim_id, claim_date, evidence_photos: [url], claim_decision, payout_amount_minor, payout_date}. orders.shipping_protection_id. order_items (add protection line item if purchased). No migration if columns are additive.

API

• POST /api/admin/shipping-protection/enable — enable protection offering for merchant
• GET /api/customers/:customerId/orders/:orderId/protection-claim — fetch protection claim form
• POST /api/customers/:customerId/orders/:orderId/protection-claim — file protection claim
• GET /api/admin/shipping-protection/claims — list claims with status
• PATCH /api/admin/shipping-protection/claims/:claimId/decision — approve/deny claim

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Checkout shows optional add-on checkbox: ‘Protect this order (damage/loss) — $2.00’. Order detail shows: protection status (active/no protection), claim button if eligible (order delivered >7 days ago). Claims section shows: filed date, evidence photos, merchant decision (approved/denied/pending), payout status.

The seam — why this is paid

Paid module owns provider integrations, claim workflow, and payout reconciliation. Core provides claim logging and UI. Merchant must sign contract with provider (Xcotton, Redo, etc.) and pay commission (typically 20-30% of premium); core facilitates but doesn’t own the insurance relationship.

Paid module owns insurance underwriting credential, claims processing, and fraud scoring ML; core does not manage insurance

Dependencies

• Existing orders, order_items, customers collections
• email layer (to notify customer of claim decisions)
• webhook system (optional, for provider claim update callbacks)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Add protection to order; confirm shipping_protection collection stores premium_amount_minor and status=‘active’
• Verify protection is visible as line item in order_items
• File claim with photo evidence; confirm claim_date is recorded
• Approve claim; confirm status changes to ‘claimed’ and payout_amount_minor is set
• Verify claim is sent to provider API (or marked for manual submission if async)
• Verify customer receives email notification of claim decision

Risks

Fraudulent protection claims can be expensive; providers use fraud scoring. Implement photo evidence requirement and timestamp validation (claim filed <30 days after delivery). Premium pricing must reflect actual loss rate; monitor chargeback data to adjust pricing. Provider integration can fail; implement fallback (manual claims processing).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.