Dodo Payments
Connect Dodo Payments so payments, refunds, and subscriptions become RefRef facts, and deliver credit, discount codes, and plan upgrades in Dodo.
The Dodo Payments integration works in two directions:
- Facts in. Dodo payments, refunds, lost disputes, and subscriptions become
purchaseEvents, purchase adjustments, and Subscription facts in your Project. Your server does not send them to the RefRef API. - Rewards out. RefRef delivers a Program's account credit to the customer's Dodo wallet, its discounts as single-use Dodo discount codes, and its custom Rewards as a free plan upgrade.
You connect one Dodo account to each Project. A Sandbox Project connects a Dodo test-mode account, and a Live Project connects a live-mode account. Start in the Sandbox Project.
Connect Dodo Payments
-
In the Dodo dashboard, switch to the mode of the Project (test mode for a Sandbox Project) and create an API key.
-
In RefRef, open the Project's Settings → Integrations, paste the key under Connect Dodo Payments, and select Connect. RefRef checks the key with Dodo and stores it encrypted.

-
The connection shows its webhook URL, which ends in
/integrations/v1/dodo/webhooks/<connectionId>. Copy it. -
In the Dodo dashboard, in the same mode, add a webhook endpoint with that URL and subscribe it to these events:
Dodo event What RefRef records payment.succeededA purchaseEvent. A subscription payment is aninvoice; a one-time payment is anorder.refund.succeededA refundpurchase adjustmentdispute.lost,dispute.acceptedA dispute_losspurchase adjustmentsubscription.active,subscription.renewedThe start of the Subscription subscription.paused,subscription.unpausedA pause and a resume subscription.cancelled,subscription.expiredThe end of the Subscription -
Copy the endpoint's signing secret (
whsec_…), paste it into the connection's Signing secret field in RefRef, and select Save. Until you save it, RefRef refuses the endpoint's events.
RefRef checks the signature of each event (Standard Webhooks) and refuses a changed body, a timestamp more than five minutes old, or another secret. A repeated event is stored once.
Dodo test mode and live mode are separate environments with separate keys, webhook endpoints, and secrets. A Sandbox Project accepts only a test-mode key, and its endpoint receives only test-mode events.
Name the customer at checkout
RefRef never matches a Dodo customer by email. Your server names the participant in the metadata when it creates the checkout session. RefRef reads it from the payment, then the subscription, then the customer:
| Metadata key | Value |
|---|---|
refref_external_id | The participant's externalId in the Project, for example your user ID. Required. |
refref_participant_kind | individual (the default) or group, for a team account. Another value names nobody. |
refref_handle | Optional. The value of the buyer's refref_handle cookie, from the landing script. See Buyers who did not sign up first. |
const response = await fetch("https://test.dodopayments.com/checkouts", {
method: "POST",
headers: {
authorization: `Bearer ${process.env.DODO_API_KEY}`,
"content-type": "application/json",
},
body: JSON.stringify({
product_cart: [{ product_id: "pdt_…", quantity: 1 }],
customer: { email: user.email, name: user.name },
metadata: {
refref_external_id: user.id,
// Optional: the buyer's browser, for a buyer who did not sign up first.
...(request.cookies.refref_handle && {
refref_handle: request.cookies.refref_handle,
}),
},
return_url: "https://example.com/thanks",
}),
});
const { checkout_url } = await response.json();Dodo copies the checkout metadata onto the subscription and onto each renewal payment, so you write it once. A payment or subscription without refref_external_id gives no fact.
Write the metadata on your server. A payment link that takes metadata from its URL lets the buyer choose it.
Buyers who did not sign up first
A buyer who clicked a referral link and then paid, with no earlier signup, has no identified browser yet. Read the buyer's refref_handle cookie and put its value into the same checkout metadata (customer metadata does not count for the handle) as refref_handle, next to refref_external_id. At the participant's first fact, RefRef identifies that browser to the participant, so the referral click counts.
- RefRef uses the handle only when the participant has no Event yet, and only when the handle is open and belongs to the Project. A handle that a signup already identified changes nothing.
- The first fact is the moment of identification: the start of the subscription, or the one-time payment. A click counts when it is at most 90 days before it.
- A buyer without the cookie, or a checkout without
refref_handle, is attributed only through a referral the participant already has.
What RefRef does with the facts
- First purchase. A billing fact carries no browser data. The start of the Subscription uses the referral that the participant already has, for example from a signup that identified the browser. When the participant has no referral yet and
purchaseis a qualifying event type, the fact can create one from a click in a browser that your backend identified to the participant before, or that the checkout named withrefref_handle. The first payment then gets the referral as its attribution. - Renewals. Each renewal payment inherits the Subscription's referral without a new click, also after the attribution window. A Program rule that pays on each purchase earns a Reward on each renewal.
- Paid history. Before RefRef evaluates a purchase Reward, it reads the referee's Dodo payments between the referral and the purchase, so that a "first purchase" rule counts only a first purchase.
- Refunds and disputes. A refund or a lost dispute reduces the purchase by its share of the payment total. Rewards calculated from that purchase get a matching adjustment. When the purchase is fully refunded, RefRef takes back a Reward that it already delivered: it debits the credit or deletes the discount code. A partial refund leaves a delivered Reward in place.
- Missed events. Every five minutes RefRef reads the payments, refunds, and subscriptions that Dodo created recently, and the lost disputes of the last 120 days, and records any that an event did not bring. Dodo lists subscriptions by creation time only, so a later cancellation of an older subscription arrives only by its event.
Deliver Rewards in Dodo
In the Program's settings, open Delivery and choose Dodo for the Reward kinds that you want RefRef to deliver:

