DEV Community: Mihir kanzariya

Give a conversion a status, not a boolean

Mihir kanzariya — Mon, 10 Aug 2026 06:03:37 +0000

The ad platform reports more conversions than the payment processor settled. Nobody wrote a bug. The two systems are counting different things, and they will keep disagreeing for as long as both exist.

The disagreement is by construction

An ad platform counts a conversion when someone it showed an ad to does the thing you told it to watch for, inside a window the platform defines, attributed by rules the platform owns. It is measuring the effect of its own inventory, using its own view of who saw what.

A payment processor counts money that cleared. It has no opinion about which click caused the charge, and it does not care that an ad was involved.

Pull from the ad platform's API and you inherit its window and its attribution model along with the number. That is not a caveat you can strip out. The count is defined by those rules, so importing the count imports the rules. The processor's number carries a different definition: settled funds, minus nothing you have not accounted for yet.

Both are honest answers. They answer different questions, and the moment you write one of them into a column labelled "revenue" you have picked a side without saying so.

Pick the authoritative event, then say which one it is

The engineering decision is small and specific: which event transitions a conversion into revenue?

If the answer is "a webhook from the processor," then the ad platform's API is a signal, not a source. If the answer is "the ad platform's postback," you have built a system that reports money nobody has received.

Most teams never make this decision explicitly. They write a conversion row when the checkout page fires, then join in ad spend later, and the mismatch surfaces months on when someone reconciles the dashboard against a bank statement and cannot explain the delta.

Make the choice in the schema, not in a comment. Every revenue figure your system emits should be traceable to one processor event with an ID you can go look up.

Reversals are the case people skip

Payments settle and then stop being settled. Refunds, chargebacks, a subscription renewal that fails on the second cycle. A dashboard that stamps a conversion as revenue at checkout is recording a fact that can still change, and it does not usually have anywhere to put the change.

The timing is the ugly part. Reversals arrive late. Disputes in particular can land well after the charge, so the most recent period is always the one with the fewest reversals recorded against it. Your last seven days look better than your last seven days will eventually have looked. That number is at its most flattering exactly when someone is reading it to decide whether to raise the budget.

You cannot fix this by waiting, because someone always wants today's number. You fix it by making the uncertainty part of the data.

Subscriptions break conversion value outright

For a one-off purchase, the value of a conversion is knowable shortly after it happens. For a subscription, it is not knowable at conversion time at all. The first payment is a first payment. It is not the customer's value, and it is not a share of the customer's value that you can compute yet.

Any ROAS you calculate on that first charge is a forecast wearing the clothes of a measurement. That is fine if you label it as a forecast. It is not fine when it sits in the same table, in the same font, as spend, which is an amount that really did leave a bank account.

Give a conversion a status, not a boolean

Here is the shape most systems start with:

{
  "click_id": "c_9f21",
  "campaign_id": "cmp_4",
  "converted": true,
  "revenue_cents": 4900
}

converted: true has no room for "settled, then refunded" or "the processor has not confirmed this yet." Anything not final gets rounded to a win, because true is the only value that means anything happened.

{
  "click_id": "c_9f21",
  "campaign_id": "cmp_4",
  "source": "processor",
  "status": "pending",
  "processor_event_id": null,
  "amount_cents": 4900,
  "observed_at": "2026-08-03T11:02:14Z",
  "settled_at": null,
  "reversed_at": null,
  "reversal_reason": null
}

status moves through a small state machine driven by processor webhooks, each transition carrying the event ID that caused it:

observed  ->  settled    (charge succeeded)
settled   ->  reversed   (refund, dispute, failed renewal)
observed  ->  expired    (window closed, no matching payment)

Now a query can ask a real question. Settled and past the dispute window is money. Settled and recent is money that is probably money. Observed is a claim. Expired is the ad platform's count minus the processor's, which is the number people argue about, sitting in a column where you can look at it instead of guessing at it.

Keep the ad platform's figure too, as its own labelled series. Do not overwrite it and do not average it against the processor's. Two series that disagree tell you something. One blended series tells you nothing, and you cannot recover the inputs later.

Where this lands

We run into the same split on the affiliate side. Our attribution window is a 60-day cookie, and we are built on Stripe, so Stripe is where the money actually lands. When our own tool and Stripe disagree, people believe Stripe every time. The design conclusion we took from that is to stop treating our own count as a competing truth and treat it as the claim that Stripe either confirms or does not.

The reason to model status rather than a boolean is not accounting hygiene. It is that "not final yet" is a real state your system observes constantly, and if the schema has no place to put it, the code will put it somewhere wrong.

Disclosure: we build affiliate software for SaaS on top of Stripe, which is how we ended up thinking about this.

Your pricing page is making a forecast and calling it a fact

Mihir kanzariya — Fri, 07 Aug 2026 04:07:03 +0000

This week someone metering LLM calls asked for help with a sentence. He has to state a usage allowance on a pricing page, and neither way of writing it works. "3 million credits" is honest and means nothing to a buyer, because no human can picture three million credits. "About 1,500 generations" is legible, and it becomes a lie the moment usage patterns change. He wanted wording that survives contact with real customers.

Better wording is not the fix. His two sentences do not differ only in how clear they are.

It is a grammar problem.

One thing first, so you can weigh the rest properly. I do not sell a metered product. I run Referralful, affiliate software for SaaS, and our pricing is flat (free until your first affiliate, then $19.99 a month). I have never had to defend a credit estimate to a customer who blew through it in nine days. What follows is reasoning about how the sentence works, not a war story. Every number below is invented for illustration.

A pricing page gets written once and read for years

You write it in an afternoon. Then it sits there through two model migrations, a feature launch that quadruples token use per action, and a slow drift in who your customers even are.

Nothing on that page knows any of this happened. There is no test that fails, no alert, no customer complaining in month one. The sentence just quietly goes from true to false while the deploy log stays empty.

Most pricing-page dishonesty is not intent. It is tense.

Refusing to translate is not the safe option

The obvious defensive move is to retreat to "3 million credits" and let the user work it out. That feels safe because it cannot be wrong.

It is not safe. It moves the estimating work onto someone with strictly less information than you, at the exact moment they are deciding whether to sign up. They cannot do the math, so they guess, and a guess about whether a plan fits usually resolves as "not yet." You did not avoid the risk. You paid for it at the top of the funnel instead of in a support ticket, and you also lost the chance to learn what a realistic month looks like for that customer.

Both sentences are bad. They are bad in different directions, which is why splitting the difference produces something that is vague and wrong.

Change what kind of sentence the number sits in

Forecast:     About 1,500 generations a month.
Observation:  Customers on this plan ran a median of 1,500
              generations in the 30 days to 1 August.

The forecast makes a promise about the future on the user's behalf. It depends on prompt length, model pricing and feature mix, all of which move without anyone touching the page. It decays.

The observation describes something that already happened. It cannot decay, because the past does not change. It also carries more information than the estimate did: a median from real customers tells you what people like you actually do, which is what the reader wanted to know in the first place.

Same shape everywhere:

Forecast:     Enough storage for roughly 50,000 photos.
Observation:  Half of Pro accounts stayed under 12 GB last month.
              Our median upload is 3.4 MB.

Forecast:     Plenty of API calls for a small team.
Observation:  The median team of five made 40,000 calls in July.
              The busiest ten percent made over 300,000.

