# Referrals with Polar

An endpoint signed with Standard Webhooks: paid orders, renewals and refunds, with discount codes credited from their text.

Connect Polar and every paid order, subscription renewal and refund reaches
the program, credited to the partner whose link or code brought the customer.
Polar signs deliveries with Standard Webhooks, with a timestamp.

## Add an endpoint

1. Open the program, **Setup**, **Billing**, **Polar**, and copy the endpoint URL.
2. In Polar: **Organization settings**, **Webhooks**, **Add Endpoint**. Paste the
   URL, format **Raw**, and select `order.paid` and `order.refunded`.
3. Paste the endpoint's secret on the card (shown when you add it, or one you set
   yourself). Both the current and the older form of Polar's secrets are
   accepted.

## Pass the referral to checkout

Set `metadata.boltclaw_ref` on the checkout link or session; Polar copies link
metadata to the order and the subscription.

```js
await polar.checkouts.create({
  products: ["prod_monthly"],
  externalCustomerId: "acme-user-10442",
  metadata: { boltclaw_ref: ref, boltclaw_customer_id: "acme-user-10442" },
});
```

The customer is your own id from the metadata, else Polar's `external_id` for
the customer, else Polar's customer id.

## Refunds

`order.refunded` carries the running total refunded, so a partial refund takes
back that share of the commission and a second refund adds to the first. Polar
has no dispute event.

## Discount codes

A discount code typed at Polar's checkout arrives as its text, so a sale made
with a partner's code alone is credited to them.

## Test mode

Polar's sandbox is its own environment and its events do not say they are tests.
Add a second Polar integration for the sandbox 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 in Polar's sandbox. 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-polar 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. -->