> ## Documentation Index
> Fetch the complete documentation index at: https://www.referly.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate from Dub
> Import your Dub Partners affiliates, referred customers, and sales into Referly with a Dub API key. Step-by-step guide to creating the key in Dub, connecting, and every import setting.
Moving from Dub doesn't mean rebuilding your program by hand. Referly connects straight to your Dub account and pulls your **affiliates** (your Dub partners), their **referred customers**, and your past **sales and commissions** across for you — no CSV exports, no file wrangling. You give Referly one key from Dub, choose what to bring over, and it does the rest in the background.
This guide walks through the whole move: how to create the right key inside Dub, how to connect it, every setting you'll see while choosing what to import, and how to follow each import as it runs.
New to migrating in general? Start with the [Migration overview](/docs/help-center/getting-started/migrate/overview) for how imports work, then come back here for the Dub-specific steps.
## Before you start
You'll need:
* **Admin access to your Dub workspace**, so you can create an API key.
* **A Dub Partners program with data in it.** Referly imports your Dub *partners*, the *customers* they referred, and the *commissions* they earned — these come from Dub Partners, Dub's affiliate side. If you only ever used Dub for short links and never ran a partner program, there won't be affiliates or commissions to bring across.
* **Your Referly program open** in the dashboard, ready to import into.
* A few minutes. Larger programs take longer to pull across, but the import runs in the background — you don't have to wait on the screen.
A Dub API key can grant full access to your Dub workspace. Treat it like a password: copy it straight into Referly, don't paste it anywhere public, and don't share it. Referly stores it securely so you only enter it once.
## Create an API key in Dub
Referly connects to Dub using an **API key** — a single key you generate inside your Dub workspace. Here's how to create one on Dub's side:
Sign in to your Dub dashboard at `app.dub.co` and make sure you're in the **workspace that holds your partner program** — API keys belong to a single workspace, so the key only sees the data in the one you're viewing.
Go to **Settings**, then **API Keys**. You can also reach this page directly at `app.dub.co/settings/tokens`.
Select **Create API Key** and give it a name you'll recognize later, such as `Referly import`.
Dub lets you choose what the key can access. Choose **All permissions**, or **Read only** — both let Referly read your partners, customers, and commissions. Avoid the **Restricted** option: it's limited to links, analytics, domains, and tags, so it can't see the partner and commission data Referly needs.
If Dub asks whether to tie the key to **you** or to a **machine user**, either works. A machine user isn't tied to a specific person, which is handy if team members change later.
Create the key and copy it right away. It starts with `dub_`, and Dub only shows it once — if you lose it, you'll need to create a new one. This single value is all Referly needs.
If you ever think your API key has been exposed, delete it in Dub's API Keys page and create a fresh one — then reconnect in Referly with the new key.
With that copied, head back to Referly.
## Open the import tool and choose Dub
In your Referly dashboard, select the **plus (+)** button in the top bar, then choose **Import Data**. You can also select **Import** from the top of your **Affiliates**, **Customers**, or **Sales** pages.
On the **Choose your source** screen, select **Dub** from the list of platforms.
## Connect your Dub account
The next screen shows Dub connecting to Referly, with a single **API key** field.
Paste the key you copied from Dub into the **API key** field. It's hidden as you type, the same way a password field is.
Select **Save connection**. Referly checks the key with Dub right away. If it works, you'll see the connection saved with a green **Saved connection** badge. If it doesn't, double-check that you copied the whole key and that it has permission to read your data (not a Restricted key), then try again.
Referly remembers this connection, so the next time you import from Dub — say, to bring sales across after your affiliates — you won't have to enter the key again. To swap in a different key later, select **Replace connection**.
## Choose what to import
Once the connection is saved, you choose which parts of your Dub program to bring over. There are three, and they line up with Dub like this:
| Select this in Referly | What it brings over from Dub |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| **Affiliates** | Your Dub partners, with their names, emails, and referral links. |
| **Referrals** | The customers your partners referred, each linked back to the partner who referred them. |
| **Sales** | Your past sale commissions and the transactions behind them, credited to the right partner. |
You can tick one, two, or all three — but the **order you import them matters**. Referred customers attach to affiliates, and sales attach to customers, so those have to exist in Referly first. Always bring your **affiliates over first**, then referrals, then sales. See [Import in the right order](#import-in-the-right-order) below.
### Pick the fields to bring across
When you tick an object, it expands to show every field Referly can pull from Dub for it. Each field has a checkbox, so you decide exactly what comes across. A few fields are marked **Required** — these are the details Referly needs to create the record, so they're always on and can't be switched off.
Here's what you can bring for each object.
* **First name** *(required)* — the partner's first name.
* **Last name** *(required)* — the partner's last name.
* **Email** *(required)* — the partner's email address. This is also how Referly links their referred customers and sales back to them.
* **Join date** — when they joined your Dub program, so their history stays accurate.
* **Payout email** — their PayPal payout email, when Dub has one on file.
* **Affiliate link** — their Dub referral link, so their existing links carry over.
* **Provider affiliate ID** — the partner's ID in Dub, kept for your reference.
* **Provider status** — the partner's status in Dub (for example, approved), kept for your reference.
When a partner has no name in Dub, Referly uses their company name, or the first part of their email, so every partner still comes across.
* **First name** *(required)* — the customer's first name.
* **Last name** *(required)* — the customer's last name.
* **Email** *(required)* — the customer's email address.
* **Affiliate email** *(required)* — the email of the partner who referred them. This is how each customer gets attached to the right partner, which is why affiliates must be imported first.
* **Join date** — when the customer was first created in Dub.
* **External user ID** — the customer's own ID from your app, the one you passed to Dub, kept for your reference.
* **Provider customer ID** — the customer's ID in Dub, kept for your reference.
* **Provider status** — where the customer is in their journey (for example, active, converted, or canceled).
* **Customer email** *(required)* — the email of the customer who bought.
* **Customer name** — the customer's name.
* **Affiliate email** — the email of the partner credited for the sale.
* **Transaction amount** *(required)* — the value of the sale.
* **Transaction date** — when the sale happened.
* **Commission** *(required)* — the commission the partner earned on that sale.
* **Paid status** — the commission's status in Dub (for example, pending or paid), so your payout history stays right.
* **Provider transaction ID** — the commission or invoice ID in Dub, kept for your reference.
* **Provider status** — the commission's status in Dub.
Referly only brings across **sale** commissions from Dub — the ones tied to a purchase — so click and other reward types stay behind. The default selections cover what most programs want, so if you're not sure, leaving them as they are is a safe choice. When you're happy with your picks, select **Continue**.
## Check the field matches
Before anything is imported, Referly shows you a preview of your Dub data lined up against the matching Referly fields. This is your chance to confirm everything landed in the right place — that names, emails, and amounts are matched to the fields you'd expect.
Look the preview over, and when it looks right, confirm to start the import.
## Start the import and follow its progress
Imports run in the background, so you can close the panel and keep working. Every import appears in the **Recent Imports** list inside the import tool, each with its own progress.
An import moves through these states:
| Status | What it means |
| -------------- | ------------------------------------------ |
| **Pending** | Queued and about to start. |
| **Processing** | Bringing your records in right now. |
| **Paused** | You've paused it; resume it any time. |
| **Completed** | Finished — all records handled. |
| **Failed** | The import stopped before finishing. |
| **Cancelled** | The import was stopped and won't continue. |
Each card shows a progress bar and a running count of how many records came in and how many were **skipped**. A record is skipped when it's missing a detail Referly needs — for example, a Dub partner with no email, a customer with no partner attached, or a commission missing its amount. That's normal; the skipped count just tells you those few couldn't be brought across.
You can **pause** a running import and **resume** it later, open **Details** for the full breakdown, or **delete** one you no longer need.
## Import in the right order
Because referred customers attach to affiliates and sales attach to customers, run your Dub imports in this order and let each finish before starting the next:
Bring your partners over so there's an affiliate for every customer and sale to attach to.
Import your referred customers. Each one links to its partner by email — which only works once those affiliates are already in.
Import your commissions and sales, credited to the affiliates and matched to their customers.
Referly reminds you of this order as you go, and it won't let you start a customer or sales import while the affiliate import it depends on is still running. Since your Dub connection is saved, each round just means reopening the import tool, picking Dub, and choosing the next object.
Check each import's results — the imported and skipped counts — before moving on to the next type. Getting affiliates in cleanly first means your customers and sales attach to the right partners automatically.
## Related
How imports work and what you can bring across.
Prefer a spreadsheet? Import affiliates, customers, or sales from a file.
Set the terms your migrated affiliates earn on.
Bring new partners into your program by email.