That last line matters more than the median. Publishing the top decile tells the heavy user to look at the next plan up, before they find out the hard way.

The date is what makes it honest

An observation with no period attached is just a forecast wearing better clothes. "Customers ran a median of 1,500 generations" ages into a claim about now, and then you are back where you started.

So put the window on the page. "In the 30 days to 1 August." Then set a recurring job that recomputes it and a calendar reminder for whoever owns the page. If you cannot commit to the recompute, do not publish the observation, because a stale median is worse than a rough estimate: it looks like evidence.

A number with a date on it is a claim you can defend in a support thread. You show the query.

What to do when there is nothing to observe

You launched last week. You have four customers, two of whom are friends. There is no median, and inventing one is the single worst thing you could do here.

Say so, and publish the mechanism instead. Tell people exactly what consumes a unit, in the units they think in: one credit per generation up to 1,000 output tokens, a long draft usually costs four to six, image generation costs twelve. Now the reader estimates for themselves with your actual arithmetic rather than your optimism, and nothing on the page can rot except the price list.

Then replace it with a real median the month you have one.

Unlimited is the same bug, louder

"Unlimited" is a forecast about your own tolerance. It is true right up until someone builds a business on top of your generosity, at which point you write a fair-use clause and quietly redefine the word.

That walk-back happens by email, to the one customer causing pain, while the pricing page keeps making the original promise to everyone else.

A number with a date on it is a claim. The same number with the date stripped off is a promise, and you do not get to decide when you have broken it.

Your deferred revenue schedule breaks the first time a customer upgrades mid-term

Mihir kanzariya — Thu, 06 Aug 2026 13:24:59 +0000

Yesterday I argued a point over four turns with the author of a revenue-recognition tool, under his post about recognizing Stripe annual subscriptions with the actual journal entries. He conceded the gap was real and shipped a fix into his product about two hours later. The argument is worth writing down, because the shape of the bug is common and the usual trigger people wire it to is the wrong one.

First, my position. We do not run a deferred-revenue ledger. We build affiliate software for SaaS on Stripe, so everything below comes from the subscription and webhook side, from watching what Stripe actually emits and when. I said that to the author mid-thread, and I think it is why the advice landed. Where the reversal lands in your books is your accountant's call, not mine.

The model that works right up until it doesn't

A customer pays $1,200 for an annual plan. You create a deferred revenue schedule keyed to that invoice and release $100 a month for twelve months. Clean. Auditable. Every textbook draws it this way.

That model holds exactly as long as nothing changes.

Month five

The customer upgrades. Or downgrades, or moves from 8 seats to 14. Stripe prorates, and on that date two things move at once: what the customer is entitled to for the rest of the term, and what you still owe them in service.

Your schedule knows about neither. It keeps releasing $100 a month against a contract that no longer exists in that form. You are recognizing revenue on terms nobody agreed to anymore, and the error compounds every month until the term runs out.

Mid-term cancellations and refunds have the same shape. The remaining deferred balance has to come off, not continue.

Close out and reopen

The fix is to close the original schedule at the change date and open a new one for the amended terms. Two other options look reasonable and both are worse.

Leaving the old schedule running and adding a second one for the delta. This is the one that bites, and it is the most common instinct because the proration genuinely is a delta. The original schedule keeps releasing revenue against a term that ended in month five. Adding a correct schedule next to an incorrect one gets you a wrong total.

Mutating the original schedule in place. You end up with an accurate present and no record of what was contracted first. When someone asks in month nine what the customer originally bought, the answer is gone.

Close-out plus a new schedule matches the shape Stripe already hands you. Proration arrives as new invoice line items, not as an edit to the original invoice. The original invoice is immutable once finalised; Stripe writes credit and debit lines with their own period.start and period.end covering the remaining term. Modelling your ledger the same way keeps it aligned with the source system instead of drifting from it every time someone changes plan.

The practical payoff is provability. Each schedule's deferred balance resolves to zero on its own, over its own window:

schedule_A: original terms,   Jan 1 -> May 14  (closed out, balance 0)
schedule_B: amended terms,    May 14 -> Dec 31 (releasing)

A schedule amended twice in place never resolves cleanly. The author had described chasing a stranded four cents that would not clear months later, which is the exact symptom this prevents. Rounding residue on a partially-consumed period has nowhere to go when the schedule that created it has been overwritten. Give it its own close-out and the four cents close out with it.

Cancellation is the same shape, and the trigger is where people get it wrong

Close out at the cancellation date so the unearned remainder comes off. Straightforward.

Then comes the part nobody writes about. Do not trigger the close-out off a credit note existing.

Walk the actual paths. Cancelling at period end, which is Stripe's default and the normal SaaS flow, produces no proration and no credit note at all. The subscription sets cancel_at_period_end, the customer runs out the term they already paid for, and at the end Stripe flips the status. Nothing gets credited because nothing needs crediting. Cancelling immediately with proration generally gives you a credit balance on the customer or a proration line on the next invoice, depending on proration_behavior and whether an invoice gets raised. A refund is its own object again, against the charge or payment intent.

Credit notes mainly turn up when you credit an invoice that is already finalised.

So a close-out that fires on credit_note.created misses the most common cancellation path entirely. Not an edge case. The default one. Every customer who cancels normally keeps releasing deferred revenue on your books until someone notices.

Key it off the subscription state instead:

// customer.subscription.updated / customer.subscription.deleted
const endsAt = sub.cancel_at
  || sub.canceled_at
  || currentPeriodEnd(sub);   // period fields moved onto
                              // subscription items in recent
                              // API versions, check yours

if (sub.cancel_at_period_end || sub.status === "canceled") {
  closeOutSchedule(sub, { at: endsAt });
}

// credit notes: reconcile against, do not trigger on

Treat a credit note as a second signal, useful for reconciling the amount, never as the thing that starts the process.

One nuance worth keeping. On a period-end cancellation you do not reverse the months you already earned. The customer consumed that service and you keep it. Close out only the future portion, which on a clean period-end cancellation is often zero anyway, since the term runs to its natural end. The value there is that the schedule stops rather than rolling into a renewal that never happens.

The general shape, not a guarantee

A lot of this is configurable. proration_behavior alone changes what lands on the invoice, whether an invoice gets raised at all, and whether the money moves through the customer balance. Field locations move between API versions, subscription period fields being the recent example. Test against your own account, on your own version, with a real upgrade and a real cancellation, and read what actually arrives on the webhook rather than what the docs imply should.

The durable part is the principle. Anything that changes the term changes the schedule, so close the old one and open a new one, and derive your triggers from the subscription object rather than from an artifact that only shows up on some of the paths.

Detecting affiliate self-referrals with Stripe's payment method fingerprint

Mihir kanzariya — Wed, 05 Aug 2026 04:35:33 +0000

The self-referral problem

Someone signs up for your affiliate program, grabs their referral link, opens a private window, creates a second account with a different email, and pays for a subscription through their own link. Now they collect a commission on the money they just paid you. If your commission is recurring, they have effectively given themselves a permanent discount and you are paying the processing fees for the privilege.

The variant that is harder to argue with: the affiliate has a real second business, or a family member signs up, or an agency refers a client and then pays the client's bill. Some of that is legitimate. Some of it is not. Either way you need to see it before you pay out, not after.

The signals most programs check are the ones easiest to defeat

Almost every affiliate system I have looked at checks three things: email address, IP address, and some flavour of device fingerprint.

