WooCommerce Integration Guide

The Loxa WooCommerce plugin is a turnkey integration that handles insurance display, cart management, and order data persistence — no custom frontend or backend code required. Install the plugin, configure your API credentials in WooCommerce settings, and Loxa Product Protection will appear on your product pages automatically.

You can see the plugin in action on our WooCommerce Test Store. All four insurance integration types are supported: Add-on, Inclusive, Hybrid Extension, and Hybrid Warranty. For details on what each type means, see the Generic Integration Guide.

---

Requirements

Requirement	Version
WordPress	5.8+
WooCommerce	7.0+
PHP	7.4+

The plugin is fully compatible with WooCommerce's High-Performance Order Storage (HPOS).

---

Installation

Download Plugin ZIP

Upload the plugin ZIP file through the WordPress admin:

1. Go to Plugins > Add New Plugin > Upload Plugin.
2. Select the ZIP file provided by Loxa and click Install Now.
3. Click Activate.

Alternatively, extract the ZIP to your wp-content/plugins/ directory and activate from the Plugins screen.

Updates

The plugin supports automatic updates via GitHub. Enter your GitHub Access Token in the plugin settings to receive update notifications in the WordPress admin.

---

Generate the Insurance Product

The plugin uses a hidden virtual product (loxa-insurance) as the line item template for insurance in the cart. You need to generate this product once after installation.

1. Go to WooCommerce > Settings > Integrations > Loxa Insurance.
2. Under Product Page, check the Generate Insurance Product checkbox.
3. Click Save changes.

This creates a virtual product with SKU loxa-insurance, base price 0.00, not visible in the catalog. The actual premium is set dynamically when insurance is added to the cart.

Required step

Insurance cannot be added to the cart until this product exists. If the product is missing, customers will not see insurance options on product pages.

---

Configure API Credentials

Navigate to WooCommerce > Settings > Integrations > Loxa Insurance and fill in the following fields under API Configuration:

Field	Description
Enable Loxa Insurance	Must be checked to activate the plugin
Loxa API Key	Your API key provided by Loxa (stored securely)
API Base URL	The Loxa API base URL, e.g. https://api.loxacover.com/test/2026-02
API Endpoint Path	The insurance information endpoint, e.g. /products/insurance-information
Analytics API Base URL	Analytics endpoint base URL (optional)
Analytics API Key	Analytics API key (optional)
GitHub Access Token	Personal access token for in-WP-admin auto-updates from GitHub (optional)

HMAC secret is auto-generated

The HMAC secret used to sign premiums is generated automatically when the plugin is activated and never has to be set manually. You'll see it on the settings page as a masked panel with a Regenerate HMAC Secret button — only use that if you have a specific reason to rotate it (e.g. a suspected leak). Rotating invalidates any in-flight signed quotes that haven't been added to a cart yet.

---

How It Works

Once installed and configured, the plugin handles the full insurance lifecycle automatically:

┌─────────────────────────────────────────────────────────────────────┐
│  PRODUCT PAGE (browser)                                             │
│                                                                     │
│  1. Page loads → PHP injects product data and settings as JSON      │
│  2. JS calls server-side proxy (wp-admin/admin-ajax.php)            │
│  3. Proxy adds API key + forwards to Loxa API                      │
│  4. Proxy attaches HMAC signatures to each plan in the response     │
│  5. JS renders insurance badge and sidebar from API data            │
│  6. Customer selects a plan → JS injects insurance data into form   │
│  7. Customer clicks "Add to Cart"                                   │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│  SERVER (WooCommerce)                                               │
│                                                                     │
│  8. Cart handler validates HMAC signature on the premium            │
│  9. Cart handler adds virtual insurance product to cart              │
│  10. Insurance JSON stored as cart item meta (loxa_insurance_data)   │
│  11. Existing insurance for same parent product is replaced          │
│  12. Insurance quantity synced with parent product quantity          │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│  CHECKOUT → ORDER                                                   │
│                                                                     │
│  13. Plugin copies insurance data to order item meta                │
│  14. Meta key: _loxa_insurance_data (accessible via REST API)       │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│  ORDER PROCESSING                                                   │
│                                                                     │
│  15. Loxa pulls orders via WooCommerce REST API                     │
│  16. Loxa processes policies from the insurance data                │
│  17. Customer receives welcome email from Loxa                      │
└─────────────────────────────────────────────────────────────────────┘

---

What the Plugin Handles Automatically

You do not need to build any of the following — the plugin takes care of it:

