# Referrals with Gumroad

Gumroad's unsigned ping and an access token: every sale is re-read from Gumroad before it counts.

Connect Gumroad and every sale, refund and dispute reaches the program,
credited to the partner whose link or offer code brought the customer.

**Gumroad's ping is not signed**, so nothing in it is ever counted. A ping only
tells Bolt Claw which sale to look at: the sale is read from Gumroad's own API
with your access token, and only what Gumroad returns is recorded. A ping for a
sale Gumroad does not know records nothing.

## Connect it

1. In Gumroad: **Settings**, **Advanced**, **Applications**: create an
   application, then **Generate access token**. Paste the token on the program's
   **Setup**, **Billing**, **Gumroad** card.
2. In Gumroad: **Settings**, **Advanced**, **Ping**: paste the endpoint URL from
   the card.
3. For refunds and disputes to be pinged too, subscribe the same URL to the
   `refund` and `dispute` resources with Gumroad's resource subscriptions API and
   your token.

## Pass the referral

Link to your product with the partner's code in `?ref=`; Gumroad keeps it with
the sale.

```html
<a href="YOUR_PRODUCT_LINK?ref=jane-20">Buy the course</a>
<!-- with the tag, append "?ref=" + BoltClawReferral.code() to your product link -->
```

The customer is your own id from a custom field, else Gumroad's purchaser id. A
recurring charge has its own sale and is a renewal.

## Refunds and disputes

A full refund reverses the commission. Gumroad's data cannot tell a partial
refund from a full one, so a partial refund is not recorded by itself: report it
through [`POST /v1/referrals/conversions`](https://boltclaw.ai/docs/api/referrals) with `refund_of`.
A dispute or chargeback reverses the sale in full.

## Offer codes

An offer code arrives as its name, so a sale made with a partner's code alone is
credited to them.

## Test mode

Each sale says whether it is a test purchase; a test sale is recorded as test
data.

## 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 (a Gumroad test purchase). 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-gumroad 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. -->