A second email costs nothing and takes ten seconds. An IP address is one VPN toggle away, and residential proxy pools are sold by the gigabyte. Device fingerprints get defeated by a fresh browser profile, and anti-detect browsers exist specifically to sell that capability to people who want it.

There is a pattern here. The signals that are cheap for you to collect are also cheap for the other side to produce. If you want a check that actually costs the attacker something, you have to find something they cannot mint on demand.

The card is the expensive signal

Fifty email addresses cost nothing. Fifty distinct working payment cards, each attached to a real funding source, is a different kind of problem. That asymmetry is the whole reason card data is worth checking.

Stripe exposes a fingerprint field on the card object of a PaymentMethod. It is an opaque string Stripe generates from the underlying card number, and it stays stable for that card across different Customer records. Two accounts with different emails, different IPs, and different browsers still produce the same fingerprint when the same physical card pays both bills.

One thing to be precise about, because people build the wrong thing here: the fingerprint is consistent within a single Stripe account. It is not a global identifier shared between merchants. You cannot ask another company whether they have seen this card, and you cannot compare fingerprints across two of your own Stripe accounts. For self-referral detection that limitation does not matter, because you are only ever comparing customers inside your own account.

Reading and storing the fingerprint

You can read it off a PaymentMethod directly:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const pm = await stripe.paymentMethods.retrieve(paymentMethodId);
const fingerprint = pm.card?.fingerprint ?? null;
const funding = pm.card?.funding ?? "unknown";

It also appears on a Charge, which is useful if you are backfilling from historical payments rather than instrumenting signup:

const charge = await stripe.charges.retrieve(chargeId);
const fp = charge.payment_method_details?.card?.fingerprint ?? null;

Store the fingerprint, never the card number. The fingerprint is an opaque Stripe-generated string with no card data inside it, so persisting it in your own database is safe and does not drag you into extra PCI scope. Keep it in a table that allows several rows per user, because people legitimately change cards.

create table user_card_fingerprints (
  user_id     uuid        not null,
  fingerprint text        not null,
  funding     text        not null default 'unknown',
  first_seen  timestamptz not null default now(),
  primary key (user_id, fingerprint)
);

Write to it from a webhook, so you capture cards attached outside your own checkout flow:

// invoice.payment_succeeded / setup_intent.succeeded handler
async function recordFingerprint(userId: string, pm: Stripe.PaymentMethod) {
  const fp = pm.card?.fingerprint;
  if (!fp) return; // non-card methods and some tokens have none

  await db.query(
    `insert into user_card_fingerprints (user_id, fingerprint, funding)
     values ($1, $2, $3)
     on conflict (user_id, fingerprint) do nothing`,
    [userId, fp, pm.card?.funding ?? "unknown"]
  );
}

The check at conversion time

When a referred customer converts, compare their fingerprints against every fingerprint on record for the affiliate who referred them. Return a signal with reasons attached, not a boolean. You will want the reasons later, when a real affiliate emails you asking why their commission is on hold.

type RiskLevel = "low" | "review" | "high";

interface SelfReferralSignal {
  level: RiskLevel;
  reasons: string[];
  matchedFingerprints: string[];
}

export async function scoreSelfReferral(
  referredUserId: string,
  affiliateUserId: string
): Promise<SelfReferralSignal> {
  const [buyer, affiliate] = await Promise.all([
    getFingerprints(referredUserId),
    getFingerprints(affiliateUserId),
  ]);

  const affiliateSet = new Set(affiliate.map((c) => c.fingerprint));
  const matched = buyer.filter((c) => affiliateSet.has(c.fingerprint));

  const reasons: string[] = [];
  let level: RiskLevel = "low";

  if (matched.length > 0) {
    reasons.push("Buyer paid with a card already on file for the affiliate.");
    level = "high";
  }

  if (buyer.some((c) => c.funding === "prepaid")) {
    reasons.push("Buyer paid with a prepaid card.");
    if (level === "low") level = "review";
  }

  return { level, reasons, matchedFingerprints: matched.map((c) => c.fingerprint) };
}

Three limits, and they are not small

Virtual cards defeat this outright. Services that mint a fresh virtual card per merchant give each one a distinct card number, which produces a distinct fingerprint. Ten virtual cards look like ten unrelated strangers. There is no clever query that recovers the link, because the link does not exist in the data you have. Anyone determined enough to run a self-referral ring at scale will find this hole, and the check is worthless against them.

Prepaid cards are a visible signal, which is a different situation. Stripe reports funding on the card object with values of credit, debit, prepaid, or unknown. A prepaid card does not tell you fraud is happening, and plenty of legitimate customers pay that way. It belongs in a look-closer tier:

const funding = pm.card?.funding; // "credit" | "debit" | "prepaid" | "unknown"
if (funding === "prepaid") flagForReview(userId, "prepaid_funding");

Shared corporate cards produce false positives, cutting the opposite way. Five colleagues expensing seats on one company card collapse into a single actor under fingerprint matching. If one of them joined your affiliate program and referred the other four, the naive check accuses an entirely honest person. I would rather ship a system that misses some fraud than one that emails a good affiliate to tell them their commission is cancelled for something they did not do.

Combine weak signals, then defend the decision

The question worth asking is not which identifier is perfect. None of them are. The question is how you combine several weak signals into a decision you can explain, in plain sentences, to a legitimate affiliate you are about to accuse.

Card signals earn their place because they are expensive to fake, not because they prove anything on their own. Build three tiers. Low risk pays out normally. Suspicious holds the commission and creates a review item with the reasons attached. Clear-cut, meaning an exact fingerprint match plus supporting evidence like a matching billing name or a signup minutes after the referral click, gets blocked with a written explanation. Never auto-claw-back on a single signal, because the one time you are wrong you will burn an affiliate who was sending you real customers.

The cost, stated plainly

Requiring a card before a trial measurably reduces signups. That is why plenty of product-led teams refuse to do it, and they are not being sloppy. Whether the trade pays off depends on what the abused resource costs you. For a cheap-to-serve SaaS seat, eating some self-referral is usually cheaper than the signups you lose at the gate. For expensive compute where every trial burns real money, the card requirement often pays for itself immediately.

I work on affiliate software for SaaS built on Stripe, which is how I ended up staring at fingerprint fields for longer than anyone should.

Your referral links lose attribution in the redirect chain, not at checkout

Mihir kanzariya — Tue, 04 Aug 2026 05:59:11 +0000

A referral link is the shortest piece of infrastructure in your product and the one most likely to lose data silently.

The setup looks trivial. An affiliate gets yoursite.com/?ref=alice. You read ref on page load, stash it somewhere, attach it to the Stripe Checkout Session, and pay out on the webhook. You paste the link into your browser once, see alice in the console, and call attribution done.

Then payouts come in low, an affiliate emails asking why a sale they clearly drove is not showing, and you go looking at the last hop.

The last hop is almost never where it broke

The debugging path is predictable. You check the Checkout Session in the Stripe dashboard, find metadata.ref empty, and start reading your checkout code. Maybe you add logging around the session creation. Maybe you suspect a race between the cookie write and the click on the pricing button.

Meanwhile the value was already gone three hops earlier, before your app rendered a single byte.

The tell is that attribution works perfectly on localhost and fails only in production. Local has no canonical-host redirect, no CDN rule, no locale router, no shortener, no in-app browser. Production has all of them, and several will rebuild your URL from scratch.

