CH 00 · Medusa
Package protection for Medusa, in one package.
Install @covrprotection/medusa, add your Covr settings, and your checkout offers protection priced by Covr. Orders, shipments and claims take care of themselves. Covr never needs access to your code.
CH 01 · What it does
The whole integration, already built.
Everything a Medusa store needed to write by hand to sell Covr protection, tested end to end and kept up to date by Covr.
Priced by Covr, never by the browser
The protection line's price comes from Covr's quote on your server. It re-prices when the cart changes, is never discounted, and never needs shipping.
Every order reaches Covr
Orders, shipments and cancellations are saved first and retried until Covr confirms them, so a shopper who paid for protection is always covered.
Claims become draft orders
When Covr approves a claim, it creates a $0 replacement draft in your admin for your team to send. The same claim never makes two.
Address check, optional
Warns a shopper about an address the carrier may not deliver to, and never blocks the order.
Orders don't sit half-fulfilled
Protection isn't a parcel, so the plugin marks its line fulfilled when the order is placed. Your orders read fulfilled when the goods ship.
Fails open
If Covr can't be reached, checkout carries on without the offer and orders queue until Covr is back. Nothing in the plugin can stop a sale.
CH 02 · Install
Five steps for your developer.
About ten minutes, on your own backend.
- 01
Install the package
In your Medusa backend. Medusa 2.16 or later, Node 20 or later.
npm install @covrprotection/medusa - 02
Add it to your config
In medusa-config.ts.
plugins: [{ resolve: "@covrprotection/medusa", options: {} }] - 03
Add your Covr settings
As environment variables on your backend. Covr gives you the store slug and webhook secret; make the API key in your Covr console, Settings, API.
COVR_ENABLED=true COVR_MERCHANT_SLUG=your-store COVR_API_TOKEN=ak_live_... COVR_WEBHOOK_SECRET=whsec_... - 04
Run the migrations
Then deploy or restart as you normally do.
npx medusa db:migrate - 05
Check it's on
In your Medusa admin, Settings, Covr Protection shows what's still missing, whether orders go to Covr as test or live, and anything Covr hasn't received yet.
CH 03 · On your storefront
Two lines in your checkout.
The widget comes from your own Medusa backend, so there's no third-party script. It shows Covr's price with a checkbox, adds or removes the line, and shows Included when your store pays for protection.
<script src="https://YOUR-BACKEND/covr/protection-widget.js"
data-publishable-key="pk_..." defer></script>
<covr-protection cart-id="cart_..."></covr-protection>Once payment details are entered the checkbox locks, so the total never moves under a card that has been typed in.
Colours, corners and font come from CSS variables, like --covr-accent and --covr-radius.
Building your own? The same thing is two calls to /store/carts/:id/protection with your publishable key. The price is never taken from the request.
CH 04 · Options
Sensible defaults, a few switches.
| COVR_DEFAULT_ON | false to show the offer unticked. Default: ticked. |
| COVR_MODE | test or live. Set test while your payments run in sandbox, so Covr never invoices test orders. |
| COVR_LOG_ONLY | true for a dry run: logs what it would send and adds no line. |
| COVR_SALES_CHANNEL_IDS | Sales channels that offer protection. Default: your default sales channel. |
| COVR_EXCLUDED_SKUS | SKUs that aren't goods, like a card fee. Left out of the protected amount. |
| COVR_REPLACEMENT_SECRET | Switches on claim replacements. Share the same value with Covr. |
| COVR_ADDRESS_CHECK | true to check shipping addresses. |
US dollars only. Refunds aren’t sent to Covr, because Medusa’s refund event doesn’t say which lines were refunded. Building your own integration instead? The wire format is in the Medusa docs.
End of the list
Ask Covr for your store slug, and your developer can start today.
Want more than protection on Medusa? Covr Suite for Medusa adds discounts, email codes, State Limit, VIP and cart suggestions in one more package.