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.
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.