Where the query string actually dies

Canonical host redirects. You redirect http to https, or bare domain to www, or the reverse. A lot of redirect rules construct the target by string concatenation and never reattach the query. This is the single most common way a ref param evaporates, and it is invisible because the page still loads fine.

server {
    listen 80;
    server_name example.com;

    # fine: $request_uri is the original path AND query
    return 301 https://www.example.com$request_uri;

    # broken: $uri is the normalized path with no query
    # return 301 https://www.example.com$uri;
}

One character of difference decides whether your affiliate gets paid. The same trap exists in every layer that can redirect: CDN rules, load balancer listeners, framework config.

// next.config.js
module.exports = {
  async redirects() {
    return [
      { source: "/pricing", destination: "/plans", permanent: true },
    ];
  },
};

Next.js forwards query params on redirects by default, but only if you have not written your own destination with a hardcoded query, and only if the hop is actually handled by Next rather than by the platform sitting in front of it. Check the hop that is actually running, not the one in your repo.

Locale and geo redirects. example.com/?ref=alice becomes example.com/en/. Same mechanism, different layer, and it usually lives in middleware written by whoever set up i18n rather than by whoever set up the affiliate program.

Shorteners and social wrappers. An affiliate runs your link through a shortener, or posts it somewhere that rewrites outbound links. Some wrappers preserve the query and append their own. Some pass the whole thing as a single encoded parameter to an interstitial and reconstruct it. Some strip anything they do not recognize.

In-app browsers. A click inside a mobile app opens a webview with a fresh cookie jar. Whatever you wrote on a previous visit in the real browser does not exist there, and whatever you write inside it may not survive the user tapping "open in Safari" afterward.

Marketing site to app domain. The ref lands on example.com, your signup and checkout live on app.example.com, and the cookie you wrote is scoped to the marketing host. The origin that writes the value is not the origin that later reads it, so at checkout there is nothing to read.

Meta refresh and client-side router redirects. A <meta http-equiv="refresh" content="0; url=/home"> or a router.replace("/dashboard") inside an auth guard rewrites the location without the query. These are especially easy to miss, because your server logs still show the original request with the param present.

The principle

Capture the referral at the earliest possible hop and persist it first-party. Do not carry the query string end to end.

The query string is a transport. It gets one job, which is to hand you a value on first paint, and then it is allowed to disappear. Every hop after that reads from your own storage. If your checkout code still expects to find ?ref= in window.location, you have built a chain where any single link breaks the whole thing.

// runs as early as possible on first paint, on the marketing domain
const REF_COOKIE = "rf_ref";
const MAX_AGE = 60 * 60 * 24 * 60; // 60 days

function captureRef() {
  const ref = new URLSearchParams(window.location.search).get("ref");
  if (!ref) return;
  if (document.cookie.includes(`${REF_COOKIE}=`)) return; // first touch wins

  document.cookie = [
    `${REF_COOKIE}=${encodeURIComponent(ref)}`,
    "path=/",
    "domain=.example.com", // top-level, so app.example.com can read it
    `max-age=${MAX_AGE}`,
    "samesite=lax",
    "secure",
  ].join("; ");
}

Two details matter more than the rest. The cookie domain is the registrable domain with a leading dot, so subdomains share it. And first touch wins here, so a returning visitor who arrives later through a different affiliate does not silently overwrite the credit. Last touch and first touch produce different payouts, and your affiliates will eventually notice which one you picked, so decide deliberately and put it in your program terms.

Then at checkout, read your own storage and hand it to Stripe.

import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function createCheckout(req, res) {
  const ref = req.cookies["rf_ref"] ?? null;

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: req.body.priceId, quantity: 1 }],
    success_url: "https://app.example.com/welcome",
    cancel_url: "https://app.example.com/plans",
    metadata: ref ? { ref } : {},
  });

  res.json({ url: session.url });
}

metadata is the only Stripe-specific piece here. It rides along to the webhook, and the value you read there is whatever your own cookie held, not whatever survived the redirect chain.

Verify the paths, do not trust them

Most affiliate programs never write a test for this, which is strange given that the whole revenue share depends on it. The test is short. Walk your own referral link through each real entry path and assert the cookie exists at the end.

http://example.com/?ref=alice
http://www.example.com/?ref=alice
https://example.com/?ref=alice
https://www.example.com/?ref=alice
https://example.com/pricing?ref=alice     # any path with its own redirect rule
https://your-shortener.example/abc123

For each one, follow redirects and check the final Set-Cookie and the final URL. curl -sIL gets you most of the way for the server-side hops. The client-side ones need a real browser, so a short Playwright script that visits each URL and reads document.cookie covers the rest. Do the in-app browser check by hand once, on a real phone, from whichever app your affiliates actually post in.

Run it after any change to redirect config, not just once at launch. Redirect rules get edited by people who have no idea an affiliate program depends on them.

One caveat, because a cookie is not forever

Fixing the redirect chain gets the value into your storage. It does not make that storage permanent: Safari's Intelligent Tracking Prevention caps the lifetime of cookies written through document.cookie, which is a separate problem I wrote about in Your 60-day affiliate cookie is lying on Safari. A cookie set by the server through a Set-Cookie header is treated differently from a script-written one, which is a real argument for capturing the ref server-side during that first request.

The shape that survives both problems: capture early, set it server-side where you can, and write the referral against the user record the moment someone signs up. The cookie only has to survive the gap between the click and the account, and that gap is the part you can actually control.

I work on affiliate software for SaaS companies, and the redirect chain is the first place I would look when a payout number does not match what an affiliate says they drove.

The affiliate commission you never actually pay out

Mihir kanzariya — Sun, 02 Aug 2026 18:53:15 +0000

The balances that never move

Run this query against your commission table: sum of unpaid commission, grouped by affiliate, where the affiliate has had no new conversion in the last twelve months. On most programs that have been running a while, the result is a long tail of accounts holding 4, 11, 27 units of currency each, and none of it is ever going anywhere.

That tail is not a bug in your payout code. It is the direct output of a rule you almost certainly wrote on purpose, and then stopped thinking about.

What a threshold actually creates

Nearly every program sets a minimum payout. Fifty is a common number. The reasoning is sound: a fixed cost attaches to each transfer, whether that cost is a processor fee, a compliance check, or ten minutes of a human reconciling something. Sending 3 units to two hundred people is a worse use of money than not sending it.

The consequence, though, is a permanent holding pen. An affiliate signs up, posts one link, drives one sale, earns 12, and drifts away. Twelve is below fifty. It will be below fifty forever, because nothing is going to move it. Your liability line grows by 12. Their balance sits at 12. Neither of you thinks about it again.

Multiply that by everyone who tried your program once. The arithmetic is not dramatic per account and it is not small in aggregate.

You have several defensible answers. Run an annual sweep that pays everything out regardless of threshold, eating the fee on the small ones as a cost of running a program. Or write an expiry into the terms, with a stated window and a warning email before it lands. Or drop the threshold to whatever amount makes the fee tolerable and let small balances flow.

What is not defensible is having no answer, because from the affiliate's side, an indefinite hold and a refusal to pay look exactly the same. They cannot see your reasoning. They can only see that they earned money and never received it.

The affiliate who never finished payout onboarding

