Puratek Shipping Protection

In-house shipping protection for WooCommerce — replaces Route.

Instead of paying a third-party service, Puratek now offers its own shipping protection. A 3% fee is added automatically at checkout, and the customer can remove it with one click if they don't want it. All protection revenue stays with the store.

---

What this plugin does

Adds	A "Shipping Protection" checkbox on the checkout page, checked by default
Charges	3% of the cart subtotal (after discounts) as a normal WooCommerce fee
Customer control	Untick the box → fee is removed instantly, no page reload
Records	The choice (Yes/No) and fee amount are saved on every order
Replaces	The Route plugin and its third-party subscription

---

What the customer sees

1. Customer adds products to the cart and goes to Checkout.

2. In the order summary, just above the total, they see:

   ☑  Shipping Protection
      Protects your order against loss, theft, or damage in transit.
   
   Shipping Protection                               $4.79
   ─────────────────────────────────────────────────────────
   Total                                           $164.44

3. The box is already ticked — protection is included automatically.

4. If they untick it, the totals refresh in place and the fee disappears.

5. The fee (when kept) appears on the thank-you page, the order confirmation email, and the customer's invoice — exactly like any other order line.

Every new order starts with the box ticked again, even if the same customer removed protection on a previous order.

The checkout also includes a Route-style branded widget. Clicking either the Shipping Protection title or the information icon opens an accessible modal with coverage details, issue-resolution guidance, 24/7 claim support, and links for claims, privacy, and terms. The modal closes from its close button, the backdrop, or the Escape key and traps keyboard focus while open.

---

What the store team sees

WooCommerce → Orders → (any order):

• The fee appears as a line item: Shipping Protection $4.79
• In the order details box there is a clear indicator:
  • 🟢 Shipping Protection: Yes — this order is protected
  • 🟠 Shipping Protection: No (customer removed) — customer opted out

When a customer reports a lost / stolen / damaged shipment:

1. Open the order and check the indicator.
2. Yes → the order is protected; reship or refund per Puratek's protection policy. (Claims are now handled by Puratek support, not Route.)
3. No → the customer declined protection; handle per standard policy.

Refunds: the protection fee is a normal order line — when refunding, you choose whether to include it, just like shipping.

---

Installation & go-live

1. Upload the plugin: Plugins → Add New → Upload Plugin → select the zip → Activate, then review WooCommerce → Shipping Protection.
2. Place a small test order and confirm the fee appears at checkout, on the order, and in the confirmation email.
3. Only after the test order is verified: deactivate the Route plugin.
4. Cancel the Route subscription.

⚠️ Never run this plugin and Route at the same time in production — the customer would be charged for two protections.

---

Configuration

Open WooCommerce → Shipping Protection to configure:

• Protection percentage and default checkout state
• Accent color and brand name
• Compact, Shield Card, or Toggle Banner checkout design
• Checkout and popup copy
• Claim, privacy, and terms page URLs

Saved settings are sanitized. Popup links are displayed only when their URL fields have been completed.

Fee base (the one-line switch): at the top of puratek-shipping-protection.php:

define( 'PURATEK_SP_FEE_BASE', 'subtotal' );

• 'subtotal' — 3% of product subtotal after discounts, shipping excluded (current default)
• 'subtotal_shipping' — 3% of product subtotal after discounts plus shipping cost

Puratek's configured policy is the discounted product subtotal, excluding shipping and tax. The alternative remains available as a developer override.

Developer filters remain available for advanced overrides:

Filter	Purpose	Default
puratek_sp_percentage	Fee percentage	3
puratek_sp_label	Customer-facing label	Shipping Protection
puratek_sp_fee_base	Amount the % is calculated on	Cart subtotal after discounts, excl. shipping & tax
puratek_sp_fee_taxable	Charge tax on the fee	No
puratek_sp_brand_name	Widget/modal brand name	Puratek
puratek_sp_brand_logo_url	Optional modal logo URL	Empty (text mark used)
puratek_sp_claim_url	File A Claim link	Hidden until configured
puratek_sp_privacy_url	Privacy Policy link	Hidden until configured
puratek_sp_terms_url	Terms & Coverage link	Hidden until configured

