# Referrals with WooCommerce

A webhook with its own secret: paid orders and refunds, coupons credited from their code, every delivery claimed so it counts once.

Connect WooCommerce and every paid order, and every refund of one, reaches the
program, credited to the partner whose link or coupon brought the customer.

## Add a webhook

1. Open the program, **Setup**, **Billing**, **WooCommerce**, and copy the
   endpoint URL.
2. In WordPress: **WooCommerce**, **Settings**, **Advanced**, **Webhooks**, **Add
   webhook**. Topic **Order updated** (add a second one for **Order created**),
   API version 3, the URL as the delivery URL, and a **Secret** of your choosing.
3. Paste the same secret on the card.

WooCommerce signs each delivery, but with no timestamp, so Bolt Claw claims
every delivery's id before reading it: a delivery sent again records nothing.
WooCommerce's unsigned set-up ping is answered so the webhook stays on.

## Pass the referral to checkout

Save the code the tag kept on the order. The Bolt Claw plugin does it for you;
or add this to your theme or a small plugin:

```php
add_action('woocommerce_checkout_create_order', function ($order) {
  if (!empty($_COOKIE['bc_ref'])) $order->update_meta_data('boltclaw_ref', sanitize_text_field($_COOKIE['bc_ref']));
  if (is_user_logged_in()) $order->update_meta_data('boltclaw_customer_id', 'acme-user-' . get_current_user_id());
});
```

An order counts once, when it is `processing` or `completed` and paid, however
many updates it gets. The customer is your own id from the order meta, else the
WooCommerce customer id, else the order (for a guest).

## Refunds

A refund is read from the order's refunds as a running total, so a partial
refund takes back that share of the commission. WooCommerce has no dispute
event.

## Coupons

A coupon arrives as its code, so an order made with a partner's coupon alone is
credited to them.

## Test mode

WooCommerce's events do not say they are tests. For a staging store, add a second
WooCommerce integration and switch **Sandbox** on.

## Check it works

On the program's **Setup** tab, the **Billing** row of the setup status turns
`Connected` with the first verified event, and says when a delivery was refused
(nearly always the wrong secret). Then press **Send a test sale** to see a
click, a signup, a sale and a refund go through your rules with test data, or
make a real test purchase on a staging store. See [Connect your billing system](https://boltclaw.ai/docs/referral-setup)
for the whole setup status and what test data never does.

<!-- https://boltclaw.ai/docs/referral-billing-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. -->