Second version of the same problem, with a different cause. Someone signs up, drives a real conversion, and never completes the details you need in order to send money. Identity checks, bank details, whatever your processor requires. The commission is real. It is owed. It is unsendable.

Two options exist and both are fine. Hold it indefinitely, which means carrying an unbounded liability against an account that may never come back. Or expire it after a stated window, with reminders on the way.

The rule you cannot get away with is deciding this the day someone emails you fourteen months later asking where their 340 went. Whatever you pick has to be written down before it applies to anybody, because a policy invented at the moment of the dispute is not a policy.

Here is the guard that decides whether a balance is payable at all. Note that a zero return has several distinct causes, and your affiliate dashboard should say which one applies rather than showing a bare "not yet".

// Amount you can actually send right now, in minor units.
function payableAmount(affiliate, ledger, policy) {
  const owed = ledger.owedMinor(affiliate.id);

  if (owed < 0) return 0;   // carried clawback, see the reversal section below
  if (owed === 0) return 0;

  // Onboarding incomplete: keep accruing, do not attempt a transfer.
  if (!affiliate.payoutsEnabled) return 0;

  // The sweep is the escape hatch that stops small balances living forever.
  if (owed < policy.thresholdMinor && !policy.isSweepRun) return 0;

  return owed;
}

Initiated is not paid

Now the failure that damages trust fastest, because your system reports success while the affiliate receives nothing.

You create a transfer. The API returns an object with an id. Your code writes status = 'paid' and moves on. Later, the money comes back. The destination bank account was closed. The connected account lost its ability to receive payouts between the time you checked and the time the money moved. Something in the chain rejected it.

Your ledger now says paid. Your balance says the money is still here. The affiliate says nothing, because they are waiting, and they will wait a while before they write to you.

The fix is a state name. Creating a transfer means you asked for money to move. It does not mean money moved.

const transfer = await stripe.transfers.create(
  {
    amount: payable,
    currency: "usd",
    destination: affiliate.connectedAccountId,
    metadata: { affiliate_id: affiliate.id, batch_id: batchId },
  },
  // Re-running a batch must not send twice.
  { idempotencyKey: `payout:${affiliate.id}:${batchId}` }
);

// Not "paid". The request succeeded, the money has not landed.
await ledger.transition(affiliate.id, batchId, "initiated", {
  transferId: transfer.id,
});

The transition from initiated to settled belongs in your webhook handler, not in the function that created the transfer. The transition back to owed belongs there too, driven by whatever failure or reversal signal your processor sends.

I am deliberately not naming those events. Stripe exposes events covering transfers, reversals, and changes to a connected account's status, and the exact set available to you depends on your API version and your Connect configuration. Read the event list in your own dashboard and confirm against current docs rather than trusting a name you read in a blog post, this one included. The mechanism is what matters: something asynchronous can undo a transfer you already created, and if you have no handler for it, your ledger will be wrong and nothing will tell you.

The reversal that lands after the money left

A customer refunds in week six. You paid the commission on that sale in week four. You cannot reach into someone's bank account and take it back.

So the balance goes negative, and future commission pays it down. That part is easy to build.

The part worth deciding early: what happens when that affiliate never earns again. You are holding a negative balance against an account that has gone quiet. At some point you write it off, and the only question is whether you decided that in advance or in the moment. Decisions made in the moment tend to be made while annoyed, and they tend to be applied inconsistently across affiliates, which is exactly the thing that turns into a public complaint.

Also worth writing down: whether refunds after some window stop clawing back at all. Many programs cap the clawback period. If yours does not, say so, since an affiliate who gets a deduction eleven months after a sale will assume you invented the rule that morning.

The part that is not code

Every state I have described is a promise to a person who sent you customers.

A threshold nobody mentioned at signup. A balance that expired with no email. A payout your dashboard marked paid that never arrived. To the affiliate, all three read as being cheated, and the fact that your code did precisely what it was written to do is not a defence they can see or verify.

Two things fix most of this. Your terms and your ledger state names should describe the same reality, in the same words, so that "pending" in the affiliate's dashboard means the thing your terms say it means. And the affiliate should be able to see which state their money is in without asking you, including the unflattering states.

Decide these before your first payout run

What the minimum payout is, and what happens to balances that will never reach it.
Whether you run a sweep, when, and whether you absorb the fee on small amounts.
How long you hold commission for someone who never completed payout onboarding, and how many reminders they get first.
Which ledger state means requested and which means confirmed landed, and which one your dashboard shows the affiliate.
What moves a commission back to owed, and which handler owns that transition.
How long after a sale a refund can still claw back commission.
What happens to a negative balance on an affiliate who stops earning.

Write the answers into your terms first, then name your database states after them. Doing it in that order is easier than reconciling the two later.

Your affiliate commission should not include VAT, and invoice.total does

Mihir kanzariya — Sat, 01 Aug 2026 18:52:33 +0000

An affiliate refers a customer in Germany. The customer pays EUR 120. Your affiliate agreement says 30%, so your system pays out EUR 36. Except the plan is EUR 100 and the other EUR 20 is VAT that you are holding on behalf of the German tax authority until you remit it. The honest commission was EUR 30. You just paid EUR 6 out of money that was never yours.

Nothing looks wrong, so this can sit there for months. The invoice says 120, the payout says 36, and 36 is 30% of 120. The arithmetic is fine. The base is wrong.

Tax you collect is not revenue you earned

The rule is simple once you say it out loud. Sales tax, VAT and GST are pass-through. The customer pays it, you hold it, you hand it to a government. It sits on your balance sheet as a liability, not as income. So it has no business being in the base you compute a partner's cut from, any more than you would pay commission on a Stripe processing fee.

It is easy to agree with that sentence and still write invoice.total, because that is the field with the obvious name.

Tax-exclusive pricing is the easy case, inclusive is the trap

Where tax gets added on top of the price, which is the usual US sales tax setup, the bug announces itself. Your $100 plan invoices at $108.75, the payout line reads $32.63 instead of $30.00, and eventually someone in finance or an affiliate with a spreadsheet asks why the number has cents in it.

Tax-inclusive pricing gives you no such warning. This is standard for EU consumer pricing, where the advertised number has to be the number the customer pays. Your EUR 120 price is EUR 100 of revenue and EUR 20 of VAT that Stripe backs out of the amount charged rather than adding to it. The invoice total is 12000. It was always going to be 12000. There is no odd cent to notice and no line that looks inflated.

The giveaway is usually not the payout at all. It is that two customers on the same plan, one in a country with VAT and one without, produce different commissions for the same affiliate on the same product. That is the signal worth alerting on if you want a cheap check: same price, same plan, different commission, go and look at the tax treatment.

The fields, with a warning about your API version

Read this section with your own account's API version open, because Stripe has reshaped the tax fields on Invoice more than once and the names below are not stable across every version you might be pinned to. In the 2025-03-31.basil release, the flat invoice.tax and the total_tax_amounts array were reorganised into a total_taxes array, and line-item tax data moved as well. If you are on an older pinned version you will still see the old shape. If you upgrade, the shape changes underneath you.

What each amount field means, as of the versions we have run:

subtotal is the sum of the line items before any invoice-level discount and before tax that gets added on top. Item-level discounts are already baked in. The word "subtotal" reads like it means "before tax", and under exclusive tax it effectively does. Under inclusive tax it does not, because the tax was never added on top to begin with. It is already inside the line amounts, so it is already inside the subtotal.