| Reward | Delivery in Dodo |
|---|---|
| Account credit | A credit entry in the customer's Dodo wallet, in USD, EUR, or GBP. Dodo applies the balance before it charges the card for the customer's subscription renewals. A void debits it back. |
| Discount | A single-use percentage discount code that only that customer can use, for the rule's duration: one billing cycle, the rule's months, or every cycle. A code of months is valid only for the subscription products with the shortest monthly or yearly billing cycle, and it lasts the rule's months in those cycles, rounded up (a yearly plan gets one year for 3 months). The customer enters it at checkout. A void deletes the code. |
| Custom | A free upgrade to a higher plan for a number of billing periods. See Give a free plan upgrade. |
RefRef delivers to the Dodo customer of the beneficiary. It learns the customer from the beneficiary's own payments; for a referrer who has not paid through Dodo, send the customer ID as billingIds.dodo with PUT /v1/participants. A Reward whose beneficiary has no Dodo customer yet waits.
A delivery is Dodo's success answer. RefRef does not read whether the customer later used the credit or the code.
Apply a discount at checkout
Dodo does not let RefRef add a discount to an existing subscription, so the Widget shows the customer the code to enter at checkout. You can also apply it for them: send the customer as billingIds.dodo with PUT /v1/participants when they sign up, read their delivered discount with GET /v1/rewards?projectId=…&beneficiaryExternalId=…&benefitKind=discount&fulfillmentStatus=fulfilled, and pass its delivery.code in discount_codes when you create the checkout session for that customer.
Not available: payouts to referrers through Dodo.
Give a free plan upgrade
A custom Reward can move the customer to a higher plan for a number of billing periods. The customer keeps paying the price of the current plan, and then goes back to it automatically.
Set it up
- In the Project's Settings → Custom units, add a unit for the upgrade, for example "Pro month".
- In the Program's rules, give that unit as a custom Reward with a quantity of 1. A plan upgrade refuses another quantity.
- In the Program's Delivery settings, choose Upgrade the plan in Dodo Payments for custom Rewards. Under Plan upgrades, enter for the unit the Dodo product ID (
pdt_…) of the higher plan and the number of billing periods, from 1 to 12. A unit without a plan goes through your product (webhook).

What the customer gets
- At once, RefRef changes the customer's subscription to the higher product, with no charge. The rest of the current billing period on the higher plan is free.
- RefRef gives the customer a flat discount of the price difference for exactly N renewals, for the higher product only. The difference is the higher product's price minus the price of the customer's subscription, so each of these renewals bills the customer's current price.
- After Dodo bills renewal N, RefRef schedules the change back to the lower product for the next billing date and deletes the discount. Renewal N+1 bills the lower product.
Renewal N+1 bills the lower product's price at that time. If you changed that price after the customer subscribed, the customer pays the new price. If the customer changed the plan or the subscription ended, RefRef records this at the switch back and changes nothing.
When RefRef does not upgrade
RefRef changes nothing, and the Reward waits for you with the reason, when:
- The customer has no active subscription, or has more than one.
- The subscription already has a discount.
- The higher product's price is not above the price of the subscription.
- The two plans have a different currency, billing interval, or tax treatment, or the subscription has a quantity other than 1 or add-ons.
The delivery also fails, for you to resolve, when the subscription already has a scheduled plan change.
A void before the switch back changes the subscription back to the lower product at once, with no charge.
A connection made before plan upgrades
A Dodo connection made before plan upgrades were available does not offer Upgrade the plan in Dodo Payments. In Settings → Integrations, select Test connection on the Dodo Payments connection. After the test passes, the option is available.
Test the integration
- Connect a Dodo test-mode key to your Sandbox Project and add the webhook endpoint in test mode.
- Create a referral link for a participant. Open it in a browser on a page with the landing script, and sign up there, so that your backend identifies the browser with the signup.
- Create a checkout session with the metadata, and pay with a Dodo test card.
- In the Sandbox Project, check Referrals and Rewards. A Reward that RefRef delivered through Dodo shows its Dodo reference.
- Refund the payment in Dodo and check the adjustment on the Reward.
Stripe
Connect Stripe so invoices, payments, refunds, and subscriptions become RefRef facts, and deliver credit, promotion codes, and plan upgrades in Stripe.
Paddle
Connect Paddle Billing so transactions, refunds, and subscriptions become RefRef facts, and apply discounts and free plan upgrades in Paddle.