Linktree Upgrade & Migration

Overview

Linktree provides a link-in-bio platform with APIs for managing profiles, links, and click analytics. The API exposes endpoints for CRUD operations on link trees, individual links, and analytics data. Tracking API changes is critical because Linktree's link schema evolves with new link types (commerce, scheduling, music), analytics response formats change with new metric dimensions, and profile customization fields expand — breaking integrations that sync link performance data to marketing dashboards or automate link management across multiple profiles.

Version Detection

const LINKTREE_BASE = "https://api.linktr.ee/v1";

async function detectLinktreeApiVersion(apiKey: string): Promise<void> {
  const res = await fetch(`${LINKTREE_BASE}/profile`, {
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  });
  const version = res.headers.get("x-linktree-api-version") ?? "v1";
  console.log(`Linktree API version: ${version}`);

  // Check for deprecated link type fields
  const linksRes = await fetch(`${LINKTREE_BASE}/links`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await linksRes.json();
  const knownTypes = ["classic", "header", "music", "video", "commerce", "scheduling"];
  const activeTypes = [...new Set(data.links?.map((l: any) => l.type) ?? [])];
  const unknown = activeTypes.filter((t: string) => !knownTypes.includes(t));
  if (unknown.length) console.log(`New link types detected: ${unknown.join(", ")}`);
}

Migration Checklist

• Review Linktree developer changelog for API breaking changes
• Audit codebase for hardcoded link type enums (new types may be added)
• Verify analytics endpoint response structure (metrics, dimensions, date ranges)
• Check profile customization fields for new appearance options
• Update link creation payload if required fields were added
• Test link ordering API — sort mechanism may have changed
• Validate thumbnail/image upload endpoints for size or format changes
• Check OAuth token scopes if new permissions required for analytics
• Update webhook handlers for link click and profile view events
• Run analytics data export and compare old vs. new response shapes

Schema Migration

// Linktree links evolved: simple URL → typed link with metadata
interface OldLink {
  id: string;
  title: string;
  url: string;
  position: number;
  active: boolean;
}

interface NewLink {
  id: string;
  title: string;
  url: string;
  type: "classic" | "header" | "music" | "video" | "commerce" | "scheduling";
  position: number;
  active: boolean;
  metadata: {
    thumbnail_url?: string;
    schedule?: { start: string; end: string };
    price?: { amount: number; currency: string };
  };
  analytics: { total_clicks: number; unique_clicks: number };
}

function migrateLink(old: OldLink): NewLink {
  return {
    ...old,
    type: "classic",
    metadata: {},
    analytics: { total_clicks: 0, unique_clicks: 0 },
  };
}

Rollback Strategy

class LinktreeClient {
  private version: "v1" | "v2";

  constructor(private apiKey: string, version: "v1" | "v2" = "v2") {
    this.version = version;
  }

  async getLinks(): Promise<any> {
    try {
      const res = await fetch(`https://api.linktr.ee/${this.version}/links`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`Linktree ${res.status}`);
      return await res.json();
    } catch (err) {
      if (this.version === "v2") {
        console.warn("Falling back to Linktree API v1");
        this.version = "v1";
        return this.getLinks();
      }
      throw err;
    }
  }
}

Error Handling

Resources

• Linktree Developer Portal
• Linktree API Documentation

Next Steps

For CI pipeline integration, see linktree-ci-integration.