subtotal_excluding_tax strips tax out but still sits before invoice-level discounts.

total_excluding_tax is the one you usually want. It applies every discount and then removes all tax, inclusive tax included.

total is the end of the line. Discounts applied, tax applied, this is what the customer owes.

The distinction that decides your number is subtotal_excluding_tax versus total_excluding_tax, and it is entirely about discounts. An invoice-level coupon lands between them. Pick the first and you commission on the list price. Pick the second and you commission on what the customer actually paid you, net of tax. They differ by exactly the invoice-level discount, which means on any invoice without one they agree, which means your test suite will happily pass while the field is wrong.

const invoice = await stripe.invoices.retrieve(invoiceId);

// total_excluding_tax: discounts applied, all tax removed (inclusive tax too).
// Falling back to `total` here would silently commission on VAT.
const base = invoice.total_excluding_tax ?? invoice.total;

const commissionCents = Math.round(base * 0.30);

That ?? fallback is a decision, not a formality. If the field comes back null on your version, falling through to total is the exact bug this article is about. Throwing, or flagging the invoice for a human, costs you an alert. The fallback costs you money on every EU invoice.

Two things worth checking before you trust any of this in production. Confirm your version returns the field at all rather than undefined, since an undefined value in JavaScript multiplied by a rate gives you NaN and a payout row that reads as zero. And confirm on an invoice with a discount and inclusive tax together, because that is the case where every field disagrees with every other field.

The discount question rides along

If the affiliate's own coupon gave the customer 20% off, do you pay them on the list price or on what the customer paid?

Both are defensible and plenty of programs pay on list. Just look at what pre-discount does to incentives. The affiliate earns more by discounting harder, and you write a cheque against money that never arrived. A partner with a 40% coupon and a pre-discount base is running a lever you handed them. Post-discount keeps everyone pointed at the same number.

Refunds inherit the same mistake

Refund half of that EUR 120 invoice and Stripe gives back EUR 60, of which EUR 10 is VAT. Your clawback should be 30% of EUR 50, so EUR 15. Compute it off the gross EUR 60 and you claw back EUR 18, taking EUR 3 out of an affiliate's pocket that they earned.

const refund = await stripe.refunds.retrieve(refundId);

// Apply the same ex-tax ratio the original invoice had.
// refund.amount is gross, so scaling by it directly over-claws on the tax.
const taxRatio = base / invoice.total;
const clawbackCents = Math.round(refund.amount * taxRatio * 0.30);

Over-clawing is worse than overpaying, by the way. Overpaying is a number nobody checks. Clawing back too much is a number your partner checks the same afternoon.

Then explain it, in one sentence, before anyone asks

Your affiliate opens their dashboard and sees EUR 30. Their referred customer told them the deal was EUR 120. They do the division, get 25%, and email you asking why the rate dropped.

You are right and you still look like you are shorting them, which is the worst position to argue from. Put one line in the program terms: "Commission is calculated on the net amount excluding VAT, sales tax and GST." That is the whole fix. Getting the arithmetic right and never explaining it is its own kind of failure, and it is the one that generates the support ticket.

What to check on your own account

Pull a paid invoice from a VAT-inclusive country and compare total, subtotal, subtotal_excluding_tax and total_excluding_tax side by side. If all four match, you have not tested the case that matters.
Grep your commission code for invoice.total and amount_paid. Both include tax.
Pin your API version explicitly and re-read the Invoice object docs at that version rather than the latest ones.
Run the same plan through a taxed and an untaxed country and confirm the commission comes out identical.
Check your clawback path separately from your payout path. They are usually written months apart by different people.

Usage-based pricing breaks affiliate commissions written for flat plans

Mihir kanzariya — Fri, 31 Jul 2026 18:56:04 +0000

A flat plan makes affiliate commission trivial. Twenty percent of a $49 invoice is $9.80, every month, forever.

Add usage-based or hybrid pricing and that one line of code has four bugs in it. None of them throw.

1. Which amount?

An invoice is not a number. A single Stripe invoice carries subtotal, total, subtotal_excluding_tax, total_excluding_tax and amount_paid, and on a usage-based invoice they are frequently all different.

The common bug is commissioning on total, which includes tax. You collect that tax and remit it to a government. Paying an affiliate a percentage of it means paying out of margin on money that was never yours.

amount_paid has the opposite problem. If the customer had account credit, amount_paid is lower than what they were actually billed, and your affiliate silently earns less for a reason that has nothing to do with them.

Pick the base deliberately. For most programs that is the pre-tax subtotal after discounts.

2. Which lines?

Flat plans have one line. Usage invoices have several: the base subscription, a line per metered price, proration adjustments, one-off charges somebody added in the dashboard.

If your program pays on subscription revenue but not on overage, or not on professional services, you cannot compute from the invoice total at all. Walk invoice.lines and filter by price or product. Decide which products are commissionable and encode that decision. Do not infer it from the amount.

3. The invoice that arrives after cancellation

Metered usage is billed in arrears. The customer cancels on the 3rd and an invoice lands on the 5th for usage they already incurred.

If your rule is pay commission while the subscription is active, you skip a legitimate invoice. If your rule is pay on every invoice, you also pay on true-ups you meant to exclude.

The subscription status at the moment the invoice finalises is the wrong test. The period the usage belongs to is the right one, and it is on the line item.

4. Reversals stop being boolean

On a flat plan a refund is the whole thing, so a refunded flag is a usable trigger.

On usage-based billing partial refunds are ordinary. A customer disputes one month of overage, not the plan. Clawing back the full commission is wrong. Clawing back nothing is also wrong.

Claw back in proportion: amount_refunded / amount, applied to the stored commission.

And wire charge.dispute.created as well as charge.refunded. They are separate events, the money leaves faster on a dispute, and a system listening only for refunds keeps paying commission on revenue it no longer holds.

What makes all four survivable

Compute the commission once and store the basis you used on the commission record: which amount, which lines, which period.

Do not recompute from the invoice later. Invoices are not immutable in practice. Credits get applied, disputes resolve, and a recomputation months later will quietly disagree with what you already paid. When it disagrees you will have no way to tell which number is the bug.

Store the number and the reason for it. Reconcile from events, not from current state.

What a failed renewal does to an affiliate commission you already paid

Mihir kanzariya — Thu, 30 Jul 2026 19:08:15 +0000

If you run an affiliate program on Stripe subscriptions, you pay commission when an invoice gets paid. The part that quietly breaks is what happens when a renewal that already earned someone a commission stops being paid.

Most implementations reverse on the wrong event. I had the shape of this wrong myself until I sat down with the retry docs and read what actually fires.

The event everyone reverses on is the wrong one

invoice.payment_failed looks like the obvious trigger. Stripe describes it as: "Occurs whenever an invoice payment attempt fails, due to either a declined payment, including soft decline, or to the lack of a stored payment method."

Attempt is the load-bearing word. It fires once per attempt, and the Smart Retries docs say "The recommended default setting is 8 tries within 2 weeks." So a single doomed invoice can fire that event eight times. If your handler reverses a commission each time, you have clawed back the same commission eight times.

The second problem is worse, because it is silent. Most failed attempts are temporary. The card works on attempt three, the invoice gets paid, and you have already reversed a commission that was genuinely owed. Nobody files a bug for this. Your affiliate just quietly earns less than they should.