• Badge rendering — all four integration types (addon, inclusive, hybrid extension, hybrid warranty) with Loxa-branded badges and styling
• Insurance sidebar — terms, legal disclaimers, plan selection, and the "Details" / "What's included?" overlay
• Variant re-pricing — when a customer selects a different product variation (size, colour, etc.), the plugin re-fetches insurance pricing at the new price point
• HMAC price verification — premiums are signed server-side and verified on add-to-cart to prevent price tampering
• Cart line item management — insurance is added as a separate line item with the correct price; duplicates are replaced; removing the insured product automatically removes the linked insurance
• Quantity synchronisation — insurance quantity is locked and automatically synced with the parent product quantity
• Coupon exclusion — insurance line items are automatically excluded from coupon discounts
• Second-chance mechanism — optionally intercepts the add-to-cart click if the customer hasn't selected insurance and shows the sidebar as a reminder (configurable in settings)
• Quote-to-order persistence — insurance data follows the order through WooCommerce's checkout and is accessible on the completed order via the REST API
• Compliance — opt-out flows for inclusive insurance are built in per Compliance Rules
• Catalog visibility — the insurance virtual product is hidden from the shop catalog and search results

---

Order Processing

Unlike a custom integration where you would POST orders to the Loxa Orders API, the WooCommerce plugin works the other way around — Loxa pulls orders from your WooCommerce REST API.

How it works

1. When a customer completes checkout with insurance, the plugin saves the full insurance data as order item meta.
2. The meta key _loxa_insurance_data is exposed via the WooCommerce REST API on order line items.
3. Loxa periodically calls GET /wp-json/wc/v3/orders on your WooCommerce instance to retrieve new orders containing insurance.
4. Loxa processes the insurance policies and the customer receives their welcome email and policy documents.

What you need to provide

To enable Loxa to pull orders, you need to create WooCommerce REST API keys:

1. Go to WooCommerce > Settings > Advanced > REST API.
2. Click Add key.
3. Give it a description (e.g. "Loxa").
4. Set the User to an administrator account.
5. Set Permissions to Read.
6. Click Generate API key.
7. Share both values with Loxa:

Credential	Description
Consumer Key	Identifies the API client (starts with ck_)
Consumer Secret	Authenticates API requests (starts with cs_)

Copy the keys immediately

The Consumer Secret is only shown once when generated. If you lose it, you will need to revoke the key and create a new one.

Keep these credentials secure

These values grant read access to your order data. Share them with Loxa through a secure channel — never send them over plain email or commit them to version control.

You do not need to POST orders to Loxa

The WooCommerce plugin does not require you to call the POST /orders endpoint. Loxa reads orders directly from your WooCommerce REST API. This means there is no additional backend development required on your side.

Insurance data on order items

When Loxa retrieves an order, each insurance line item includes the _loxa_insurance_data meta:

Example order line items (GET /wp-json/wc/v3/orders/:id)

{
  "line_items": [
    {
      "name": "3 Seater Sofa",
      "sku": "sofa-3-seater",
      "quantity": 1,
      "price": 1299.99
    },
    {
      "name": "Loxa Insurance",
      "sku": "loxa-insurance",
      "quantity": 1,
      "price": 101.99,
      "meta_data": [
        {
          "key": "_loxa_insurance_data",
          "value": {
            "code": "LDF5-20260119-23",
            "name": "Product Protection",
            "term": "5",
            "premium_raw": "101.99",
            "sum_insured": "1299.99",
            "signature": "a1b2c3d4",
            "impression_guid": "f1c7bd11-bc26-4840-945f-ae630f3cda96",
            "parent_sku": "sofa-3-seater",
            "parent_cart_key": "6512bd43d9caa6e02c990b0a82652dca",
            "parent_name": "3 Seater Sofa"
          }
        },
        {
          "key": "_loxa_insurance_code",
          "value": "LDF5-20260119-23"
        }
      ]
    }
  ]
}

Field	Description
code	The insurance plan code (used by Loxa to identify the policy)
name	Plan display name
term	Coverage term in years
premium_raw	Premium amount charged to the customer
sum_insured	The product price at time of purchase
signature	HMAC signature used for price verification
parent_sku	SKU of the product being insured
parent_name	Name of the product being insured
parent_cart_key	Internal cart key linking insurance to its parent
impression_guid	Analytics tracking identifier

Cancellations

Loxa handles cancellation tracking once orders are pulled. If you need to notify Loxa of cancellations outside of the standard flow, you can use the Cancellations endpoint directly.

---

Theme Compatibility

The plugin is designed to work with standard WooCommerce themes. It injects anchor elements into the product page using WooCommerce's woocommerce_single_product_summary hook and renders the sidebar in wp_footer.

