Track Dub referral links in Japanese and English without breaking referral IDs

21 min read
SaaSDubUTMAffiliate Marketing

When Japanese and English articles point to the same referral link, the link alone does not distinguish their language or placement. I tested a URL builder that labels both with UTMs while preserving the issued referral path and existing referral parameters.

The experiment was run on September 30, 2026. It checks URL construction locally using example.com fixtures. It does not issue links through Dub’s API, test redirects, verify purchases, or establish commission attribution. The tests generate no referral clicks or signups.

For the next step after URL construction, see Dub conversion tracking: lead/sale APIs and Stripe customer mapping, including an offline request JSON example.

Separate traffic from confirmed commissions

A click and a confirmed commission represent different events. A reader may leave without signing up, or continue using a free plan. Refund and cancellation rules also vary by program, so a sale event is not necessarily a finalized payout.

For this publication, the review sequence is article views, referral clicks, leads, sales, and confirmed commissions. Define click rate as referral clicks divided by relevant article views, and lead rate as leads divided by relevant link clicks, using matching periods and scopes. Adding UTMs does not collect every input needed for those calculations.

Dub documents filtering analytics by UTM values and combining that view with Conversions to inspect signups and sales. A publisher’s URL builder cannot instrument the vendor’s conversion events. Dub UTM analytics announcement

Keep the issued referral URL as the source

Start with enrollment and the referral URL issued by the program. Recreating a short link from a product’s ordinary website URL can lose the original referral identifier. Add editorial labels to the issued URL instead.

The fixture is https://example.com/ref/demo?ref=keep#pricing. I set explicit expectations that /ref/demo, ref=keep, and #pricing survive construction. That proves what our code preserves, rather than what a vendor’s attribution system will do.

In the current site implementation, Circleback has a verified issued referral link; Dub uses an ordinary official-site link because this account is not enrolled in its program. Dub’s public enrollment page lists 30% per sale for one year. This does not mean this publication currently earns that commission. Dub’s official program page

Use one naming convention for both languages

I use the article slug as the campaign and put language and placement in utm_content. A translated title would be a poor campaign identifier: an editorial title change would create a different campaign label.

Parameter and purpose Fixture value
Publication (utm_source) sakimyto.com
Referral channel (utm_medium) affiliate
Article (utm_campaign) circleback-webhook-action-items
Language and placement (utm_content) ja-footer or en-footer

Use body for a contextual link and footer for the service section after an article. Restricting values avoids mixing JA, jp, and Japanese for the same language. Reader emails and customer names have no role in these labels. URLs can appear in histories and access logs, so article-level identifiers are sufficient.

Build parameters with the URL API

Appending ?utm_source=... to a string fails when the URL already has a query. I edit parameters with URL and URLSearchParams instead.

import { buildReferralUrl } from './referral-utm.mjs'

const url = buildReferralUrl(
  'https://example.com/ref/demo?ref=keep#pricing',
  {
    locale: 'ja',
    slug: 'circleback-webhook-action-items',
    placement: 'footer',
  },
)
console.log(url)

The result is:

https://example.com/ref/demo?ref=keep&utm_source=sakimyto.com&utm_medium=affiliate&utm_campaign=circleback-webhook-action-items&utm_content=ja-footer#pricing

Existing UTM values are replaced with this convention. searchParams.set avoids duplicate utm_content entries while retaining unrelated parameters and the fragment. The function accepts HTTPS URLs without embedded credentials, ja/en locales, body/footer placements, and lowercase alphanumeric article slugs separated by hyphens.

What the local tests establish

Generating Japanese and English variants from one input changes utm_content from ja-footer to en-footer. The path, referral value, fragment, and campaign stay the same. Tests also verify that an existing UTM value is replaced rather than duplicated.

Relative paths, HTTP URLs, javascript: URLs, and URLs with embedded credentials are rejected. Unsupported languages, unknown placements, and a slug such as ../private also fail. These checks keep editorial inputs consistent; they cannot turn an arbitrary URL into a valid program referral.

Equal values do not mean identical URL strings

On October 7, 2026, I also tested a referral value containing a space and a tilde. The synthetic input includes two tag values and two old utm_content values:

https://example.com/ref/demo?ref=partner%20one~two&tag=alpha&tag=beta&utm_content=old&utm_content=older#pricing

Adding UTMs changed the raw ref value from partner%20one~two to partner+one%7Etwo. Both decode to partner one~two. Node’s documentation explains that URL and URLSearchParams use different encoding rules, including how they encode the tilde. Node.js URLSearchParams encoding caveat

These are the demo’s checks with the URLs omitted. Both tag values, the path, and the fragment survive; the two old utm_content values become one ja-footer value.

{
  "decodedRefBefore": "partner one~two",
  "decodedRefAfter": "partner one~two",
  "rawRefBefore": "ref=partner%20one~two",
  "rawRefAfter": "ref=partner+one%7Etwo",
  "repeatedTags": ["alpha", "beta"],
  "utmContentValues": ["ja-footer"],
  "pathPreserved": true,
  "fragmentPreserved": true
}

“Preserve” here refers to the tested path, decoded values, and fragment. It does not promise an identical original URL string. Treat signed URLs that require an exact URL string as outside this example’s scope. Do not apply it when the signing scheme or permission to append UTMs is unknown. The function does not detect signed URLs, and this experiment does not test a vendor’s signature verifier or real attribution.

