Referrals for WooCommerce: the plugin

Bolt Claw's WordPress plugin connects a WooCommerce shop to a referral program with no developer: the tag on your storefront, every paid order and refund reported, partner codes kept in step as WooCommerce coupons, and an optional "Invite your friends" card on the order-received page.

It replaces the webhook way. Use one or the other, not both: they name customers differently, and both would report each order.

Install

Download Bolt Claw Referrals (WordPress.org, or the zip from this page once it is published there) and upload it under Plugins, Add New, Upload Plugin. It needs WooCommerce 8.2 or later, WordPress 6.5 or later and PHP 7.4 or later.
In Bolt Claw, Settings, Developers, make a key with:
- conversions:write, always: orders and refunds are reported with it;
- referrals:read, for the coupon sync;
- referrals:embed, only for the order-received card.
In WordPress, WooCommerce, Settings, Bolt Claw: paste the key and the program's id (on its Setup tab), save, and press Test connection.

The key is kept in WordPress's options, never printed into a page, and sent only to https://api.boltclaw.ai/v1. You can rotate it in Bolt Claw at any time.

What it does

The tag. Bolt Claw's website tag on every storefront page, with the days a code is kept and, if you like, the friend's welcome bar. With a consent plugin that supports the WP Consent API, the code is kept only once the visitor accepts marketing cookies.
Orders. When an order reaches Processing or Completed, it is reported once as a sale, with the partner's code and click from the visitor's cookies, the order's coupons, the total in the currency's minor units, and its lines. Each order's event id is woo:<site>:<order id>, so a retry, or the order moving from Processing to Completed, never counts twice. A network failure is retried with the same id, for up to a day.
Refunds. Each refund is reported once, with refund_of naming the sale.
Coupons. Every hour, and when you press Sync now, each active partner code becomes a WooCommerce coupon at the program's friend's discount (percent, or a fixed amount off the cart; "once" is one use per customer). A coupon you made by hand with the same code is matched and keeps its own settings. A code switched off in Bolt Claw gets a past expiry date in WooCommerce; nothing is deleted. It reads GET /v1/referrals/programs/{id}/codes, which your own system can read too.
Invite your friends (off by default). On the order-received page of a buyer a partner referred, the in-app panel in thank-you mode, with the buyer's own link. The plugin mints a short-lived panel token on your server; the key never reaches the page. Switch on Invite after purchase on the program's Welcome tab, and add your shop's address to the panel's allowed origins (the In your app tab).

Check it works

Place a test order with the plugin's Test data switch on: it is recorded as test data, credited to the program's test partner and never payable. The program's Integration tab shows it under the setup status. Switch Test data off before you go live.

It replaces the webhook way. Use one or the other, not both: they name customers differently, and both would report each order.

Install

Download Bolt Claw Referrals (WordPress.org, or the zip from this page once it is published there) and upload it under Plugins, Add New, Upload Plugin. It needs WooCommerce 8.2 or later, WordPress 6.5 or later and PHP 7.4 or later.
In Bolt Claw, Settings, Developers, make a key with:
- conversions:write, always: orders and refunds are reported with it;
- referrals:read, for the coupon sync;
- referrals:embed, only for the order-received card.
In WordPress, WooCommerce, Settings, Bolt Claw: paste the key and the program's id (on its Setup tab), save, and press Test connection.

The key is kept in WordPress's options, never printed into a page, and sent only to https://api.boltclaw.ai/v1. You can rotate it in Bolt Claw at any time.

What it does

The tag. Bolt Claw's website tag on every storefront page, with the days a code is kept and, if you like, the friend's welcome bar. With a consent plugin that supports the WP Consent API, the code is kept only once the visitor accepts marketing cookies.
Orders. When an order reaches Processing or Completed, it is reported once as a sale, with the partner's code and click from the visitor's cookies, the order's coupons, the total in the currency's minor units, and its lines. Each order's event id is woo:<site>:<order id>, so a retry, or the order moving from Processing to Completed, never counts twice. A network failure is retried with the same id, for up to a day.
Refunds. Each refund is reported once, with refund_of naming the sale.
Coupons. Every hour, and when you press Sync now, each active partner code becomes a WooCommerce coupon at the program's friend's discount (percent, or a fixed amount off the cart; "once" is one use per customer). A coupon you made by hand with the same code is matched and keeps its own settings. A code switched off in Bolt Claw gets a past expiry date in WooCommerce; nothing is deleted. It reads GET /v1/referrals/programs/{id}/codes, which your own system can read too.
Invite your friends (off by default). On the order-received page of a buyer a partner referred, the in-app panel in thank-you mode, with the buyer's own link. The plugin mints a short-lived panel token on your server; the key never reaches the page. Switch on Invite after purchase on the program's Welcome tab, and add your shop's address to the panel's allowed origins (the In your app tab).