> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rekomi
> Run an affiliate program on your Dodo Payments store with Rekomi. One pasted API key connects the two, and Rekomi tracks sales and pays your affiliates.
## Introduction
[Rekomi](https://rekomi.com) is an affiliate tracking and management platform with a native Dodo Payments integration. An affiliate shares a link, and Rekomi records the click. When that visitor buys, Dodo Payments sends the sale to Rekomi, which credits the right affiliate. Rekomi calculates the commission and pays your affiliates for you, in 150+ countries, tax forms included.
To connect, you paste one Dodo Payments API key with write access into Rekomi. Rekomi validates the key, creates the webhook endpoint in your Dodo Payments account, and fetches the endpoint's signing secret. You don't fill in a webhook form or paste anything back into Dodo Payments.
Rekomi credits a sale to an affiliate when a referred customer completes a one-time payment, starts a paid subscription, or pays a renewal. Refunds and disputes claw the commission back automatically.
## How It Works
Dodo Payments hosts checkout on its own domain, so the affiliate referral travels into the sale as checkout metadata:
1. A visitor clicks an affiliate link and lands on your site, where the Rekomi script stores the referral in their browser.
2. At checkout, you attach that referral to the payment as `rekomi_ref` metadata.
3. Dodo Payments processes the payment and sends a signed `payment.succeeded` webhook to the endpoint Rekomi created.
4. Rekomi matches the referral to the affiliate, calculates the commission on the pre-tax sale amount, and records it.
Subscription renewals arrive the same way, so recurring commissions need no extra work. Refunds and disputes also arrive through the same endpoint.
## Prerequisites
Before you set up this integration, you need:
1. A [Dodo Payments account](https://app.dodopayments.com) in live mode
2. A [Rekomi account](https://app.rekomi.com/sign-up)
3. A Dodo Payments API key with **write access** enabled, because read-only keys can't create webhooks
## Getting Started
Enable write access on the key. A read-only key passes validation but can't create the webhook endpoint, so the connection fails partway.
In the Dodo Payments dashboard, go to **Developer → API Keys** and click **Add API Key**. Name the key `Rekomi` and keep **Enable write access** checked. For details, see [Authentication](/api-reference/introduction#authentication).
In Rekomi, open **Setup → Connect payment processor**, choose Dodo Payments, and paste the key. Rekomi validates it, creates the webhook endpoint in your account, and fetches the endpoint's signing secret.
After you connect, Rekomi uses the key only to manage the webhook endpoint and run periodic health checks. Your sales arrive through the signed webhook, not through the API.
Add the Rekomi tracking script to your marketing site to capture affiliate clicks. Rekomi shows your snippet, with the program ID filled in, under **Setup → Install**.
```html theme={null}
```
Attach the captured referral to each payment as `rekomi_ref` metadata. The [Implementation Guide](#implementation-guide) shows how for each checkout type.
Sales, renewals, refunds, and disputes now credit and claw back affiliate commissions automatically, and Rekomi pays your affiliates.
## Implementation Guide
### Checkout Sessions via the API
On your frontend, read the referral with `window.Rekomi.getReferral()` and send it to your backend with the checkout request. On the backend, set it in `metadata`:
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();
export async function createCheckout(productId: string, rekomiRef?: string) {
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: productId, quantity: 1 }],
customer: {
email: 'customer@example.com',
name: 'John Doe',
},
return_url: 'https://yoursite.com/success',
metadata: {
...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
},
});
return session.checkout_url;
}
```
The same `metadata.rekomi_ref` field works on subscription products, so the first charge and every renewal credit the same affiliate.
### Payments API
The example below uses `POST /payments`, which is **deprecated**. It still works for existing integrations. New integrations should use [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`), which take `metadata` the same way.
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();
export async function createPayment(productId: string, rekomiRef?: string) {
const payment = await client.payments.create({
billing: {
city: 'New York',
country: 'US',
state: 'NY',
street: '123 Main St',
zipcode: '10001',
},
customer: {
email: 'customer@example.com',
name: 'John Doe',
},
product_cart: [{ product_id: productId, quantity: 1 }],
payment_link: true,
metadata: {
...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
},
});
return payment;
}
```
### Static Payment Links
Add the referral to the link as a flat `metadata_rekomi_ref` query parameter, not the bracket form:
```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```
Dodo Payments adds `metadata_*` query parameters to the payment's metadata, where Rekomi reads them.
## What Gets Tracked
Rekomi handles each type of sale event as follows:
| Event | What happens |
| - | - |
| One-time payment | Commission credited on the pre-tax sale amount |
| Subscription renewal | Recurring commission, every charge arrives as its own payment event |
| Refund | Commission clawed back automatically, up to the amount credited |
| Dispute | Commission clawed back as soon as the dispute opens |
Rekomi calculates commissions on the pre-tax sale amount. Dodo Payments is the Merchant of Record and collects the tax, so your affiliates earn on the sale itself, not on the tax that the buyer's country adds.
## Important Notes
* Rekomi registers the webhook endpoint with exactly the events it needs. Don't edit that endpoint's event list in the Dodo Payments dashboard: Rekomi's health checks flag the connection if events are removed.
* A free trial creates no payment until the trial ends, so no commission exists until the first charge. A [paid trial](/features/subscription#paid-trials) charges the trial amount upfront.
* Disconnecting in Rekomi deletes the webhook endpoint from your Dodo Payments account.
## Additional Resources
The full setup walkthrough, troubleshooting, and security details in Rekomi's docs.
All affiliate integration options for Dodo Payments.
For help with the integration, contact Rekomi support at [support@rekomi.com](mailto:support@rekomi.com) or Dodo Payments support at [support@dodopayments.com](mailto:support@dodopayments.com).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.