Referrals

Run a referral or affiliate program and tell Bolt Claw when a referred customer signs up, pays, or asks for their money back. Bolt Claw works out which partner referred them, what that partner earned, holds the commission through your refund window, and takes it back if the sale is refunded.

Three jobs, and they belong on separate keys:

• Reporting what happened — POST /v1/referrals/conversions — needs conversions:write. The Referral tracking preset is exactly that one scope: the key your checkout server holds, which can read nothing. Report from your server, never from a browser: anything shipped to a visitor can be read by that visitor.
• Running the program — programs, partners, commissions, payouts and statistics — needs referrals:read (and referrals:write to change anything). The Referrals preset is those two.
• Showing your own users their referrals — a referral panel inside your product, or your own screen built on the same data — needs referrals:embed alone. The Referral panel preset is that one scope: the key your own server holds to mint a panel session for a signed-in user and to create the referrers behind it, which can touch no program, partner or payout. Never put it in a browser or an app.

Every amount is an integer in the currency's minor units — cents for USD, yen for JPY — in a field ending _minor (the conversion request's amount is the one exception to the suffix, and the same unit). Responses are the same objects the dashboard shows, in snake_case; lists are cursor-paginated, newest first, 50 to a page by default and at most 100.

This API is the merchant's side of a program. It never carries a partner's account id or email (a partner's email appears only if they chose to share it with your program), and a partner never sees your account either — they know you as the program's name. An id that is not on your account is a 404, whatever it is.

Referrers: your own users

A referrer is one of your users who holds a referral link, usually through the referral panel. They are not partners: they have no Bolt Claw account, never apply, and are not counted against the partner allowance (referrers have their own, maxRefReferrers, Free 100,000). You identify one by your own id for them, external_id, which is 1 to 200 printable characters and must be percent-encoded in a path. GET .../referrers/{external_id} returns exactly what the panel shows that person, so your own screen can show the same thing.

Rewards that are not cash, and the friend's side

A reward rule can give a free period, credit, a perk, a gift card or (to the friend) a discount, as well as a commission; it can reward the person who shared (beneficiary: promoter) or the friend who arrived through the link (referee). What such a rule gives is a grant, which you give in your own system and record with POST /v1/referrals/grants/{id}/fulfil, or which Bolt Claw gives through your Stripe with a restricted key. See Rewards that are not cash, The friend's welcome and Stripe codes and credits.

Carrying the referral to your checkout

A partner's link, https://boltclaw.ai/r/<code>, sends the visitor to your product URL with ?via=<code> added. Put this tag on your site to keep that code until checkout:

<script src="https://boltclaw.ai/referrals/v1.js" defer
        data-cookie-days="30" data-attribution="last" data-param="via"></script>

It stores the code in a first-party cookie on your domain, bc_ref (mirrored to localStorage, for in-app browsers that drop cookies). It makes no network request of any kind and sets nothing on boltclaw.ai. It gives you:

• BoltClawReferral.code() — the code, or null.
• BoltClawReferral.attach(form) — adds a hidden boltclaw_ref field to a form.
• BoltClawReferral.clientReferenceId() — the code for Stripe Checkout's client_reference_id, or undefined.

v1.js never changes behaviour under you. v2.js does everything it does, the same way, and adds what you ask for: the friend's welcome banner, Stripe Payment Links, codes from another tool's links and a consent mode. With none of those switched on it, too, makes no request. See The friend's welcome.

event_id makes retries safe

Report every event with an id of your own that never changes — an order id, a refund id. The same event_id sent again returns 200 with "duplicate": true and the conversion as it was first recorded, and changes nothing: no second commission, no second refund. So after a timeout, retry with the same id; never mint a new one. An event_id is unique per program.

A 409 CONFLICT here means another event for the same customer was being recorded at that very moment, and nothing was recorded for yours. Send the same request again, with the same event_id. A new id is a new conversion, and a new conversion can pay a partner twice for one sale.

Who gets the credit

In order: a referral.code of this program, then an active discount_code of this program, then whoever the customer is already attributed to. Under first-click, a customer once attributed stays with that partner. Under last-click, a newer code moves the customer to its partner for that event and the ones after it; what was already recorded keeps its commission either way.

A conversion is recorded whether or not anyone referred it ("attributed": false). A partner earns only while their membership is approved: a pending, rejected or banned partner's conversions are recorded and earn nothing.

Commissions, holds and refunds

A commission is a percentage of the sale (rounded down to the minor unit) or a flat amount, as the program's reward rules say, and either once per customer, for a number of months, or for life. A program can pay a different rate per product, price, plan or interval, more to a group or level of partners, its own rate to one partner, a bonus at a milestone, and a ceiling per customer or per month: send a sale's items and each line is matched to the most specific rule, and every commission says why it is that amount (basis_text). It starts pending for the program's hold period and becomes approved when the hold ends, unless it has been flagged for review.

A refund takes back the same share of the commission as the share of the sale refunded, against the running total refunded: two refunds of 30% each take back 60%. A full refund, or a dispute, takes back all of it (reversed). If the commission had already been paid out, the money has left, so a negative commission is recorded instead and comes off the partner's next payout.

Stripe

If your checkout runs on Stripe, you can connect your Stripe account from the dashboard instead (in one click with the Bolt Claw Stripe App, or with a webhook and its signing secret), and paid checkouts, subscription invoices, refunds and disputes are reported for you. Eleven other billing systems connect the same way, from Paddle and Shopify to RevenueCat and Gumroad: see Connect your billing system. Each one's conversions carry it as their source. Put the code in the Checkout Session's client_reference_id (or metadata.boltclaw_ref); for a subscription, also in subscription_data.metadata.boltclaw_ref, so the first invoice is credited whichever event Stripe delivers first. To tie Stripe customers to the ids you use here, set metadata.boltclaw_customer_id to your own customer id.

A subscription invoice carries its lines, so a rule for one product, price or billing interval applies to it with nothing else to set up (each line's share of what was paid, tax and invoice discounts spread across the lines). When Stripe sends only some of an invoice's lines, the invoice is matched as a whole. A one-time Checkout carries no lines: set metadata.boltclaw_product, metadata.boltclaw_price or metadata.boltclaw_plan on the session and the sale is matched as that one line.

Refunds are matched to their payment by payment intent. On Stripe API versions from 2025-03-31, an invoice event no longer carries one, so select invoice_payment.paid too (the Stripe App receives it for you): it links the invoice to the payment that paid it, and a refund of a subscription invoice is then matched whichever event arrives first. Without it, report such a refund here with refund_of set to the invoice.paid event's id.

The setup status, and test data

GET /v1/referrals/programs/{id}/integration-status answers, part by part (the website tag, billing, signups, sales, codes, the in-app panel and the friend's welcome), whether each is connected, warnings or not_connected, with one sentence saying what was seen and one saying what to do, and lists every connected billing system without its credential. It counts live data only. POST .../integration-status/tag-check fetches the product page once to look for the website tag.

Test data is recorded with "test": true on a conversion, POST /v1/referrals/programs/{id}/test-sale runs a whole test sale (a click, a signup, a sale with two items, a partial refund) and answers every step, and a test-mode or sandbox event from a billing system is test data too. Test data is credited to the program's own test partner whoever's code it carried, is never paid, never counted and emails nobody, and reaches only webhook endpoints with test_events on. Conversions, commissions and rewards carry test. A test event_id and a live one, or a test customer and a live one, never collide. DELETE /v1/referrals/programs/{id}/test-data deletes it all and touches nothing live. Connect your billing system has the whole picture.

A click your own server saw. For a partner's link that opens straight on your site, POST /v1/referrals/clicks with the link's code and what your server saw (ip, user_agent, referrer) records it as a click on boltclaw.ai/r/<code> would be: hashed and classed, never stored, counted toward the click allowance, and earning nothing by itself.

The onboarding answers. A program takes setup_payments (how you take payments), setup_signups (how people sign up) and audience_eu_uk, and returns them as setup; they choose the steps the dashboard lists.

What stays in the dashboard

On purpose, and permanently for this API:

• Payout exports. A payout file carries partners' PayPal, Wise or bank details, for money you owe them. It is downloaded by a signed-in person and audited; a key cannot fetch one.
• Connecting a billing system. Every integration needs a credential pasted or shown once (a signing secret, a read-only key, the Stripe App's install), and a secret never passes through an API call or a chat with a model. A credential goes in once and never comes back out. The setup status reads every integration, without its credential.
• Everything partner-side. Applying, links, codes, placements and payout details belong to the partner's own session. This API is yours.

Also dashboard-only today: invites, discount codes, links, the Stripe connection, pausing or archiving a program, banning a partner, approving a commission early, creating or cancelling a payout batch, and the fraud review queue.

Errors here

The usual codes, and what they mean here:

Operations

POST /v1/referrals/conversions

Report a conversion

Scope conversions:write. Accepts Idempotency-Key. Another workspace's answers 404.

A lead, sale, refund or dispute. event_id is YOUR id for the event and the idempotency key: to retry, send the SAME event_id. A repeat answers HTTP 200 with duplicate: true and changes nothing. A 409 CONFLICT means another event for this customer was being recorded at that moment: send the same request again. Never make up a new event_id to retry: that is a new conversion, and can pay a partner twice.

A repeat answers with the conversion as it was first recorded. A lead or a sale needs customer; a sale needs amount and currency; a refund or dispute needs refund_of (the sale's event_id), and a refund its amount. Amounts are integers in minor units. Needs conversions:write, which does nothing else, so it can sit in a checkout server.

Request body (required)

{
  "program_id": "3f8c1e42-9b7a-4d61-a0f5-2c9e1b7d4a83",
  "event": "lead",
  "event_id": "<event_id>"
}

Answers

Report a signup — answers 201

event_id is your own id for the event and makes the call safe to retry: reporting the same one again answers 200 with duplicate: true and changes nothing.

curl -X POST https://api.boltclaw.ai/v1/referrals/conversions \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "program_id": "4e8a2b71-39cd-4f06-8a52-71b0d4c9e283",
  "event": "lead",
  "event_id": "signup-10492",
  "customer": {
    "id": "cus_10492"
  }
}'

const res = await fetch("https://api.boltclaw.ai/v1/referrals/conversions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "program_id": "4e8a2b71-39cd-4f06-8a52-71b0d4c9e283",
    "event": "lead",
    "event_id": "signup-10492",
    "customer": {
      "id": "cus_10492"
    }
  }),
});

// 201
const data = await res.json();

GET /v1/referrals/programs

List programs

Scope referrals:read.

The workspace's referral programs.

Parameters

Answers

POST /v1/referrals/programs

Create a program

Scope referrals:write. Accepts Idempotency-Key. Can make something publicly visible.

A referral program with a public join page partners apply through. Values are checked here: an https product_url, cookie_days from 1 to 365, a known attribution_model, payout_schedule and join_mode (400). The plan sets how many programs an organisation may run.

Request body (required)

{
  "name": "<name>",
  "product_url": "<product_url>"
}

Answers

Create a referral program — answers 201

name and product_url are the only required fields; everything else takes a sensible default you can change later.

curl -X POST https://api.boltclaw.ai/v1/referrals/programs \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme partners",
  "product_url": "https://example.com"
}'

