Install on Dodo Payments

Dodo Payments is a Merchant of Record for digital products and SaaS, and Rekomi supports it natively. The setup is one paste: you give Rekomi a full-access API key, and Rekomi validates it live, creates the webhook endpoint in your Dodo Payments account itself, and fetches its signing secret for you. There is nothing to paste back into Dodo and no manual webhook form to fill in. From that point on, payments, subscription renewals, refunds, and disputes flow into Rekomi with no relay code to write or maintain. Still evaluating? See Why Rekomi for Dodo Payments →.

One thing to know up front: the key must be full-access. Dodo's read-only keys pass ordinary validation but cannot create webhooks, so a read-only key fails partway through the connect with an error naming exactly that. After connect, the key is used only to manage the webhook endpoint and run a periodic read-only health check; your sales arrive through the signed webhook, not through the key.

What you need

• A Dodo Payments account in live mode. Test mode is a completely separate universe on a separate host (test.dodopayments.com) with its own keys and its own webhooks; Rekomi rejects test-mode credentials on a production connection with a clear error before anything is stored.
• A full-access API key. In Dodo Payments, open Developer > API Keys and create a key (name it "Rekomi"). Dodo keys do not expire; if the key is ever revoked, Rekomi's health checks flag the connection as broken within 30 minutes and email you.
• Two minutes. There is no OAuth dance, no webhook form, and no secret to copy; the whole flow is one paste.

Connect in Rekomi

Step 1. Go to /dashboard/setup/dodo.

Step 2. Paste your full-access API key and click Connect Dodo Payments. Rekomi validates the key live against Dodo, creates the webhook endpoint pointed at your per-workspace URL with the exact event set it needs, and fetches the endpoint's signing secret itself. If either half of that fails, nothing is left behind: an endpoint whose secret could not be stored is deleted again rather than left delivering events Rekomi cannot verify.

That's it. The setup page shows the webhook URL and the registered events for reference only; Rekomi manages the endpoint end to end.

Attribution: carry rekomi_ref in checkout metadata (required)

Dodo hosts its checkout on its own domain, so the affiliate referral has to travel from the visitor's browser into the payment record. This step is required for new-customer attribution: without it, sales arrive with no referral and no commission is credited.

First, make sure the Rekomi head script is installed on your marketing site so the affiliate click is captured when a visitor lands on an affiliate link:

<script>
  (function(){
    var s=document.createElement('script');
    s.src='https://js.rekomi.com/v1/rekomi.js';
    s.async=true;
    s.dataset.programId='YOUR_PROGRAM_ID';
    document.head.appendChild(s);
  })();
</script>

The program ID is in Settings > Tracking in the Rekomi dashboard. Then pick the recipe that matches how you sell:

Creating checkouts via Dodo's API. Read the referral on your frontend with window.Rekomi.getReferral(), send it to your backend with the checkout request, and set it in metadata on POST /checkouts, /subscriptions, or /payments:

{
  "product_cart": [{ "product_id": "prod_your_product", "quantity": 1 }],
  "metadata": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
}

Static payment links. Decorate the link with the flat metadata param; Dodo copies metadata_key=value query params into the payment's metadata (note the flat underscore form, not the metadata[rekomi_ref] bracket form some other platforms use):

const ref = window.Rekomi?.getReferral?.();
const url = new URL("https://checkout.dodopayments.com/buy/prod_your_product");
if (ref) url.searchParams.set("metadata_rekomi_ref", ref);
// use url.toString() as the href on your Buy button

Subscription metadata persists for the life of the subscription, and Rekomi also falls back to the customer's attribution history, so renewals credit the same affiliate.

How sales and renewals track

• Every charge arrives as one payment event. One-time purchases, the first subscription charge, every renewal, plan-change charges, and on-hold recovery charges all record from Dodo's payment.succeeded event, at the charged amount.
• Initial vs renewal is inferred. Dodo's payment event does not label itself as first-charge or renewal, so Rekomi infers it: a payment on a subscription Rekomi has seen before records as recurring, an unseen one as initial. If deliveries ever arrive out of order the two labels can swap; the amounts are always correct, and the commission follows the assigned label (recurring rules like delays and caps key off it).
• Commissions are calculated on the charge amount including tax. Dodo reports the charge tax-inclusive, and its refunds and disputes are tax-inclusive too, so this is the only basis where a full refund claws back exactly what was credited. Your affiliates earn on what the customer actually paid.
• Trials fire no payment event until the trial ends, so no commission exists until the first real charge. Subscription lifecycle events (active, on hold, cancelled, expired) flow through as churn signals for churn-aware commission rules.
• Everything is de-duplicated by the underlying payment, subscription, refund, and dispute ids, so Dodo's retries and manual redeliveries never double count.

Refunds and disputes

Refunds reverse commission automatically: a partial refund claws back the refunded share, and multiple partials keep clawing back until the original commission is exhausted, never past it. Dodo allows refunds within 30 days of the transaction; each partial arrives as its own refund event. One honesty note: Dodo sometimes reports a full refund without an amount on the event; Rekomi treats that as a refund of everything remaining on the conversion, which is the safe reading (the clawback is capped at the original commission either way). A no-amount event that claims to be partial is flagged for review instead of guessed at.

Disputes (chargebacks) claw back the disputed money when the dispute opens. If you later win the dispute, the commission is not restored automatically in this version; the win is logged so you can adjust manually if you choose. Losing a dispute changes nothing further (the money was already clawed back at open).

