> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up affiliates

> Launch a merchant affiliate program in minutes — set commissions, share an apply link, approve partners, and attribute sales automatically.

An affiliate program lets partners earn a commission for driving paid customers to you. As the merchant, you enable the program, set default commission terms, approve who can promote you, and Macropay tracks referral clicks and attributes the resulting sales. Because Macropay is your [merchant of record](/merchant-of-record/introduction), commission is always computed on the **net amount** — subtotal minus discount, excluding tax — so payouts never include money you never kept.

## 1. Enable the program and set defaults

Open the **Affiliates** page in the dashboard and go to the **Program** tab. Toggle the program on and set the defaults every new affiliate inherits.

| Setting                  | What it does                                                                     |
| ------------------------ | -------------------------------------------------------------------------------- |
| **Commission type**      | `percentage` (a share of the net sale) or `fixed` (a flat amount per sale).      |
| **Rate**                 | The commission percentage when type is `percentage` (e.g. `20` for 20%).         |
| **Fixed amount**         | The flat commission in minor units when type is `fixed` (e.g. `2500` = \$25.00). |
| **Cookie window (days)** | How long after a click a sale can still be attributed to the affiliate.          |
| **Recurring**            | When on, the affiliate earns on renewal invoices, not just the first sale.       |
| **Recurring cap**        | Optional limit on how many billing cycles pay out (e.g. 12 months).              |
| **Auto-approve**         | When on, new applicants are approved instantly instead of waiting for review.    |

You can change these defaults at any time. Existing affiliates keep their own terms unless you edit them individually.

### Update the program via API

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.macropay.ai/v1/affiliate-program \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "commission_type": "percentage",
      "rate": 20,
      "cookie_window_days": 30,
      "recurring": true,
      "recurring_cap": 12,
      "auto_approve": false
    }'
  ```

  ```json Response theme={null}
  {
    "enabled": true,
    "commission_type": "percentage",
    "rate": 20,
    "fixed_amount": null,
    "cookie_window_days": 30,
    "recurring": true,
    "recurring_cap": 12,
    "auto_approve": false
  }
  ```
</CodeGroup>

<Note>
  For a fixed-fee program, send `"commission_type": "fixed"` and `"fixed_amount": 2500` (in minor units) instead of `rate`.
</Note>

## 2. Share your apply link

Send prospective partners to your public application page. Replace `<ORG_ID>` with your organization ID:

```
https://affiliate.macropay.ai/affiliate/apply?org=<ORG_ID>
```

Affiliates submitted through this page create an application record. You can also create affiliates programmatically — the same record is produced when an applicant (or your own integration) posts to the apply endpoint:

```bash theme={null}
curl -X POST https://api.macropay.ai/v1/affiliates/apply \
  -H "Content-Type: application/json" \
  -d '{
    "org": "<ORG_ID>",
    "email": "partner@example.com",
    "name": "Partner Name",
    "website": "https://partner.example.com"
  }'
