Package Protection¶

Package Protection adds an optional shipment-protection fee at checkout and fronts the claims workflow customers use when items arrive damaged or go missing. Merchants configure the fee amount and behavior per channel; customers file claims against their orders from the storefront, and admins resolve approved claims with store credit and a replacement order.

At a glance


Extension id	`package_protection`
Category	fee
Version	0.1.0
Provides	Fee calculation strategy (`package_protection`), admin nav entries, dashboard widget
External account	None

What It Provides¶

Fee calculation strategy — PackageProtectionCalculator, registered as a FeeCalculationStrategy under the name package_protection. It is a thin wrapper that delegates to the core fee calculator, so the Package Protection fee supports the five built-in calculation types (flat, percent, flat_plus_percent, per_weight, per_box); the separate named strategy exists so channel-scoped resolution can filter by extension_name="package_protection" when multiple fee extensions are active.
Admin sidebar entries (declared in the manifest) — Claims (/claims) under Customer Service, and Package Protection (/settings/checkout/package-protection) under the Checkout settings section.
Dashboard widget — a dashboard-widget slot contribution shipped inside the extension package (admin/DashboardWidget.svelte) and mirrored into the admin by the extension-UI sync. It renders a status card linking to the claims queue; visibility honors the Show on Dashboard flag in the per-channel config and fails open (visible) when the flag or config cannot be resolved.
Claims workflow (core) — the claim data model and services live in the core fee module (backend/vectis/modules/fee/): admin-defined claim reasons, claims with line items and an event audit trail, and the lifecycle submitted → in_review → denied/approved → complete. Customers file claims from the storefront account area (/account/claims); resolving a claim (default resolution type store_credit_and_reorder) issues store credit for the claimed value and creates a replacement order from the claimed lines.
Eligibility flags — accounts and shipping addresses carry a package_protection_eligible flag; when either is ineligible, checkout's available-fees listing attaches a customer-facing ineligibility reason to the fee.

Setup¶

Enable the extension for your channel under Settings > Extensions.
Configure the fee under Settings > Checkout > Fees — per the manifest install hint: "Enable the extension and configure the fee amount in Settings > Checkout > Fees. Manage claim reasons in Settings > Package Protection." Fee rows whose extension_name is package_protection receive the per-channel overrides below at quote time.
Fine-tune per-channel behavior on Settings > Checkout > Package Protection (/settings/checkout/package-protection): fee toggle and placement, default calculation type and amount, the claims toggle and claim-form messages, and dashboard-widget visibility.
For demo environments, python -m vectis.core.seed_fees seeds a Package Protection fee (flat 4.99, auto-attach), four claim reasons (Damaged, Missing - All Quantity, Missing - Partial Quantity, Wrong Item Received), and a starter channel config.

Configuration Reference¶

The manifest declares an empty config_schema — configuration happens on the extension's own settings page, Settings > Checkout > Package Protection (/settings/checkout/package-protection), which stores its keys on the per-channel extension config:

Key	Read by	Effect
`fee_enabled`	Checkout fee listing	When `false`, the Package Protection fee is omitted from available fees.
`default_calculation_type`	Checkout fee listing	Overrides the fee row's calculation type at quote time.
`default_flat_amount`	Checkout fee listing	Overrides the fee row's flat amount at quote time.
`auto_attach`	Checkout fee listing	Overrides the fee row's auto-attach flag.
`show_on_dashboard`	Dashboard widget	An explicit `false` hides the widget; anything else leaves it visible.
`fee_placement`, `allow_claims`, `claim_header_message`, `claim_footer_message`	—	Stored by the settings page but not read by the current checkout or storefront code.

Permissions¶

The manifest declares no permissions.

Operational Notes¶

Per-channel overrides apply only when a package_protection channel-extension row is enabled for the channel; after applying the overrides, the checkout resolver recalculates the fee amount.
Eligibility denials use fixed messages: "This account is not eligible for package protection." / "This shipping address is not eligible for package protection."
The credited value on resolution is the claimed lines' value — the whole order's line totals for whole-order claims, otherwise final_unit_price × quantity_claimed per claimed line.
Claim resolution is best-effort on both legs: store-credit issuance and replacement-order creation each log a warning on failure rather than failing the resolution; the claim still transitions to complete, recording the credit amount and (when created) the replacement order id.

For the extension developer view, see Building Extensions.