Save the following two files in the same directory. Run bun referral-demo.mjs, or node referral-demo.mjs with Node.js 22+. It prints both language variants and the checks locally, without visiting a referral destination.

The earlier demo.mjs remains a shared demo that also exercises Circleback task conversion. It is not needed for this UTM-only check.

Do not append UTMs after #pricing

On October 16, 2026, I tested appending UTMs to a URL with a fragment. Adding &utm_source=sakimyto.com after ?ref=keep#pricing puts the UTM text inside the fragment. searchParams.get('utm_source') returned null. Appending ?utm_source=... after #pricing on a URL without an existing query had the same problem. Node documents the query in search and the fragment in hash as separate URL components. Node.js URL structure

The existing runnable demo now compares string concatenation with buildReferralUrl using the same input. Save the two files listed above and run the same command to see these additional fields:

{
  "appendedUtmSource": null,
  "appendedFragment": "#pricing&utm_source=sakimyto.com",
  "builtUtmSource": "sakimyto.com",
  "builtFragment": "#pricing"
}

Both Bun and Node produced this result. buildReferralUrl puts the UTM in the query and preserves the original #pricing. This is local parsing of a synthetic URL, not a test of Dub click tracking or attribution after redirects. The signed-URL restrictions in the preceding section still apply.

Plus signs and spaces in referral IDs

On October 18, 2026, I compared ways to put the synthetic ID partner+demo into a query. Parsing ?ref=partner+demo made searchParams.get('ref') return partner demo. The WHATWG URL Standard replaces a raw + with a space before percent-decoding a form-encoded query. WHATWG query parsing steps

The existing runnable demo also prints the following literalPlus object, using the same two files and commands above. Bun and Node produced matching results.

{
  "input": "partner+demo",
  "interpolatedRef": "partner demo",
  "valueSetRef": "partner+demo",
  "encodedQueryRef": "partner+demo",
  "builderCannotRepairRef": "partner demo",
  "doubleEncodedRef": "partner%2Bdemo"
}

When setting an unencoded value yourself, pass it as url.searchParams.set('ref', 'partner+demo'). In this example, the plus was serialized as %2B and read back as partner+demo. Adding UTMs with buildReferralUrl to a URL that already contained %2B also preserved that value. Passing the value through encodeURIComponent before set left %2B in the decoded result. Pass unencoded values to set.

The function cannot infer whether a raw + in an issued URL was intended as a space or a plus. Adding UTMs to ?ref=partner+demo still leaves the parsed value as partner demo. Check the vendor-issued source and its specification rather than replacing characters throughout the URL or decoding and rebuilding it. This is local parsing of synthetic URLs; real Dub referral IDs, clicks, and commission attribution remain untested.

Dub documents passing short-link parameters to the destination, with short-link values taking precedence when a destination parameter has the same name. Avoid overriding any parameter the program uses for referral identity. Dub parameter forwarding announcement

Check program rules before adding UTMs to an issued link. If the program provides an approved testing method, inspect the final referral identifier, UTM values, and corresponding click record. Do not manufacture self-referral purchases to test payouts; program-specific restrictions still apply.

The site currently publishes the original verified Circleback URL. This local URL experiment and vendor-side attribution verification remain separate. A structurally correct URL is not evidence that a commission was attributed correctly.

Using the data to choose further articles

Measurement also needs context if AI is going to help with the next decision. Instead of recording that an article “did well,” retain its slug, language, reporting period, views, clicks, and confirmed commissions separately. That gives a later editorial review a basis for distinguishing reach from adoption decisions. This URL construction experiment does not collect those performance figures.

After publication, first check whether each language attracts readers searching for the problem addressed. If views do not lead to clicks, review whether the article gives enough information to decide on the service. If clicks do not lead to signups or sales, investigate product fit, pricing, and setup effort. A small number of clicks cannot establish a reliable language-level conversion difference.

The Circleback webhook experiment tests concrete integration decisions, including missing owners and replay handling. That is the editorial standard for subsequent SaaS articles: give readers evidence they can use to judge whether the workflow fits their own operation.

Go deeper on this topic

SaaS integrations

Give AI the context to continue the work: source conversations, open tasks, and unresolved details, from adoption decisions to integration code.

Article 23 of 23 in this series.

View topic page

Use the topic hub as a map, then continue to the next article in the series. New here? Start at the home hub →

FAQ

Why does a plus sign in a referral ID become a space?

URLSearchParams parses a raw + in query text as a space. In the synthetic test, passing the value to set or using %2B in the URL preserved a literal plus. Adding UTMs to a URL that already contains a raw + cannot recover the intended value. Check the issued URL against its source; live Dub attribution remains a separate question.

Can I read a UTM from the query if I append it after #pricing?

In the local synthetic test, an appended UTM became part of the fragment and was absent from searchParams. Editing the query with the URL API kept the UTM and original #pricing separate. Live Dub tracking and attribution remain untested.

Can I use the builder on signed URLs if parameter values stay the same?

It does not preserve the original URL string exactly. Spaces and tildes can be re-encoded. The function does not detect signed URLs; do not use it when the signing scheme or permission to append UTMs is unknown. Vendor signature verification and real attribution remain untested.

Do UTM parameters establish commission attribution?

No. UTMs classify traffic. Enrollment, an issued referral link, and program-specific attribution rules are still required. Confirmed commissions depend on the program’s terms and finalized results.

Does the sample connect to the Dub API?

No. It tests URL construction locally. Link issuance, destination parameter persistence, and lead or sale attribution require separate verification.