const res = await fetch("https://api.boltclaw.ai/v1/referrals/programs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Acme partners",
    "product_url": "https://example.com"
  }),
});

// 201
const data = await res.json();

GET /v1/referrals/programs/{id}

Read a program

Scope referrals:read. Another workspace's answers 404.

The program, its join link and how many partners are waiting for a decision.

Parameters

Answers

PATCH /v1/referrals/programs/{id}

Update a program

Scope referrals:write. Another workspace's answers 404. Can make something publicly visible.

Changes the fields you send; a field left out keeps its value. Values are checked as on create.

Sending terms saves new program terms and raises terms_version: every partner must accept the new version before their next payout. An AI assistant's key is asked first when the body carries terms, unless your organisation lets assistants save terms without asking. Draft terms from the program's own settings with POST /v1/referrals/programs/{id}/terms/draft.

Parameters

Request body (required)

Answers

GET /v1/referrals/programs/{id}/partners

List a program's partners

Scope referrals:read. Another workspace's answers 404.

Partners by their name in this program, with all-time stats. An email appears only where the partner chose to share it. q keeps the partners whose display name contains it, ignoring case.

Parameters

Answers

POST /v1/referrals/partners/{id}/approve

Approve a partner

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Approves an application. The partner gets their links, starts earning, and is emailed at once. Approving a partner who is already approved changes nothing and emails nobody, so a retry is safe. Takes no body.

