Shipping insurance on Shopify: developer notes

This page is for the developer who maintains your theme and checkout. Setup in the Shopify admin, with pictures of each location, is in Shipping insurance on Shopify.

Checkout block

The in-checkout offer is the mulberry-shipping-insurance checkout UI extension. It requires Checkout Extensibility and does not render on checkout.liquid.

• Targets: purchase.checkout.cart-line-list.render-after (below the cart items) and purchase.checkout.shipping-option-list.render-after (below the shipping options). Each block anchors to its list; it can't be placed anywhere else.
• Settings (per block):
  • live (Enable shipping insurance): while off, the offer renders in the checkout editor preview only.
  • auto_add (Auto-add shipping insurance): adds the protection line when checkout loads, unless the customer declined protection on the cart page (see below).
• When it renders: only once Mulberry returns a premium for the cart. It renders nothing if shipping insurance isn't enabled on the account, the location isn't turned on, no customer rate is set, or the cart has no eligible products.

Cart page checkout button

The cart-page offer is the Shipping insurance button app embed in the Mulberry theme app extension. Its script loads on every storefront page, and it changes the page only where it finds your checkout button and only when Mulberry has turned the cart location on for your store.

• Finding your button: the embed's Checkout button selector setting, default button[name="checkout"], input[name="checkout"]. If your theme's checkout button doesn't match, set a selector that does. A selector that doesn't parse falls back to the default.
• What it replaces: it hides your button and inserts its own, copying your button's classes so it takes your theme's styling. The Mulberry buttons follow your button's disabled state, so a terms checkbox that disables your button disables them too. If the offer can't be loaded, your own button comes back unchanged.
• Checkout with Package Protection: adds the protection line, then goes to checkout. If the cart already carries protection at the current premium, it clicks your own button, so your theme's checkout handling runs as usual. If it had to change the cart, it goes straight to /checkout instead of submitting your cart form, because a theme cart form submits quantities by position and would misapply them to the changed lines. Code that runs on your cart form's submit doesn't run on that path.
• Checkout without Package Protection: removes any protection line and sets the cart attribute _shipping_insurance_declined to true. The checkout block's auto-add respects it, so the customer isn't re-protected in checkout.
• Wording: the button, the premium line, and the link text are configured by Mulberry per store.
• Console: problems are logged as browser console warnings starting with [Mulberry], for example when the offer can't be loaded or the selector doesn't parse.

The protection line item

Both locations, and the draft order block, add protection as its own line item carrying two properties: _shipping_insurance ("true") and _shipping_insurance_premium. The leading underscore keeps them out of view for customers. If your theme or other apps add, remove, or re-price cart lines, leave this line alone. Mulberry identifies it by _shipping_insurance.

Order lifecycle

Mulberry tracks each protected order through webhooks the app registers at install. Nothing on your side needs to call Mulberry.

• Recorded: the policy is recorded when the order is placed (orders/create).
• Shipment registered: the tracking number and carrier go to the insurer when the order is fulfilled (fulfillments/create). A fulfillment without a tracking number is skipped, so the shipment isn't registered until a fulfillment carries one.
• Voided: the policy is voided if the order is cancelled (orders/cancelled).

For the full list, see the Webhook catalog.

Troubleshooting

If the offer doesn't appear, check in this order:

1. Shipping insurance is enabled on the Mulberry account, with a customer rate.
2. The location is turned on for the store. Changes on Mulberry's side can take a few minutes to reach the storefront.
3. For checkout: the block is added, Enable shipping insurance is on, and the checkout is saved. The editor preview ignores that toggle, so an offer that previews but doesn't show live usually means it's off.
4. For the cart page: the Shipping insurance button embed is on and its selector matches your checkout button. Look for [Mulberry] warnings in the browser console.
5. The cart has at least one eligible product.