Example — change the fee to 2.5%:

add_filter( 'puratek_sp_percentage', function () { return 2.5; } );

Example — include shipping in the 3% base:

add_filter( 'puratek_sp_fee_base', function ( $base, $cart ) {
    return $base + (float) $cart->get_shipping_total();
}, 10, 2 );

---

FAQ

Does it work with coupons? Yes. The 3% is calculated after discounts, so customers are never charged protection on money they didn't spend.

Is the fee taxed? Not by default. It can be switched to taxable with the puratek_sp_fee_taxable filter if required.

Where is the customer's choice stored? On the order itself: meta _puratek_shipping_protection (yes / no) and _puratek_shipping_protection_fee (amount). Reporting tools can query it.

Does it work with the block-based checkout? No — it is built for the classic [woocommerce_checkout] shortcode checkout, which is what this site uses.

Multisite? Yes. Activate it per-site; no network-wide configuration is needed.

HPOS (High-Performance Order Storage)? Yes, fully compatible.

---

Troubleshooting

Symptom	Likely cause / fix
Checkbox missing at checkout	Theme overrides the order review template without the woocommerce_review_order_after_order_total hook — check the child theme's WooCommerce templates
Fee doesn't update when toggling	JavaScript error from another plugin blocking the AJAX call — check the browser console
Two protection fees shown	Route is still active — deactivate it
Fee shows $0.00	Cart subtotal is 0 (e.g. 100% coupon) — the fee hides itself automatically at 0

---

Technical summary (for developers)

• Fee via woocommerce_cart_calculate_fees (checkout contexts only: checkout page, update_order_review, wc-ajax=checkout).
• Opt-in state in WC()->session (puratek_shipping_protection), default yes.
• Toggle endpoint: ?wc-ajax=puratek_sp_toggle (nonce-protected).
• Checkbox rendered inside the review-order table so it survives fragment refreshes; JS handler is delegated to document.body.
• Order meta written through the WC_Order object (HPOS-safe) on woocommerce_checkout_create_order.

---

Changelog

1.2.3 - August 2026

• Removed the percentage from the customer-facing WooCommerce fee label while preserving the configured fee calculation.

1.2.2 - August 2026

• Replaced the browser checkbox with a consistent branded control and white checkmark.
• Improved borders, spacing, focus states, selected states, and card depth across all templates.

1.2.1 - August 2026

• Compacted the popup and removed the oversized standalone icon.
• Updated the popup summary to match coverage exclusions and the 10-day claim window.
• Hide claim, privacy, and terms links unless their URLs are explicitly configured.

1.2.0 - August 2026

• Added a WooCommerce admin settings screen.
• Added Shield Card and Toggle Banner checkout templates alongside Compact.
• Added configurable percentage, default state, color, copy, and policy URLs.
• Refreshed the information popup with a stronger visual hierarchy.
• Made the submitted checkout field authoritative and added a no-JavaScript fallback.
• Mark orders protected only when the protection fee is actually present.

1.1.0 - August 2026

• Added a Route-style branded checkout widget with a live fee amount.
• Added an accessible information modal and responsive isolated CSS.
• Added smooth modal entrance/exit and staggered benefit animations with a reduced-motion fallback.
• Added native-fetch opt-in toggling with WooCommerce totals refresh.

1.0.1 — August 2026

• Finalized the fee base as discounted merchandise subtotal, excluding shipping and tax.
• Hardened percentage filtering and checkout-session error handling.
• Restores the checkbox when the AJAX update fails, preventing misleading totals.

1.0.0 — July 2026

• Initial release: automatic 3% protection fee, opt-out checkbox with AJAX totals refresh, order meta record, admin order indicator.