The dunning window is an ambiguity window

For up to two weeks on default settings, you do not know whether that commission is owed. That is not a problem to engineer around, it is just true, and the design should say so.

Give commission rows a third state. Something like pending_recovery, entered on the first failure, exited on either invoice.paid or a terminal outcome. During that window you do not pay it out and you do not reverse it. Holding is the honest answer, and it is also the one that stops you paying out money you may need to chase back.

Which terminal event, and the trap that bit me

When retries run out, the docs are clear that Stripe stops: "After the final payment attempt, we make no further payment attempts."

What happens to the subscription depends on a setting the merchant chose, and there are three options:

Setting	Result
Cancel the subscription	"changes to a `canceled` state after the maximum number of days defined in the retry schedule"
Mark the subscription as unpaid	"changes to an `unpaid` state ... Invoices continue to be generated and stay in a draft state"
Leave the subscription overdue	"remains in a `past_due` state ... Invoices continue to be generated and charge customer based on retry settings"

So the natural move is to reverse on a terminal invoice event, and the two candidates are invoice.marked_uncollectible ("Occurs whenever an invoice is marked uncollectible") and invoice.voided ("Occurs whenever an invoice is voided").

Here is the trap. uncollectible is a manual status. The invoice workflow docs describe it only as something a person does: "you can update the status of the invoice to be uncollectible", offered either as a Dashboard action or an API call. The status itself means "The customer is unlikely to pay the invoice. Normally, you treat it as bad debt in your accounting process." There is no documented automatic transition from open or past_due into it.

Which means: if the merchant is on "leave the subscription overdue", nothing marks that invoice uncollectible unless a human does it as a bookkeeping chore. invoice.marked_uncollectible may never fire at all. Your commission sits in pending_recovery forever, against revenue that is never arriving.

Worth separating void here too, because people reach for it as a synonym and it is not one. Voiding "is conceptually similar to deleting or cancelling it. However, voiding an invoice maintains a paper trail", and "Voided invoices are treated as zero-value for reporting purposes, and aren't payable." Uncollectible is bad debt you still recognise. Void is an invoice that stops existing for reporting. They are different accounting statements and they deserve different commission handling.

What to do instead

Do not hang reversal on a single invoice event.

Listen for customer.subscription.deleted and customer.subscription.updated as well, since two of the three end states are expressed on the subscription rather than the invoice.
Add a time-based sweep. The retry window is knowable: it is whatever Smart Retry policy the account is on, and the options are 1 week, 2 weeks, 3 weeks, 1 month or 2 months. If a commission has sat in pending_recovery past that window plus a margin, resolve it yourself instead of waiting for an event that is not coming.
Record which rule resolved it. When an affiliate asks why a commission vanished, "the invoice was marked uncollectible on this date" and "our sweep timed it out after 21 days" are very different answers, and only one of them is defensible.

The one decline that is not a retry problem

A decline with authentication_required is not a timing failure. The card is fine and the issuer wants the customer back on-session to complete 3DS. No retry schedule fixes that, so a commission stuck behind one is waiting on a human, not a timer. Treat it differently in the sweep: it should trigger an email to the customer, not a longer wait.

Measuring what this costs you

Stripe has a page for this that is easy to miss: dashboard.stripe.com/revenue_recovery, which gives "key performance indicators (KPIs), trends, and reports to help you understand how failed subscription payments are affecting your business."

Two caveats before you trust the number. It covers the current and previous month only, so any 90 day question still needs an export. And the scope is narrower than it looks: "Data in the revenue recovery overview represents recurring subscription payments only and excludes the first invoice payment following a trial." If most of your failures are trial conversions, they are not in there.

When you do export, count invoices and not charges. Eight failed charge rows can be one uncollected invoice. Sum the charges and you will overstate what failed renewals cost you by several times, and if you are using that number to size how much commission you need to claw back, you will size it several times too big.

The shape of it

Pay on a settled fact. Hold on an ambiguous one. Reverse on a terminal one, and then go and check that your terminal one actually fires for the merchant configuration you are running.

Every Stripe quote above is from the Billing and API docs, checked on 2026-07-31: billing/revenue-recovery/smart-retries, billing/invoices/workflow, billing/revenue-recovery/recovery-analytics and api/events/types.

What on_behalf_of actually changes on a Stripe destination charge (and what it does not)

Mihir kanzariya — Wed, 29 Jul 2026 18:57:07 +0000

I gave someone bad advice about this in a comment three weeks ago. They were about to ship it. Here is the correction, and the full picture of what the parameter actually does.

The claim I made was that adding on_behalf_of to a destination charge would let each connected account own its own disputes. That is wrong. It is a comfortable kind of wrong, too, because almost everything else about on_behalf_of does point in that direction.

What on_behalf_of genuinely changes

Set on_behalf_of to a connected account on a destination charge and Stripe treats that account as the settlement merchant. Per Stripe's Connect charges documentation, it:

Settles in the connected account's country. Stripe "settles charges in the country of the specified account to minimise declines and avoid currency conversions."
Prices with that country's fee structure. It "uses the fee structure for the connected account's country."
Shows their statement descriptor, not yours.
Shows their address and phone on the customer's statement when the two accounts are in different countries.
Pays out on their schedule. Stripe "pays out a connected account, depending on the days specified in its delays_days setting."

That is a real change in who the customer thinks they paid, and a real change in the economics of the charge. If your connected accounts sit in other countries, both the settlement currency and your per-transaction cost move.

What it does not change

Dispute liability.

For destination charges, and for separate charges and transfers, with or without on_behalf_of, Stripe's disputes documentation is explicit: "Stripe debits dispute amounts and fees from your platform account." You recover by reversing the transfer to the connected account.

Only full direct charges, created with the Stripe-Account header, move dispute liability onto the connected account.

So the presentation moves and the money does not. The customer sees the connected account's name on their statement, the connected account's country determines settlement, and then a chargeback lands on your platform balance anyway. Those two facts sit next to each other in the docs and it is easy to read the first and assume the second.

The capability cost nobody mentions

on_behalf_of is not free on the onboarding side. Stripe's account capabilities documentation states that "to enable connected accounts to accept a payment method for direct charges or charges with on_behalf_of, you must request that payment method's capability for those accounts."

So a plain destination charge needs transfers. A destination charge with on_behalf_of needs the payment method capability too, which for cards means card_payments, and card_payments requires transfers as a prerequisite. With transfers alone, your platform processes the charge.

In practice that means more verification for every connected account you onboard. If you are weighing on_behalf_of for presentation reasons, that is the bill.

The cross-border trap worth knowing before you ship

This one costs real money and it is easy to miss.

When a dispute arrives on a destination charge, the instinct is to reverse the transfer immediately and get your money back from the connected account. On cross-border transfers, do not.

Stripe's guidance: "Retransferring a previous reversal is subject to cross-border transfer restrictions, meaning you might have no means to repay your connected account. Instead, wait to recover disputed cross-border payment transfers for destination charges with on_behalf_of until after a dispute is lost."

Reverse early, win the dispute, and you can end up unable to send the money back.

The short version

	destination charge	with `on_behalf_of`	direct charge
statement descriptor	platform	connected account	connected account
settlement country and fees	platform	connected account	connected account
dispute liability	platform	platform	connected account
capability needed	`transfers`	`card_payments`	`card_payments`

