Referral codes & bulk sync
This article's section starts at 0:53 in the video.
This page explains what actually happens behind the scenes when DollarBack generates referral codes: where the codes live in Shopify, what the sync status banners mean, and why the editor locks while a generation run is in progress.
Where referral codes live
Every customer's referral code is a discount code in Shopify. That's what lets the referee redeem it at checkout and what makes attribution work. But the codes are not thousands of separate discounts: they're pooled onto one shared Shopify discount, with each customer's code attached to that single parent as an additional code.
If you use the Ultimate Discounts integration, the codes are attached to your connected integration discount instead: same pooling model, different parent (Referral + Ultimate Discounts integration).
Each code is also stored on its owner's customer profile (the db-referral.code metafield), which is how DollarBack maps a redeemed code back to the referrer. Older installations issued codes that were the customer's numeric ID; those legacy codes keep working.
Don't delete or edit the shared referral discount directly in Shopify admin; every customer's referral code hangs off it. Manage the program from DollarBack admin → Referral only.
When bulk generation runs
A bulk generation/sync run kicks off when codes need to be created or re-attached at scale:
You save a new config: codes are generated for every customer the config matches.
You add a config targeting a tag: codes are generated for the tagged customers.
The code pool needs a re-sync, for example after connecting an Ultimate Discounts integration discount, so existing codes attach to the new parent.
New customers who sign up later get their code individually; bulk runs are for the existing customer base.
Reading the status, and why the editor locks
While a run is in progress the Referral page shows a Bulk Operation in Progress banner: "Referral codes are being generated. Please wait until the operation completes before making changes." (with a count when multiple operations are running). The config editor is locked until it finishes. When it completes you'll see a "Bulk operation completed successfully" toast.
The lock is deliberate. A bulk run writes codes to the shared Shopify discount in batches over several minutes. If you could edit the config mid-run (change the prefix, retarget the tags, swap the parent discount), part of the customer base would end up with codes generated under the old rules and part under the new, and attribution would fray. Locking guarantees every code in a run is consistent. On large stores, expect a run to take minutes rather than seconds; there's nothing to do but let it finish.
Related guardrail: the Code Prefix field is permanently locked after the first save ("Code prefix cannot be changed once the config is saved"), because changing it would orphan every code already generated with the old prefix.
If you migrated from an older DollarBack referral setup, you may see a Legacy Config Detected banner: your settings were auto-migrated to the new format. Review and save to complete the migration. Saving may trigger a bulk run.
Verify it works
After the completion toast: pick a customer in Shopify admin and confirm their referral code exists on their profile, then check the storefront (widget or account page) shows the same code. Applying that code on a test checkout should pull up the referee discount.
Common issues
Editor is greyed out → a bulk operation is running; wait for the completion toast.
A customer has no code → the run may still be processing, or they match no config; see Run multiple referral configs.
Codes stopped working store-wide → check that the shared referral discount still exists in Shopify admin; see A referral wasn't tracked.
Related articles
Last updated