Notes / February 20, 2026

Premium order protection in Shopware—how we approached it

Third-party protection products, cart rules, and post-order reconciliation without surprising finance.

Patterns from a Shopware 6 commerce build (Albany-adjacent); partner names generalized.

“Order protection” products (extended returns, shipping insurance–style SKUs, or third-party warranty add-ons) look simple: add a line item. The expensive part is cart math, promotion interaction, tax, refunds, and revenue recognition when a third party sends async confirmations.

This is how I approached it so finance and CX did not get surprised after launch.

1. Product catalog design

  • Virtual product — no inventory decrement; fulfillment pipeline skips pick/pack.
  • Tax class — align with finance; some add-ons are taxable as services, some are not—do not guess.
  • Visibility — hide from search/listing if it should only appear as an upsell, not a browsable SKU.
  • Translations — legal copy differs by locale; store in snippet or product long description with CMS preview.

2. Cart rules: auto-append vs opt-in

Auto-append

  • Cart rule: IF cart contains shippable goods AND NOT already contains protection SKU → add.
  • Watch stackability with coupons that grant 100% off—does protection become free incorrectly?

Opt-in

  • Checkbox on cart or mini-cart modal → adds line via Store API / AJAX route.
  • Easier legally (“customer chose”); slightly lower attach rate.

Precedence doc (we actually wrote this in Confluence)

  1. Free shipping promotions
  2. Percent-off coupons
  3. BOGO rules
  4. Protection append rule

When two rules fight, log the winner in debug channel for first week post-launch.

3. Checkout UX and disclosure

  • Surface plain-language summary before payment: what is covered, what is not, cancellation window.
  • Link to PDF terms hosted on CDN (versioned URL with ?v=20250301 so old orders reference immutable terms).
  • Accessibility: checkbox must be keyboard-focusable; error text if they try to remove protected goods but leave protection—explain fix.

4. Tax and Avalara (or core tax)

If protection is its own line item:

  • Confirm tax code in Avalara matches SKU mapping.
  • For RDF / fee-style jurisdictions, verify protection is not double-counted as shipping.

We ran GetTax fixture tests comparing cart JSON before/after protection line—saved diffs in repo as golden files.

5. Post-order and async partner APIs

Many partners confirm coverage after payment:

  • Queue job on OrderPlaced with idempotency key = orderId + lineItemId.
  • Store partner’s coverageId on line item payload or customFields.
  • Retry policy: exponential backoff; DLQ after N failures with PagerDuty route.

Order states

  • Do not move to complete for CX until partner ack OR timeout SLA reached—align with OMS expectations.

6. Refunds and partials

Test matrix (we automated parts in integration tests):

  • Full order refund → protection removed or refunded per contract.
  • Partial refund of merchandise only—does protection remain valid?
  • Split shipment — if protection is per-shipment vs per-order, document which carrier events trigger consumption.

7. Observability

  • Metrics: attach rate, partner API error %, average confirmation latency.
  • Dashboard for finance: MRR-style reporting if protection is recurring (usually not—still useful).

Resume framing

“Owned order-protection in Shopware: product + cart rules + checkout disclosure, tax validation with Avalara fixtures, async partner integration with retries, and refund edge cases covered by tests.”