# Referrals with Shopify

Webhooks with the store's own key and no app: paid orders, refunds and disputes, with partner links credited from the landing page.

Connect Shopify with no app to install: every paid order, refund and dispute
reaches the program, credited to the partner whose link or discount code brought
the customer. A partner link works with no code on the shop at all.

## Add the webhooks

1. Open the program, **Setup**, **Billing**, **Shopify**, and copy the endpoint URL.
2. In Shopify admin: **Settings**, **Notifications**, **Webhooks**, **Create
   webhook**, once for each of `orders/paid`, `refunds/create` and
   `disputes/create`, format JSON, with the URL.
3. At the bottom of that page Shopify shows the key your webhooks are signed
   with, one per store. Paste it on the card.

Shopify signs each delivery with no timestamp, so every delivery's id is claimed
before it is read: a delivery sent again records nothing.

## Pass the referral

Nothing to add for links: a partner link's `?via=` stays in the order's landing
page address, and Bolt Claw reads it from there. You can also put the code in a
cart attribute (Buy It Now and accelerated checkouts may drop those, which is
why the landing address is read too):

```js
fetch("/cart/update.js", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ attributes: { boltclaw_ref: BoltClawReferral.code(), boltclaw_customer_id: "acme-user-10442" } }),
});
```

The customer is your own id from the cart attributes, else Shopify's customer
id. A subscription renewal arrives as a new order.

## Refunds and disputes

A refund counts its successful refund transactions, so a partial refund takes
back that share of the commission. A dispute (Shopify Payments) reverses the
sale in full.

## Discount codes

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

## Test mode

Each order says whether it is a test (Shopify's test payments, or a development
store), and a test order is recorded as test data; its refunds and disputes
follow it.

## 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 with Shopify's test payments. 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-shopify 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. -->