Parameters

Answers

POST /v1/referrals/partners/{id}/reject

Reject a partner

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Rejects an application. Takes no body.

Parameters

Answers

GET /v1/referrals/programs/{id}/commissions

List a program's commissions

Scope referrals:read. Another workspace's answers 404.

Commissions, newest first, each with its conversion and partner.

Parameters

Answers

POST /v1/referrals/commissions/{id}/adjust

Adjust a commission

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Adds an adjustment on the same conversion, never an edit in place: a signed amount in minor units (not 0) and your reason, which is recorded in the activity log.

Parameters

Request body (required)

{
  "amount_minor": 1,
  "reason": "<reason>"
}

Answers

GET /v1/referrals/programs/{id}/payouts

List a program's payouts

Scope referrals:read. Another workspace's answers 404.

Payouts, newest first. Payout details and export files stay in the dashboard.

Parameters

Answers

POST /v1/referrals/payouts/{id}/paid

Mark a payout paid

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

You paid outside BoltClaw; this records it with your reference. Send expected_minor (the amount you were shown): if refunds have moved the total since, nothing is marked and the answer is 409 CONFLICT naming the new figure. Recorded in the activity log.

Parameters

Request body (required)

{
  "reference": "<reference>"
}

Answers

GET /v1/referrals/programs/{id}/payout-providers

List a program's payout providers

Scope referrals:read. Another workspace's answers 404.

The payout accounts this program can pay through, by name and state: your own PayPal, Wise, Stripe, Tremendous, Trolley or Tango account, or your own payout system (webhook). Never a credential. Connecting or disconnecting one is done in the dashboard, on the Payouts tab.

Parameters

Answers

POST /v1/referrals/payout-providers/{id}/test

Test a payout provider connection

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Makes one harmless read at the provider with the stored credential and records whether it works, and why not. Moves no money.

Parameters

Answers

GET /v1/referrals/programs/{id}/payout-settings

Get a program's payout settings

Scope referrals:read. Another workspace's answers 404.

How the program pays: its provider, the providers a promoter may choose among, the schedule, sending on a schedule (available only after a legal review), and the largest payout sent without a second confirmation.

Parameters

Answers

PATCH /v1/referrals/programs/{id}/payout-settings

Change how a program pays

Scope referrals:write. Another workspace's answers 404.

Choose the provider that pays promoters, the providers they may choose among (each must be connected), the day of the month a monthly batch is made, and an optional largest payout. auto_send can be turned on only once BoltClaw allows it, after a legal review; until then a person sends every batch. Recorded in the activity log.

These are a send's own rails, so a key that is not an AI assistant's needs referrals:payouts as well as referrals:write, as sending does; an assistant needs a person's approval.