Theme	Status	Notes
Storefront (and Storefront-based)	Works out of the box	Standard WooCommerce hooks are present
Block themes	Works out of the box	Anchor elements injected via hooks
Custom themes	May need config	See below

For custom themes that restructure the product page or use non-standard selectors for the add-to-cart button, quantity input, or variant pickers, you can configure the relevant CSS selectors in the plugin settings.

If your theme does not render the standard WooCommerce product summary hooks, you can manually add the anchor elements to your template:

<span id="loxa-woocommerce-inclusive-anchor" data-loxa-woocommerce-anchor="inclusive"></span>
<span id="loxa-woocommerce-addon-anchor" data-loxa-woocommerce-anchor="addon"></span>

---

Admin Configuration Reference

All settings are located at WooCommerce > Settings > Integrations > Loxa Insurance.

Product Page Settings

Field	Default	Notes
Add to Cart Button Selector	.single_add_to_cart_button	CSS selector for the ATC button
Variant Selector	(empty)	Optional CSS selector for custom variant pickers
Quantity Selector	input[name="quantity"]	CSS selector for the quantity input
Buy Now Button Selector	(empty)	Optional; for express checkout buttons that submit the product form

Behavior

Field	Default	Notes
Sidebar Position	right	left or right
Second Chance on Add to Cart	Off	Shows sidebar if customer clicks ATC without selecting insurance
Variant Change Delay	0	Debounce in ms before re-fetching insurance on variant change
Variant ID Source	auto	How to detect the selected variant; auto covers most themes
Exclusion Tags	(empty)	Comma-separated category or tag names to exclude from insurance
Prices Exclude VAT	Off	Enable if catalog prices are ex-VAT; applies 20% uplift for insurance pricing
Category Override	Off	Passes a category override to the Loxa API based on product tags prefixed with loxa-. Must be agreed with Loxa before use.

Appearance

Field	Default	Notes
Theme Mode	light	light, dark, or midnight
Font	branded	branded (Neulis Sans) or inherit (your store's theme font)
Custom CSS	(empty)	Additional CSS applied to the insurance badge and sidebar

Developer

Field	Default	Notes
Debug Mode	Off	Enables [Loxa] browser console logs (requires manage_woocommerce capability)
Dummy Payload Mode	disabled	Uses local test data instead of live API calls — options: addon, inclusive, hybrid_warranty, hybrid_extension
Disable Main Flow	Off	Disables all automatic listeners; for fully custom JS integrations

---

Troubleshooting

Insurance badges are not appearing on product pages

Check the following:

1. Plugin is enabled — go to WooCommerce > Settings > Integrations > Loxa Insurance and confirm the "Enable" checkbox is checked.
2. API credentials are configured — verify the API key and base URL are filled in. The HMAC secret is auto-generated, so it should always be present unless something has gone wrong.
3. Product is insurable — the Loxa API must return insurable: true and active: true for the product. Enable debug mode to see [Loxa] console logs.
4. Anchor elements exist — the plugin injects anchors via the woocommerce_single_product_summary hook. If your theme doesn't fire this hook, add the anchors manually:

   <span id="loxa-woocommerce-inclusive-anchor" data-loxa-woocommerce-anchor="inclusive"></span>
   <span id="loxa-woocommerce-addon-anchor" data-loxa-woocommerce-anchor="addon"></span>
   

5. Product is not excluded — check that the product's categories or tags don't match the Exclusion Tags setting.

Insurance is not being added to the cart

Check the following:

1. Insurance product exists — check the "Insurance Product ID" field in settings. If empty, check "Generate Insurance Product" and save.
2. HMAC secret is present — the secret is auto-generated on plugin activation. The HMAC panel on the settings page shows a masked preview when one is set. If the panel says no secret is configured (rare), click Regenerate HMAC Secret to create one.
3. Check browser console — enable debug mode and look for [Loxa] errors in the browser console.

Express checkout buttons (Google Pay, Apple Pay, PayPal) bypass insurance

Express checkout buttons on the product page initiate their own payment flow directly with the payment provider, bypassing the standard add-to-cart form. Insurance data is never submitted through these flows.

Options:

• Disable express checkout buttons on product pages — customers who add to cart normally will always be offered insurance
• Use the Buy Now Button Selector config if the button submits through the product form
• Express checkout on the cart and checkout pages is unaffected since insurance is already in the cart

Insurance prices don't update when selecting a product variation

1. Check the Variant Selector — if your theme uses custom dropdowns or swatches, you may need to set the CSS selector in settings.
2. Adjust the Variant Change Delay — if prices flash or re-fetch too quickly, increase the debounce delay (e.g. 200).
3. Check the Variant ID Source — try switching between auto, form, and url to match how your theme reports the selected variation.

---