Set up affiliates

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, 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

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
  }'

{
  "enabled": true,
  "commission_type": "percentage",
  "rate": 20,
  "fixed_amount": null,
  "cookie_window_days": 30,
  "recurring": true,
  "recurring_cap": 12,
  "auto_approve": false
}

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

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:

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:

Single email

Enter an email (and optional name) and we send an invite with a one-click join link.

CSV upload

Upload a CSV with an email column (optional name) to invite many people at once — parsed in your browser, then sent.

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 — 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.

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.

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:

Logs the click against the affiliate’s <CODE>.
Sets an mp_ref cookie scoped to your cookie window.
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.

Hosted checkout

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.

Your own site

Add our snippet — it captures ?ref and forwards mp_ref into Macropay checkout links automatically.

API / SDK

Creating sessions yourself? Set metadata.mp_ref to the code when you create the checkout.

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

<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:

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>"
    }
  }'

Explicit metadata.mp_ref always wins — automatic injection never overwrites a code you set yourself.

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 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.

Bootup

Features

Integrate

Merchant of Record (MoR)

Set up affiliates

1. Enable the program and set defaults

Update the program via API

Invite affiliates by email or CSV

Single email

CSV upload

Get listed on the marketplace

3. Approve applicants

4. How attribution works

Getting the code onto the order

Hosted checkout

Your own site

API / SDK

FAQ

Next steps

Affiliates overview

Affiliate payouts

​1. Enable the program and set defaults

​Update the program via API

​2. Share your apply link

​Invite affiliates by email or CSV

Single email

CSV upload

​Get listed on the marketplace

​3. Approve applicants

​4. How attribution works

​Getting the code onto the order

Hosted checkout

Your own site

API / SDK

​FAQ

​Next steps

Affiliates overview

Affiliate payouts

1. Enable the program and set defaults

Update the program via API

2. Share your apply link

Invite affiliates by email or CSV

Get listed on the marketplace

3. Approve applicants

4. How attribution works

Getting the code onto the order

FAQ

Next steps