Shopify
Protection on Shopify.
Protection is an ordinary hidden product, two webhooks, and a cart toggle. There is no Covr app to install — everything here is store configuration you already control.
How it fits together
Protection on Shopify is an ordinary product. The shopper adds it to the cart like anything else, it appears as a line item on the order, and Covr reads it from the order webhook.
There is deliberately no Covr app to install. Everything below is store configuration you already control.
| Field | Type | Description |
|---|---|---|
| 1. A protection product | one-time | A hidden product whose variants are the prices you can charge. Created once per store. |
| 2. Two webhooks | one-time | orders/create and fulfillments/create pointed at Covr. This is what books the premium and starts tracking. |
| 3. A cart toggle | theme | A snippet that quotes the premium and adds or removes the line item. The only part that touches your theme. |
Do I need a Shopify app?
For a store you own, no. An app exists to let a third party install into a theme it has never seen and read orders it otherwise has no access to — neither applies when it is your own store.
A custom app is worth creating for one narrow reason: it gives you Admin API credentials without the OAuth and app-listing work. If you want to script the product setup below rather than click through it, create a custom app in Settings → Apps and sales channels → Develop apps, and give it write access to Products.
The protection product
One product per store, hidden from search and collections. Its settings matter more than they look — three of the four below cause real operational damage if left at Shopify's defaults.
| Field | Type | Description |
|---|---|---|
| Track quantityrequired | off | Leave inventory tracking off. With it on, Shopify reserves stock against every protected order and your warehouse sees protection as a backordered item. On the live store we inspected, the running count had reached -282. |
| This is a physical productrequired | off | Protection is not shipped. Left on, it enters shipping-rate and weight calculations and can change what the shopper is quoted for delivery. |
| Charge tax | off | Protection is generally not taxable, but this is a question for your accountant and your jurisdiction, not a default we can set for you. |
| Product visibility | hidden | Publish it to the Online Store so it can be added to a cart, but keep it out of collections, search, and sitemaps. Nobody should reach it by browsing. |
Discounts will eat your premium
A store-wide percentage discount applies to every line in the cart including protection, so a 20% promo quietly reduces the premium you collect while the cover you owe stays the same.
Shopify has no per-product "not discountable" flag. Scope your discounts instead: target a collection that contains your merchandise and not the protection product. If you use an upsell or bundling app, exclude the product there too — the store we inspected tags theirs exclude_rebuy for exactly that reason.
Prices and the variant ladder
This is the one place Shopify constrains the design, and it is worth understanding before you create the product.
A cart line takes its price from a variant. You cannot put an arbitrary amount on a standard cart line, so a protection product can only charge prices you have created variants for. That set of prices is the ladder.
What the incumbent does, and why yours can be better
The store we inspected runs a competing app with a 76-rung ladder: $0.20 steps up to $8.95, then $0.65 steps to $20.43, then $7.25 steps to $140.38. Every premium is rounded up to the next rung — a $200 cart quoted at 3% ($6.00) is charged $6.15, and a $625 cart quoted at $18.75 is charged $19.13.
Shoppers therefore pay slightly more than the rate card says, and the rungs coarsen as carts grow — a $7.25 gap at the top means a large cart can be charged several dollars above its quoted rate.
That coarsening is a choice rather than a limit: Shopify allows 2,048 variants per product, and 76 is nowhere near it. A finer ladder is available to anyone who wants one.
Covr handles this by making the rate card and the ladder agree deliberately, rather than letting the ladder distort the card. Set the store's rounding to the same step as your variants, and every quote lands exactly on a rung — the price the shopper is quoted is the price they are charged.
| Field | Type | Description |
|---|---|---|
| Even steps | recommended | Variants every 25¢ from $0.25 to $25.00 — 100 rungs — with the store's rounding set to Round up to 25¢. Covers a $800 cart at 3%, and the quoted price is always the charged price. |
| Fine steps | wider range | Every 5¢ to $100.00 is 2,000 rungs — still inside Shopify's 2,048 limit — and covers a $3,300 cart at 3% with the premium never more than 5¢ above the rate card. |
Building the ladder
Creating a few hundred variants by hand is not a good use of an afternoon. Covr ships a script that creates the product with the right settings and generates the ladder:
npx tsx ./scripts/shopify-protection-setup.mts --store yourshop.myshopify.com --step 25 --max 2500
It is a dry run until you add --apply, and it prints the price-to-variant map your theme snippet needs. It needs an Admin API token from a custom app with write_products.
If neither ladder is enough
A cart above your top rung has no price to charge. Give the rate card a final not covered band at that value, so large carts are declined honestly rather than being sold protection at the top rung and under-covered.
The alternative is a Shopify Function to set the line price directly, which removes the ladder entirely — but it requires an app, and it is not worth building until a store genuinely outgrows the rungs.
Order and fulfilment webhooks
Two webhooks, both created in Settings → Notifications → Webhooks. These are what book the premium and start tracking; the cart toggle above is cosmetic without them.
| Field | Type | Description |
|---|---|---|
| orders/createrequired | required | Records the order and books the premium. Send it to the URL below with JSON format and the latest API version. |
| fulfillments/createrequired | required | Registers the tracking number. Without it an order has no shipment, and a shopper cannot file a claim at all. |
https://www.covrprotection.com/api/webhooks/shopifySet SHOPIFY_WEBHOOK_SECRET to the store's webhook signing secret. Every delivery is verified with a constant-time HMAC check and fails closed — an unset secret rejects everything rather than trusting it.
Webhooks already pointed at the legacy www.getarrive.app URL keep working — existing stores need no change.
Protection is recognised by the line item title
Covr identifies the premium by matching the line item's title, word-bounded and case-insensitive, against: covr protection, covr shield, shipping protection, package protection, order protection, shipping insurance, or protection plan. Legacy arrive protection and arrive shield titles are still recognised.
Name your product so it contains one of these. A product called "Delivery Guarantee" ingests as an ordinary item: the order is recorded as unprotected, no premium is booked, and nothing warns you. "Shipping Protection" is the safe choice.
Expect a few 500s in the log
If a fulfilment arrives before its order, Covr answers 500 with {"retry": true} so Shopify redelivers rather than dropping the tracking number. That is intended back-pressure, not a fault.
Adding it to the cart
The only part that touches your theme. Quote the premium, show a toggle, and add or remove the matching variant.
// Called from your cart or checkout page. No secret key — this endpoint
// is scoped to your store's own domain by Origin.
const res = await fetch("https://api.covrprotection.com/v1/widget/quote", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
merchantId: "merch_2zta9l4uravokw42",
subtotal: cartSubtotalInDollars, // shippable items only
currency: "USD"
})
});
const { quote, reason } = await res.json();
if (!quote) {
// Above what this store covers, or protection is unavailable.
hideProtectionToggle();
} else {
showProtectionToggle(quote.premium.amount); // e.g. "4.35"
}// Map the quoted premium to the variant on your ladder. With rounding set
// to match the ladder step, the quote always lands exactly on a rung.
const variantId = LADDER[quote.premium.amount];
await fetch("/cart/add.js", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ items: [{ id: variantId, quantity: 1 }] })
});Re-quote whenever the cart changes
The premium is priced off the insurable subtotal, so adding or removing merchandise changes it. Re-quote and swap the variant, and discard a response that arrives after a newer one — a slow quote for an older cart must not overwrite a newer price.
Leave the toggle off by default
Covr returns toggleState: "unchecked". An optional paid add-on that is pre-selected for the shopper is the practice consumer-protection regulators object to. Pre-checking attaches far more often, and that is a conversation to have with your own counsel before you make it.
Exclude protection from the subtotal you send
Quote on the merchandise subtotal. Including the protection line makes each re-quote price the previous premium, and the number climbs every time the cart is touched.
Switchover checklist
For a store moving from another protection provider. The order matters: nothing here changes what shoppers see until the last step.
| Field | Type | Description |
|---|---|---|
| 1. Create the product | invisible | Hidden, inventory tracking off, not a physical product, with the variant ladder you chose. Nothing is live yet. |
| 2. Set the rate card | invisible | In Covr, on the store page under Underwriting. Match the incumbent's card exactly if you want premiums unchanged, and set rounding to your ladder step. |
| 3. Add the webhooks | safe | Orders start reaching Covr. Protection is still sold by the incumbent, so these arrive unprotected — that is expected and harmless. |
| 4. Verify with a test order | safe | Place a real order through the incumbent's toggle and confirm it appears in Covr with a shipment once fulfilled. |
| 5. Swap the toggle | live | Replace the incumbent's cart widget with yours. From here protection is sold by Covr and the premium is booked against your store. |
| 6. Leave the old app installed | for a while | Claims on orders it protected are still its responsibility. Uninstalling ends that cover for orders already in transit. |
Check the premium before and after
Place the same cart through both toggles and compare. If the numbers differ, the rate card or the ladder does not match the incumbent's — and it is far cheaper to find that on one test order than in a month's reconciliation.