Parameters

Request body (required)

Answers

GET /v1/referrals/programs/{id}/payout-preview

See who is ready to be paid

Scope referrals:read. Another workspace's answers 404.

Ready to pay, before any batch: per currency and provider, the promoters a batch would pay and the provider's estimated fees (charged by that provider to your account; BoltClaw charges nothing), and every promoter who would wait, with why: payout details changed in the last 48 hours, payouts locked, an open fraud flag, below your minimum, or details the provider needs that they have not given yet.

Parameters

Answers

POST /v1/referrals/programs/{id}/payout-batches

Make a payout batch

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Turns every approved commission that can be paid into draft payouts, one per promoter per currency, each with the provider that pays it. Nothing is sent: the batch waits for send, a file export, or marking each payout paid. Below the minimum, negative, flagged or held waits for the next batch.

Parameters

Answers

GET /v1/referrals/payout-batches/{id}

Get a payout batch, ready to send

Scope referrals:read. Another workspace's answers 404.

Every payout in the batch with its provider, whether it can be sent now (and why not), the provider's estimated fee, and how it went once sent. sendable is exactly what send would send: its payout ids, its totals per currency (send them back as expected_totals), and the payouts large enough to need confirming by name.

Parameters

Answers

POST /v1/referrals/payout-batches/{id}/send

Send a payout batch through your payout provider

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Pays the batch's payouts from YOUR provider account (PayPal, Wise, Stripe, Tremendous, Trolley, Tango) or asks your own payout system for each (referral.payout.requested). BoltClaw never holds the money. expected_totals must equal what the batch would send now (GET /referrals/payout-batches/{id}, sendable.totals), or nothing is sent; a payout in sendable.large must be named in confirm_large. Each payout is sent once, with an idempotency key made from its id; results arrive as referral.payout.* events.

Needs referrals:payouts, the key your own payout server holds, or an AI assistant with a person's approval: referrals:write alone never sends money. Recorded in the activity log.

Parameters

Request body (required)

{
  "expected_totals": {}
}

Answers

POST /v1/referrals/payout-batches/{id}/cancel-auto-send

Stop a scheduled send

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Stops a batch that was going to be sent by itself after its 24-hour notice. A stop: it always works, and the batch stays for a person to send. Recorded in the activity log.

Parameters

Answers

GET /v1/referrals/payouts/{id}

Get a payout

Scope referrals:read. Another workspace's answers 404.

One payout, with how it was sent and what its provider said (delivery).

Parameters

Answers

GET /v1/referrals/payouts/{id}/details

Read where a requested payout goes

Scope referrals:payouts. Another workspace's answers 404.

For YOUR OWN payout system, after referral.payout.requested: the promoter's own payout details for this one payout, while it waits to be paid. Refused (409) while the promoter's details changed in the last 48 hours or they locked their payouts. Every read is recorded in the activity log, as a payout export is. Needs referrals:payouts, which an AI assistant's key never holds.

Parameters

Answers

POST /v1/referrals/payouts/{id}/result

Report what your payout system did

Scope referrals:payouts. Accepts Idempotency-Key. Another workspace's answers 404.

For YOUR OWN payout system: the payout was paid (with your reference), failed or returned (with a reason). Failed and returned put its commissions back in Ready to pay. The same answer again changes nothing; a payout already settled otherwise is 409. Needs referrals:payouts, which an AI assistant's key never holds.

Parameters

Request body (required)

{
  "status": "paid"
}

Answers

GET /v1/referrals/programs/{id}/tax

Get a program's tax settings

Scope referrals:read. Another workspace's answers 404.

Whether this program's payouts wait for a tax form (tax_forms) or for the promoter's own invoice (invoice_required), and whether you issue self-billed invoices for your EU and UK business promoters (self_billing). Also whether your own tax details are complete, never the details themselves (your EIN, legal name and addresses are entered in the dashboard), and the table of which payout providers count toward your 1099-NEC, each with why and its source. BoltClaw prepares these forms; it does not give tax advice or file anything for you. See Tax forms and 1099s.

Parameters

Answers

PATCH /v1/referrals/programs/{id}/tax

Change whether a program's payouts wait for tax forms or invoices

Scope referrals:write. Another workspace's answers 404.

Send only what you change. tax_forms: off; us_only (a US person needs a W-9, and anyone else signs a short statement that they are not a US person); or all (everyone needs a W-9, W-8BEN or W-8BEN-E). A promoter whose required form is missing, expired or replaced waits in Ready to pay until they sign. invoice_required: each payout waits for the promoter's own invoice (a promoter who self-bills never waits for one). self_billing: you issue the invoices for promoters who accept your self-billing agreement; turning it on needs your invoicing details first (409 until they are complete). An archived program is 409. Recorded in the activity log with the values before and after.

Turning a requirement off lets money that waited for a form be paid, so a key needs referrals:payouts as well as referrals:write for this call, as changing how payouts are sent does; an AI assistant needs a person's approval.

Parameters

Request body (required)

Answers

GET /v1/referrals/programs/{id}/tax-forms

List each promoter's tax form status

