# Referrals for WooCommerce: the plugin

One plugin: the tag, every order and refund reported once, partner codes as coupons, an invite on the order page.

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](https://boltclaw.ai/docs/referral-billing-woocommerce). Use one or the
other, not both: they name customers differently, and both would report each order.

## Install

1. 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.
2. 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.
3. 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.

<!-- https://boltclaw.ai/docs/referral-woocommerce as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->