Bring-your-own-provider caveat. Dodo lets some merchants process through their own Stripe or Adyen account behind Dodo's checkout (BYOP). Payments track normally either way, but BYOP payments may never emit refund or dispute webhooks (the merchant handles those at their own provider), so clawbacks for BYOP refunds are manual.

Currencies

Dodo's Adaptive Currency feature can present more than 80 local currencies at checkout, which is more than Rekomi's supported-currency list covers. When a payment, refund, or dispute arrives in a currency Rekomi does not support (for example VND, NGN, CLP, or the three-decimal codes KWD, BHD, OMR), that event is skipped and flagged rather than guessed at, so a commission is never computed on a mangled amount. Sales in the major currencies (USD, EUR, GBP, and the rest of Rekomi's list) all record normally. If a meaningful share of your sales settles in an unsupported currency, tell us; the list is expandable.

Security

• Every webhook delivery is signature-verified (the standard-webhooks scheme: HMAC over the delivery id, timestamp, and body, with a 300-second freshness window) before anything is processed, failing closed on anything malformed.
• The API key and the webhook signing secret are stored encrypted at rest and never returned by the API. You never see or handle the signing secret at all; Rekomi fetches and stores it directly.
• Disconnecting deletes the webhook endpoint at Dodo, wipes both secrets, and retires the webhook URL.
• Live mode and test mode are isolated by construction: they are separate hosts with separate keys and separate webhooks, and events are additionally checked against the connected business before anything records.

Quirks worth knowing

• One conversion source per workspace. Dodo Payments Connect is mutually exclusive with Stripe Connect, Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, and the S2S API, so the same sale is never counted twice. Disconnect one before connecting another. And to be precise about one edge: if you sell through Dodo with BYOP over your own Stripe account, the Dodo rail is the one to connect; Stripe Connect would not see those charges as Dodo reports them.
• Dodo API keys do not expire. If the health check flags the connection as broken, the key was revoked in Dodo, or the webhook endpoint was deleted or disabled there; it is never a routine expiry. There is no secret-rotation API, so recovery is always the same one paste: create a fresh full-access key and reconnect.
• The endpoint can be disabled from Dodo's dashboard. If that happens, the setup page and the reconnect email say so specifically: re-enable it in Dodo's dashboard, or reconnect (which recreates it).
• Dodo caps webhook endpoints at 5 per account. If your account is at the cap, the connect fails with an error saying exactly that; remove an unused endpoint in Dodo's dashboard and try again.
• Switching modes strands the old endpoint. Live and test are separate universes, so reconnecting under a different mode cannot clean up the other mode's endpoint. If you switch, delete the old endpoint in that mode's Dodo dashboard (it also counts toward the 5-endpoint cap).
• The retry ladder runs about 27.5 hours. Dodo retries a failed delivery up to 8 times (immediately, then 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 10 hours). Rekomi answers with an error on purpose when it briefly cannot process a money event so Dodo redelivers; for anything that outlives the ladder, Dodo's dashboard has delivery logs with manual redelivery, and Rekomi records redeliveries idempotently.
• Coupon-code attribution is not wired for Dodo yet. Attribution rides rekomi_ref metadata; per-affiliate discount codes still work as plain discounts, they just do not attribute the sale by themselves on this rail.

Test the flow

Dodo's test mode is a separate host, and production Rekomi connections deliberately reject test-mode credentials, so a full rehearsal runs on a staging setup. What you can verify on production without spending money:

1. Connect, then click Check connection on the setup page: it live-probes the webhook endpoint Rekomi created (key validity, endpoint existence, and the disabled flag, in one check).
2. Confirm the endpoint appears in your Dodo dashboard under Developer > Webhooks, pointed at your per-workspace URL.
3. Place one real purchase through an affiliate link with ?via= set to an approved affiliate's link slug, confirm the conversion on the campaign's Activity tab within a minute, then refund it and confirm the commission claws back.

Troubleshooting

"...is a FULL-ACCESS key (read-only keys cannot create webhooks)..." The key validated but could not create the webhook endpoint. Dodo's read-only keys can read your account but not write to it; create a full-access key under Developer > API Keys and connect with that.

"Dodo allows up to 5" webhook endpoints. Your account is at Dodo's endpoint cap, so the create was rejected. Remove an unused endpoint in the Dodo dashboard (Developer > Webhooks) and connect again.

"Test mode connections are not available here." You selected (or your key belongs to) Dodo's test mode on a production connection. Test mode is a separate universe; connect with a live-mode key.

"Connection needs attention" banner or reconnect email. Either the stored API key stopped validating (revoked in Dodo) or the webhook endpoint went missing or was disabled. The message says which. For a disabled endpoint, re-enable it in Dodo's dashboard or reconnect; for everything else, create a fresh full-access key and reconnect on /dashboard/setup/dodo; your tracking history is preserved.

Sales arrive but no affiliate is credited. The payment reached Rekomi but carried no rekomi_ref. Verify your checkout-create call sets metadata.rekomi_ref (or your static payment links carry the flat ?metadata_rekomi_ref= param), and that the head script ran before the buyer clicked through (so window.Rekomi.getReferral() had a value).

A sale in an exotic currency did not record. Check the currency against Rekomi's supported list; unsupported-currency events are skipped and flagged by design (see Currencies above) rather than recorded at a guessed value.

A conversion is missing after an outage. Dodo's retry ladder covers about 27.5 hours. For anything older, open the delivery in Dodo's dashboard webhook logs and redeliver it; Rekomi records it idempotently.

Related

• S2S tracking API reference
• JavaScript pixel reference
• Refund handling