Scope referrals:read. Another workspace's answers 404.

Every approved or pending promoter of the program with their latest tax form for your business: its type (W-9, W-8BEN, W-8BEN-E, or the statement that they are not a US person), revision, status, when it was signed and when it expires. STATUS ONLY: never a tax number, a legal name or anything the form says. Opening a form is done in the dashboard, with two-step verification. requirement_met is false while their payouts wait for a form; waiting_since and forfeitable_minor say since when, and how much.

Parameters

Answers

POST /v1/referrals/partners/{id}/forfeit

Forfeit a promoter's money held for a missing tax form

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Gives up, for good, every approved commission of this promoter that is waiting for a tax form in this program: they will not be paid it, and no payout will ever include it. Only money held for a missing, expired or replaced form can be forfeited (409 otherwise, and when nothing is waiting); what they earn afterwards is not touched. Send a reason of 3 to 500 characters: it is recorded in the activity log with what was given up. BoltClaw never forfeits anything by itself.

Needs referrals:payouts as well as referrals:write, as sending money does, or an AI assistant with a person's approval: referrals:write alone never gives a promoter's money up.

Parameters

Request body (required)

{
  "reason": "<reason>"
}

Answers

GET /v1/referrals/tax-years/{year}

Get a year's 1099-NEC data

Scope referrals:read. Another workspace's answers 404.

Everyone your referral programs paid in a calendar year, as one person per account, with how each was paid (per provider and currency), their tax form's status, and whether they belong on your 1099-NEC (included) and why, in a sentence. Warnings say what to fix before you file: no form, no tax number, backup withholding (24%) may apply, a replaced form, an expired W-8, money in another currency. Only US dollars paid through the providers your 1099 table counts are reportable, against the year's threshold (threshold_minor). No tax number and no legal name: the files themselves (the IRS IRIS CSV, a general CSV and Copy B) are made in the dashboard, with two-step verification. BoltClaw never files, never withholds and never checks a tax number with the IRS.

Parameters

Answers

GET /v1/referrals/payouts/{id}/invoices

List a payout's invoices

Scope referrals:read. Another workspace's answers 404.