```

### Invite affiliates by email or CSV

From **Dashboard → Affiliates → Invite** you can recruit directly:

<CardGroup cols={2}>
  <Card title="Single email" icon="envelope">
    Enter an email (and optional name) and we send an invite with a one-click
    join link.
  </Card>

  <Card title="CSV upload" icon="file-csv">
    Upload a CSV with an email column (optional name) to invite many people at
    once — parsed in your browser, then sent.
  </Card>
</CardGroup>

Invited people get a tokenized link (`/affiliate/apply?org=<ORG_ID>&invite=<token>`)
that prefills their email and — because you invited them — **auto-approves** them
on join. Track who's pending vs accepted in the Invite tab, and resend or revoke
any invite. Invites expire after 30 days.

### Get listed on the marketplace

Whenever your program is **enabled**, it's automatically listed on the public
**affiliate marketplace** at
[affiliate.macropay.ai](https://affiliate.macropay.ai) — a searchable directory
of programs (name, website, category, and commission) anyone can browse and apply
to. In **Program** settings, add a short **listing description** (it falls back to
your org bio) and a **category** (e.g. Design, SaaS, Development) so affiliates can
search and filter to find you.

## 3. Approve applicants

New applications land in the **Affiliates** tab with a `pending` status. Approve or reject each one — on approval, the affiliate is issued a unique referral **code** and inherits your program defaults.

If you turned on **Auto-approve**, applicants are activated immediately and skip this step.

<Tip>
  Need a different deal for one partner? Open any affiliate and set a **per-affiliate override** for commission type, rate, fixed amount, or recurring terms. Overrides take precedence over the program defaults for that affiliate only.
</Tip>

## 4. How attribution works

A referral link routes a visitor through Macropay's tracking endpoint before sending them to your destination URL:

```
https://api.macropay.ai/v1/affiliate/track?ref=<CODE>&org=<ORG_ID>&url=<DEST>
```

When a visitor opens that link, Macropay:

1. **Logs the click** against the affiliate's `<CODE>`.
2. **Sets an `mp_ref` cookie** scoped to your cookie window.
3. **Redirects** to `<DEST>` with `?ref=<CODE>` appended so the code is available client-side.

A sale is attributed when the resulting order carries the referral code in `user_metadata` as **`mp_ref`** (or `referral_code`). At `order.paid`, Macropay matches the code to an active affiliate and records the commission on the **net amount** (subtotal minus discount, excluding tax). Recurring commissions, if enabled, accrue on each subsequent paid invoice until the cap is reached.

### Getting the code onto the order

There are three ways the code reaches the order — pick whichever fits your setup. **No tracking pixel on your site is required for hosted checkout.**

<CardGroup cols={3}>
  <Card title="Hosted checkout" icon="bolt">
    **Automatic, no code.** Because Macropay hosts your checkout, the `mp_ref`
    cookie set by the tracking link is read at checkout and folded into the order
    for you. Works out of the box with checkout links and the hosted page.
  </Card>

  <Card title="Your own site" icon="code">
    Add our snippet — it captures `?ref` and forwards `mp_ref` into Macropay
    checkout links automatically.
  </Card>

  <Card title="API / SDK" icon="terminal">
    Creating sessions yourself? Set `metadata.mp_ref` to the code when you create
    the checkout.
  </Card>
</CardGroup>

**Snippet** — drop this on your site if you link to Macropay checkout from your own pages:

```html theme={null}
<script src="https://app.macropay.ai/affiliate.js" async></script>
```

It reads `?ref`/`?mp_ref` from the landing URL, stores it for your cookie window, and appends `mp_ref` to any Macropay checkout links on the page. It also exposes `window.MacropayAffiliate.getRef()` if you'd rather attach the code yourself.

**API** — pass the code through `metadata.mp_ref` when you create the checkout session. The value flows onto the order as `user_metadata.mp_ref`, which is what attribution matches at `order.paid`:

```bash theme={null}
curl -X POST https://api.macropay.ai/v1/checkouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "<PRODUCT_ID>",
    "metadata": {
      "mp_ref": "<CODE>"
    }
  }'
```

<Note>
  Explicit `metadata.mp_ref` always wins — automatic injection never overwrites a code you set yourself.
</Note>

## FAQ

**How do I attribute a sale to an affiliate?**
The order needs the affiliate's referral code in `user_metadata` as `mp_ref` (or `referral_code`). With **Macropay-hosted checkout this is automatic** — the tracking link's `mp_ref` cookie is read at checkout and attached for you. If you run your own site/checkout, add the [`affiliate.js` snippet](https://app.macropay.ai/affiliate.js) or set `metadata.mp_ref` via the API. Attribution is finalized at `order.paid`.

**A percentage commission is a percentage of what amount?**
The **net amount** — the subtotal minus any discount, excluding tax. Because Macropay is the merchant of record, tax is remitted on your behalf and is never part of the commission base.

**Can I set a different rate for one affiliate?**
Yes. Open the affiliate in the **Affiliates** tab and add a per-affiliate override for commission type, rate, fixed amount, or recurring terms. The override applies only to that affiliate and takes precedence over the program defaults.

**Do affiliates earn on subscription renewals?**
Only if you enable **Recurring** on the program (or as a per-affiliate override). When on, commission accrues on each paid invoice up to the optional **recurring cap**; when off, only the first paid sale earns.

**How long after a click can a sale still be attributed?**
For as long as your **cookie window** allows. The `mp_ref` cookie is set when the visitor passes through the tracking link, and a matching order within that window is credited to the affiliate.

## Next steps

<CardGroup cols={2}>
  <Card title="Affiliates overview" icon="people-group" href="/features/affiliates/introduction">
    How the affiliate program fits together, end to end.
  </Card>

  <Card title="Affiliate payouts" icon="money-bill-transfer" href="/features/affiliates/payouts">
    Review accrued commissions and pay your partners.
  </Card>
</CardGroup>