Migrating link infrastructure feels risky — thousands of URLs live in emails, printed materials, and bookmarks. Done right, it's a four-hour mechanical job with zero broken links. This playbook is the sequence: export, map, re-shorten, forward, verify, cut over.
Step 1 — Export everything
Bitly lets you export your links (CSV per group). Get every field: short URL, long URL, title, created date, click counts. If you have multiple groups, export each and merge — the mapping step needs the full inventory.
Step 2 — Build the mapping
The mapping is the heart of the migration: every Bitly short URL → its destination → the new yas.sh alias. The rules:
- Keep aliases that still matter — campaign and branded links keep their slugs.
- Let random codes go — old random codes have no value; new random codes are generated automatically.
- Preserve destinations exactly — including UTM parameters. Copy the destination URL verbatim; don't "clean it up" mid-migration.
A spreadsheet (or a script) produces the canonical map: bitlyUrl, destination, newAlias, newUrl.
Step 3 — Re-shorten in bulk
The bulk creation pattern applies: pace at 1/sec, use Idempotency-Key per row, handle 409s explicitly:
# mapping.csv: destination,alias,title
while IFS=, read -r dest alias title; do
curl -s -X POST https://yas.sh/api/v1/links \
-H "Authorization: Bearer yas_live_..." -H "Content-Type: application/json" \
-H "Idempotency-Key: mig-$RANDOM" \
-d "{\"originalUrl\":\"$dest\",\"customAlias\":\"$alias\",\"title\":\"$title\"}" \
| jq -r '.url // .detail' >> migration-results.txt
sleep 1
done < mapping.csv
Capture every 409 (alias collisions) and resolve them by policy — deterministic suffix or skip.
Step 4 — Forward the old links (the non-negotiable step)
Old links live in the wild: emails sent, print published, QR codes printed. They must keep working. Forward with 301s from the old domain to the new links — either via Bitly's redirect settings per link, or (better) a rewrite rule on your own domain if your custom domain is moving with you:
old: bit.ly/launch → 301 → go.yourbrand.com/launch
The 301 consolidates any remaining link equity and keeps every old URL functional. The 301 vs 302 guide explains why the old side should be 301 while the new platform keeps using 302 internally.
Step 5 — Verify before cutover
- Sample 5% of links: every sampled old URL must 301 to the matching new link, and the new link must 302 to the correct destination.
- Compare counts: export counts from yas.sh vs the input rows — every row accounted for.
- Check QR assets: if printed QR codes pointed at old links, scan a sample to confirm the forwarding chain works end-to-end.
Step 6 — Cut over, then sunset
Announce the new domain internally, update templates and signatures, and run a two-week overlap: both domains resolve, old via 301. After the window, retire the old domain deliberately — and keep the forwarding active for a further month for stragglers if cost allows.
What not to do
- Don't migrate on a deadline day. Campaign launches and migration cutover don't mix.
- Don't clean destinations while migrating. Fix UTMs after the move, in a separate pass.
- Don't delete the old account immediately. Exports and analytics remain useful for the overlap window.
- Don't skip the sample verification. The one mapping row you didn't check is the one that's wrong.
What the Bitly export gives you
Bitly's export is the raw material for the whole migration. It typically includes each link's long URL, the short link or hash, the custom alias if any, the title, tags, and the click history at the time of export. Pull the full record, then clean it: normalize URLs, de-duplicate, and decide how to handle links that are no longer relevant or that point to dead destinations. Every decision you make here shapes the rest of the project, so it is worth spending time on the export before touching the import.
Keeping every published link alive
The links already in the wild — in bios, newsletters, printed materials, QR codes — must keep working or you lose the clicks and trust built into them. Two mechanisms protect them: preserve the existing short codes so the new URLs match what was already published, and set up 301 forwarding from your old Bitly domain to the new links so anything still pointing at the old address resolves to the correct destination. A 301 also carries the accumulated SEO value of the old URLs, which matters if any of these links have been indexed and ranked.
The import, done safely
Import the cleaned list through the API using the batch pattern: pace the requests to stay inside rate limits, attach an Idempotency-Key per row so a retry does not duplicate, and handle collisions deterministically rather than letting them fail the run. The bulk creation workflow describes this loop in detail. After the import, verify the count matches the source, spot-check a sample of redirects resolve to the right destination, and confirm the analytics carried over before you consider the migration done.
The four-hour playbook in practice
The name "four-hour playbook" reflects how fast a clean migration can be when the prep is right. In practice the clock is dominated by the export-and-clean step, not the import. A realistic sequence: export and clean the data, prepare the slug mapping and collision policy, run the paced import with idempotency, enable 301 forwarding from the old domain, verify, then stage the cutover so any low-risk links confirm the setup before everything else switches. Handled this way, a migration that used to feel risky becomes a routine, reversible operation.
Common Bitly-specific snags
Two Bitly details trip people up: Bitly exports can include links with a different default domain and custom back-halves that need explicit mapping, and Bitly's click history is often reported on a delay, so the numbers at export time may not be final. Expecting these, cleaning the export accordingly, and validating the carried analytics prevents a surprise when the numbers in the new dashboard do not match the old one.
Conclusion
A Bitly migration is export → map → re-shorten → forward → verify → cutover, and nothing in the sequence is exotic — the bulk creation and custom domains guides cover the mechanics. The compare page shows why teams make the move; the playbook above is how they do it without a single broken link.