The invoices for one payout, newest first: the self-billed invoice you issued in the promoter's name, the promoter's own uploaded invoice, and any they replaced. Each says whether it was accepted, disputed (with the promoter's reason) or replaced. Read a PDF with POST /referrals/invoices/{id}/link.

Parameters

Answers

POST /v1/referrals/invoices/{id}/link

Get a download link for an invoice

Scope referrals:read. Accepts Idempotency-Key. Another workspace's answers 404.

A link to one invoice's PDF, good for ten minutes and one download. It names a promoter's business, so it needs the payouts permission and every link is recorded in the activity log. Treat the link as a secret; ask again for a new one.

Parameters

Answers

POST /v1/referrals/payouts/{id}/statement-link

Get a download link for a payout statement

Scope referrals:read. Accepts Idempotency-Key. Another workspace's answers 404.

A link to the payout's statement as a PDF (who paid whom, how much, when and for which period), good for ten minutes and one download. The statement is what a promoter without a self-billed or uploaded invoice keeps. Treat the link as a secret; ask again for a new one.

Parameters

Answers

POST /v1/referrals/payouts/{id}/invoice

Issue a paid payout's self-billed invoice

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

For a program that self-bills: issues the self-billed invoice of a paid payout that has none (its promoter's or your own invoicing details were missing when it was paid). A payout that already has one answers that invoice, so a repeat changes nothing. 409 with what is missing when it cannot be issued: the payout is not paid, the promoter does not self-bill with this program, your invoicing details are incomplete, or the promoter is in your own country and your domestic VAT rate is not set. Moves no money.

Parameters

Answers

POST /v1/referrals/invoices/{id}/reissue

Issue a corrected invoice for a disputed one

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

A promoter disputed a self-billed invoice within its 14 days. Fix what they said was wrong (ask them to correct their own details, or correct yours in the dashboard), then call this: the disputed invoice becomes void and a new one is issued, with the next number in the promoter's series, from the details as they are now. It starts its own 14 days. Only a disputed self-billed invoice can be replaced (409 otherwise). Recorded in the activity log. Moves no money.

Parameters

Answers

GET /v1/referrals/brand

Get the brand your partners see

Scope referrals:read.

Your brand as partners see it on your own partner portal, the join page, the in-app panel, the friend's welcome and their emails: its name, logos, colours, corner radius, support address, sender name and whether "Powered by BoltClaw" shows. Without program_id, the workspace's brand, which every program uses; with it, that program's own override, where a field left null follows the workspace's brand. effective is what partners of that program actually see, both merged. support_email_verified says whether the support address was confirmed with a code: only then is it the reply-to of partners' emails. See White-label portal.

Parameters

Answers

PATCH /v1/referrals/brand

Change the brand your partners see

Scope referrals:write.

Send only what you change; null clears a field (a program's override then follows the workspace's brand again). name up to 80 characters; accent and background as #rrggbb; radius from 0 to 24; sender_name up to 60 characters, the name partners' emails come from (the address stays BoltClaw's); support_email, which becomes the reply-to of partners' emails only after you confirm it with a code (changing it unconfirms it); show_powered_by, off unless you turn it on. A logo or icon is uploaded first with POST /referrals/brand/uploads, then saved here by sending the path it answered as logo_light_path, logo_dark_path or favicon_path (or null to remove it). With program_id, the change is that program's override. Recorded in the activity log with the names of the fields changed. An AI assistant asks a person first, unless your organisation lets assistants change it without asking.

Request body (required)

Answers

POST /v1/referrals/brand/uploads

Get an upload URL for a logo or icon

Scope referrals:write. Accepts Idempotency-Key.

A signed URL for one file of your brand: logo_light, logo_dark or favicon, as a PNG, JPEG or WebP image of at most 2 MiB (no SVG). PUT the file's bytes to upload_url with its content type, then save it with PATCH /referrals/brand, sending path as the slot's field. Nothing changes until that PATCH: an upload that is never saved is not shown to anyone. The URL works for one file and expires (expires_at); treat it as a secret. upload_url is null in a replay of the same Idempotency-Key: ask for a new one.

Request body (required)

{
  "slot": "logo_light",
  "content_type": "image/png"
}

Answers

POST /v1/referrals/brand/support-email/verification

Send a code to confirm the support address

Scope referrals:write. Accepts Idempotency-Key.

Emails a six-digit code to the support address saved on the brand (the workspace's, or the program's with program_id), good for 15 minutes. Confirm it with POST /referrals/brand/support-email/verification/confirm; until then partners' emails have no reply-to. At most five codes a day for one brand and twenty for the workspace (429 past that). 409 when the address is already confirmed, 400 when none is saved. The answer repeats the address the code went to.

Request body (required)

Answers

POST /v1/referrals/brand/support-email/verification/confirm

Confirm the support address with its code

Scope referrals:write. Accepts Idempotency-Key.

The six-digit code from the email POST /referrals/brand/support-email/verification sent. Each code has five tries; a wrong, used or expired one is 400 (send a new one). Once confirmed, the address is the reply-to of partners' emails about the program, until it is changed. Recorded in the activity log.

Request body (required)

{
  "code": "<code>"
}

Answers

GET /v1/referrals/domains

List your own link and portal domains

Scope referrals:read.

Every domain of your own connected to your referral programs: a links domain (go.example.com, where links read https://go.example.com/<code>) or a partner portal (partners.example.com), each with where it stands and the exact DNS records still to set. See Your own domain.

Answers

POST /v1/referrals/domains

Connect one of your own domains

Scope referrals:write. Accepts Idempotency-Key.

Claims a subdomain of yours (go.example.com for links, partners.example.com for the partner portal; never a domain's root, a wildcard or an IP address) for every program (all_programs, the default) or the ones in program_ids. Nothing is served yet: the answer's records are the exact DNS records to add at your DNS host, in order. First a TXT record, _boltclaw.<host> with the value bc-verify=<token>, which proves the domain is yours; once it is seen, the CNAME record our hosting provider recommends for it appears in records (it differs per domain: never use one from another domain), and sometimes a second TXT record our hosting provider asks for. Check progress with POST /referrals/domains/{id}/check. A domain counts against your plan's domains from the moment it is added (402 past it); 409 when it is already yours, or connected to another account.

An AI assistant always asks a person first: it decides where your links and portal will answer. In the dashboard, adding a domain also needs two-step verification; over the API that approval stands in for it.

Request body (required)

{
  "host": "<host>",
  "kind": "links"
}

Answers

GET /v1/referrals/domains/{id}

Get one of your domains

Scope referrals:read. Another workspace's answers 404.

One domain: where it stands (status, and problem, a sentence saying what is in the way), the exact DNS records to set and whether each is in place, whether a CAA record on your domain keeps the certificate from being issued, and, once active, its address.

Parameters

Answers

DELETE /v1/referrals/domains/{id}

Remove one of your domains

Scope referrals:write. Another workspace's answers 404.

The domain stops answering at once: links on it stop working (each still works at its https://boltclaw.ai/r/<code> address) and its portal pages are gone. It is then taken off our hosting provider, so no record of ours is left pointing at it; remove your own DNS records for it too. Recorded in the activity log. An AI assistant always asks a person first.

Parameters

Answers

POST /v1/referrals/domains/{id}/check

Check a domain's DNS records now

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Looks at the domain's records now instead of waiting for the next check (pending domains are looked at every ten minutes, active ones every day), and moves it on when they are in place: the TXT record proves the domain is yours, the CNAME record routes it, and then the certificate is issued. At most once every 15 seconds per domain: a check asked sooner answers the domain as it stands. Nothing is ever removed by a check.

Parameters

Answers

GET /v1/referrals/programs/{id}/listing

Get a program's directory listing

Scope referrals:read. Another workspace's answers 404.

What the partner directory shows about the program, and whether it is listed. The directory is a page inside BoltClaw that only signed-in accounts can open; it lists only programs whose business switched listing on, and never shows who promotes a program or how many do. missing names every condition not met yet (an active program anybody may apply to, terms, a reward for partners, an organisation at least a week old and not suspended, and a real sale through your billing system or a finished setup checklist); listing is refused until it is empty. preview is the card partners will see. state is listed, unlisted, held (reports from three different accounts hid it until BoltClaw reviews it) or delisted. See Recruiting partners.

Parameters

Answers

PATCH /v1/referrals/programs/{id}/listing

Change a program's directory listing

Scope referrals:write. Another workspace's answers 404.

Sets what the partner directory shows (category, pitch of at most 280 characters, countries, languages, the logo's logo_path from POST /referrals/programs/{id}/listing/logo) and whether the program is listed. The reward summary, cookie window and payout schedule come from the program itself, never from text you type. Turning listed on is 409 with every reason while a condition is not met. An AI assistant asks a person first, because listing publishes the program to every signed-in partner; your organisation may let assistants change it without asking.

Parameters

Request body (required)

Answers

POST /v1/referrals/programs/{id}/listing/logo

Get a URL to upload the listing's logo

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

A signed URL for one PNG, JPEG or WebP file of at most 2 MiB. PUT the file's bytes there with its content type, then save it with PATCH /referrals/programs/{id}/listing, sending the answer's path as logo_path. The file is accepted only if its bytes are an image of that type. upload_url is null in a replay of the same Idempotency-Key.

Parameters

Request body (required)

{
  "content_type": "image/png"
}

Answers

GET /v1/referrals/programs/{id}/broadcasts

List a program's broadcasts

Scope referrals:read. Another workspace's answers 404.

The program's messages to its promoters, newest first (at most 50): drafts, ones being sent and sent ones, with who they went to and how many were emailed, muted or failed.

Parameters

Answers

POST /v1/referrals/programs/{id}/broadcasts

Write a broadcast to a program's promoters

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

A draft, to everyone approved in the program, one group or level, or a list of up to 500 promoters you pick. Nothing is sent until POST /referrals/broadcasts/{id}/send. The body is a small Markdown subset: paragraphs, bold, italic, [links](https://...) and lists; no HTML, no images, https links only, and every link is shown with its domain. {name}, {link} and {code} are filled with each promoter's own display name, referral link and discount code. Subject at most 120 characters, body at most 5,000.

Parameters

Request body (required)

{
  "subject": "<subject>",
  "body": "<body>"
}

Answers

GET /v1/referrals/broadcasts/{id}

Get one broadcast

Scope referrals:read. Another workspace's answers 404.

One broadcast: its subject and Markdown, who it goes to, the hosts it links to, whether its current text was test-sent, and once sent, how many promoters it reached: emailed, muted (they still see it on their program page), your own users in the in-app panel (referrers, never emailed by BoltClaw), failed and skipped.

Parameters

Answers

PATCH /v1/referrals/broadcasts/{id}

Change a draft broadcast

Scope referrals:write. Another workspace's answers 404.

Changes a draft's subject, body or audience. A sent broadcast is a record and is 409: write a new one.

Parameters

Request body (required)

Answers

POST /v1/referrals/broadcasts/{id}/test

Send yourself a test of a draft

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Emails the draft, as it reads now, to the address of the person who made this API key and nobody else, with sample values in {name}, {link} and {code}. At most ten per draft, one every 15 seconds. The dashboard sends a broadcast only after a test of its current text.

Parameters

Answers

POST /v1/referrals/broadcasts/{id}/send

Send a broadcast to a program's promoters

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Sends the draft. Every approved promoter it names sees it on their program page; those with a BoltClaw account are emailed (unless they muted the program's messages: every email has a one-click unsubscribe), a few a minute; your own users in the in-app panel are never emailed by BoltClaw, so referral.broadcast.sent tells your webhook, and GET /referrals/broadcasts/{id}/referrers names them for your own message. A program may send 2 broadcasts in any 24 hours and 10 in any 30 days (429 past either). An AI assistant always asks a person first: it messages people.

Parameters

Answers

GET /v1/referrals/broadcasts/{id}/referrers

List your own users a broadcast reached

Scope referrals:read. Another workspace's answers 404.

The referrers (your own users, made by your server) a sent broadcast reached, 200 a page, by your own id for each (external_id), with their name, link and code, so your system can send them the message itself. BoltClaw emails none of them.

Parameters

Answers

POST /v1/referrals/programs/{id}/imports/preview

Check a partner list before importing it

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Checks up to 500 rows (as rows, or a csv with a header row: name, email, and optionally code, group, rate, balance, currency) against the program and writes nothing: rows that would fail and why (a code taken, a person already invited or promoting, a group that does not exist, a balance in another currency). Addresses are hashed on arrival and never stored. Send a larger file in parts. See Recruiting partners.

Parameters

Request body (required)

Answers

GET /v1/referrals/programs/{id}/imports

List a program's imports

Scope referrals:read. Another workspace's answers 404.

The partner lists brought into the program, newest first, with how many people each invited and how many claimed.

Parameters

Answers

POST /v1/referrals/programs/{id}/imports

Import a partner list

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Makes an invite reserved for each row, all or nothing (409 with the first row's reason when any fails: preview first). Each invite holds that person's vanity code (no one else can take it meanwhile), group, custom rate and opening balance. BoltClaw sends nobody an email: the answer has each person's personal link, and you send it from your own email. When they sign in through it they are approved (if your plan has room) with their code, group and rate, and an opening balance becomes a bonus paid by hand ("Balance brought over") only then. import_id continues an import begun by an earlier part of the same file. A file with opening balances also needs referrals:payouts on the key. An AI assistant always asks a person first. Recorded in the activity log.

Parameters

Request body (required)

Answers

GET /v1/referrals/imports/{id}/invites

List an import's personal links

Scope referrals:write. Another workspace's answers 404.

Everyone in one import with their personal link and whether they claimed it, 1,000 a page, for the file you send from your own email. The links are credentials (each joins one person), so this needs referrals:write.

Parameters

Answers

GET /v1/referrals/programs/{id}/library

List a program's file library

Scope referrals:read. Another workspace's answers 404.

The images, text snippets and links partners see on their program page (an item with a group_id only by that group's), in order. An image item is shown once its file is in (ready).

Parameters

Answers

POST /v1/referrals/programs/{id}/library

Add to a program's file library

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

An image (its file follows through POST /referrals/library/{id}/upload), a snippet of at most 2,000 characters whose {link} and {code} partners see filled with their own (with the program's disclosure line after it), or a link to a brand guide or press kit (https only; its domain is shown). group_id shows it to one group only; in_panel shows a snippet to your own users in the in-app panel too. At most 200 items a program.

Parameters

Request body (required)

{
  "kind": "image",
  "title": "<title>"
}

Answers

PATCH /v1/referrals/library/{id}

Change a library item

Scope referrals:write. Another workspace's answers 404.

Changes an item's title, text, link, group, place in the order, or whether a snippet is in the panel. For an image, image_path saves the file uploaded through POST /referrals/library/{id}/upload; it is accepted only if its bytes are a PNG, JPEG or WebP image.

Parameters

Request body (required)

Answers

DELETE /v1/referrals/library/{id}

Delete a library item

Scope referrals:write. Another workspace's answers 404.

The item and its file are gone; partners no longer see it. An AI assistant asks a person first, unless your organisation lets assistants do it without asking.

Parameters

Answers

POST /v1/referrals/library/{id}/upload

Get a URL to upload a library image

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

A signed URL for an image item's file: one PNG, JPEG or WebP of at most 2 MiB (no SVG, HTML or PDF). PUT the bytes there with their content type, then save it with PATCH /referrals/library/{id} and the answer's path as image_path. upload_url is null in a replay of the same Idempotency-Key.

Parameters

Request body (required)

{
  "content_type": "image/png"
}

Answers

GET /v1/referrals/programs/{id}/link-hosts

List the sites a program's links may go to

Scope referrals:read. Another workspace's answers 404.

A partner's link can open any page of your site: https://boltclaw.ai/r/<code>?to=/pricing goes to your product URL's host plus /pricing, and &host=docs.example.com to another of your hosts. Those other hosts are the program's allowed_hosts, each used only once you prove it is yours with the TXT record shown here (_boltclaw.<host> with the value bc-verify=<token>), then POST /referrals/programs/{id}/link-hosts/check. Anything else falls back to the product URL: a link is never an open redirect.

Parameters

Answers

POST /v1/referrals/programs/{id}/link-hosts/check

Check a site's TXT record now

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

Looks up _boltclaw.<host> now for one of the program's allowed hosts; when it holds the value shown, links may go to that host. A check that finds the record gone takes that away again. At most once every 10 seconds per host.

Parameters

Request body (required)

{
  "host": "<host>"
}

Answers

GET /v1/referrals/programs/{id}/leaderboard

Read a program's leaderboard

Scope referrals:read. Another workspace's answers 404.

Every promoter with something counted, ranked by the program's leaderboard metric over its period (or the metric and period you ask for), with each one's membership id, name and, for one of your own users, your external_id. This is your view: promoters see only the first places, each named as its promoter chose (hidden, initials or their name), and money only when the board shows amounts. What counts is counted activity: a sale no person or rule holds, not refunded in full, not disputed; on a waitlist, confirmed friends. Counted again at most every 10 minutes. See Campaigns.

Parameters

Answers

GET /v1/referrals/programs/{id}/contests

List a program's contests

Scope referrals:read. Another workspace's answers 404.

A program's contests, newest first, each with its prizes and what it is now (scheduled, running, ended, awarded or cancelled; the clock decides, not a job).

Parameters

Answers

POST /v1/referrals/programs/{id}/contests

Create a contest

Scope referrals:write. Accepts Idempotency-Key. Another workspace's answers 404.

A window (up to a year), a metric as a leaderboard's, who may enter (every promoter, or one group or level), a minimum to qualify, and prizes by place: cash (paid as a bonus by hand) or a reward that is not cash (credit, a gift card, a free period or a perk). Standings count only what happens inside the window. Nothing is paid until a person awards the prizes after it ends. At most 10 contests a program may be scheduled or running at once.

Parameters

Request body (required)

{
  "starts_at": "2026-03-04T17:02:10.885210+00:00",
  "ends_at": "2026-03-04T17:02:10.885210+00:00",
  "prizes": [],
  "name": "<name>"
}

Answers