If what you want is for partners to look like the merchant, on_behalf_of does that. If what you want is for partners to carry the chargeback risk, it does not, and you need direct charges.

I conflated those two for three weeks. Worth checking which one you actually need before the first dispute arrives and tells you.

Multi-currency affiliate commissions on Stripe: which amount do you actually owe?

Mihir kanzariya — Wed, 29 Jul 2026 02:03:26 +0000

If your customers pay in their own currency and you pay affiliates in yours, every payment carries two different amounts. Pick the wrong one and every commission you calculate is quietly wrong.

Two amounts, two currencies

Stripe calls the currency the customer is charged in the presentment currency, and the currency that lands in your account the settlement currency. When they differ, Stripe converts, and the conversion is where commission math goes wrong.

The invoice tells you what the customer paid. The balance transaction tells you what you actually received.

// invoice.paid
const invoice = event.data.object;
invoice.currency;      // presentment: what the customer was charged in
invoice.amount_paid;   // presentment amount, smallest currency unit

// Resolve the charge for this invoice. The field name depends on your API
// version (older versions expose invoice.charge, newer ones invoice.payments),
// so read it from your own version rather than copying a field name.
const charge = await stripe.charges.retrieve(chargeId, {
  expand: ['balance_transaction'],
});

const bt = charge.balance_transaction;
bt.currency;       // settlement: your account currency
bt.amount;         // settled, before Stripe's fee
bt.net;            // settled, after Stripe's fee
bt.exchange_rate;  // the rate used for THIS payment

Most commission code reaches for invoice.amount_paid, because it is right there in the webhook payload. On a single-currency account that is fine. The moment a customer pays in EUR and your account settles in USD, amount_paid is a number in a currency you never received.

Decide what the commission is a percentage of

There are two defensible answers, and you have to pick one deliberately.

A percentage of what the customer paid. Stable from the affiliate's side: the same sale always earns the same commission in the customer's currency. You absorb the exchange rate movement.

A percentage of what you received. Stable from your side: you never pay out more than a fixed share of money you actually hold. The affiliate's commission moves with the rate, and you have to explain that.

Neither is wrong. Shipping without deciding is, because then the code picks for you, and it picks whichever field was easiest to reach.

The refund trap

This is the part that catches people out.

When a currency-converted payment is refunded or disputed, Stripe converts back at the current rate, not the rate of the original charge. From Stripe's documentation on conversions for disputes and refunds:

Exchange rates fluctuate with the market, so the rate used during the payment can differ from the rate used when a dispute or refund occurs.

Their own worked example: a 60 USD payment at 0.88 EUR per USD settles as 52.80 EUR. If the rate is 0.86 when the refund lands, only 51.60 EUR comes back out of your balance. The customer still gets a full refund in their currency. You carry the difference.

So if you claw back a commission by recomputing it at today's rate, the reversal will not match what you originally recorded. A few hundred refunds later, that is a reconciliation gap nobody can explain.

Store the numbers, not just the percentage

The fix is boring and it holds up. On every commission row, write down enough that you never have to re-derive anything.

create table commission (
  id                   bigserial primary key,
  affiliate_id         bigint not null,
  invoice_id           text   not null,

  -- what the customer paid
  presentment_amount   bigint not null,
  presentment_currency text   not null,

  -- what you actually received
  settled_amount       bigint not null,
  settled_currency     text   not null,
  exchange_rate        numeric,
  balance_transaction  text,

  -- what you owe, frozen at calculation time
  commission_amount    bigint not null,
  commission_currency  text   not null,
  basis                text   not null,   -- 'presentment' or 'settled'

  created_at           timestamptz not null default now()
);

basis is the column that saves you. A year from now, when someone asks why two commissions on identical-looking sales came out different, the row says which side of the conversion it was calculated from.

And on a refund, reverse the stored commission_amount. Do not recompute it. The number you owed is the number you un-owe, wherever the rate has moved since.

One sentence for your program terms

If you pay affiliates in their local currency, there is a second conversion between you and them, so the amount landing in their bank will not always match the number in your dashboard. Say that in the terms in one sentence.

It costs nothing to disclose, and it prevents the support email that opens with "your dashboard says 40 and I received 38."

Self-referral and coupon leaks: the affiliate fraud checks worth building on Stripe

Mihir kanzariya — Tue, 28 Jul 2026 07:21:11 +0000

Affiliate fraud in a small SaaS program is rarely sophisticated. It is usually one of two things: someone buying through their own link to pocket the commission on their own subscription, or an affiliate's coupon ending up on a deals aggregator where it converts people who were already going to buy.

Neither one looks like fraud in your dashboard. Both look like growth.

These are the checks worth wiring in before the program gets big enough for it to hurt.

Self-referral: match on the card, not the email

Email matching is the obvious check and the easiest to beat. Anyone who wants the commission will use a second address.

Stripe gives you something harder to fake. Every PaymentMethod carries card.fingerprint, which stays the same for the same physical card even across different customers.

// on invoice.paid, before you write the commission row
const invoice = event.data.object;
const pm = await stripe.paymentMethods.retrieve(
  invoice.default_payment_method,
  { expand: ['card'] }
);

const fp = pm.card?.fingerprint;
if (fp && fp === affiliate.cardFingerprint) {
  return holdCommission(invoice, 'self_referral:card_match');
}

This needs the affiliate's fingerprint on file, which you have if they are also a paying customer. If they are not, fall back on cheaper signals and treat them as a score rather than a verdict:

Normalized email match (strip dots and +tags on Gmail before comparing)
Same billing postal code and same last4
Signup IP matching the IP recorded on the referral click
Under 60 seconds between the click and checkout

Any one of those alone is noise. Two or three stacking up on an affiliate's first ever conversion is worth a human look.

Coupon leaks: compare redemptions to clicks

If you hand affiliates a coupon code as well as a link, the code will eventually escape onto a deals site. Then you are paying recurring commission on customers who found you through Google and searched for a discount on the way to checkout.

The signal is a redemption count with no relationship to the affiliate's traffic.

const clicks = await countClicks(affiliate.id, last30Days);
const redemptions = await countRedemptions(affiliate.couponId, last30Days);

// an affiliate sending real traffic converts a fraction of their clicks
if (redemptions > 10 && redemptions / Math.max(clicks, 1) > 1) {
  flag(affiliate, 'coupon_leak');
}

An affiliate with 300 redemptions and 20 clicks is not sending you anyone. Their code is just loose on the internet.

Cookie stuffing: heavy clicks, dead conversion

This one runs the other direction. Someone loads your referral URL in a hidden iframe or an image tag, so every visitor to their site gets tagged, and they collect on whoever was going to convert anyway.

It shows up as click volume far above your program norm with a conversion rate far below it, usually concentrated in a couple of referrer domains that are not real content pages. Log the Referer header and user agent on every click and you can spot it in a single query.

Hold the commission, do not delete it

The mistake I would avoid: auto-rejecting on a flag. False positives happen, and an affiliate who loses a legitimate commission to your fraud rule will tell people about it.

Mark the commission pending with a reason instead, keep a normal payout hold window (30 days covers most monthly plans), and review the flagged ones by hand. At small volume there will not be many.

I build Referralful, affiliate software for SaaS built on Stripe, so I spend a lot of time in this corner of the API. The checks above are worth thinking through whatever you run your program on, including a homegrown one.

What have you actually seen get abused in your program?