Canva Upgrade & Migration

Overview

Guide for handling Canva Connect API changes. Canva uses a single REST API version (/rest/v1/) but evolves endpoints over time. Monitor the changelog for breaking changes.

Prerequisites

• A pinned current artifact, tested rollback version, and current official changelog evidence.
• Synthetic or approved non-production assets and a protected OAuth test tenant.

Instructions

1. Map the announced change to scopes, endpoints, stored identifiers, and response contracts.
2. Test behind a feature flag with only approved synthetic assets and minimum scopes.
3. Compare redacted authorization, schema, rate/cost, and publication outcomes before promotion.
4. Roll back on a policy, contract, or reconciliation difference.

Known Migrations

Brand Template ID Migration (September 2025)

Canva migrated brand templates to a new ID format. Old IDs accepted for 6 months.

// Check if your stored template IDs need updating
async function migrateBrandTemplateIds(
  db: Database, token: string
): Promise<{ migrated: number; failed: string[] }> {
  const stored = await db.getBrandTemplateIds();
  let migrated = 0;
  const failed: string[] = [];

  // Fetch current templates from Canva
  const { items } = await canvaAPI('/brand-templates', token);
  const currentIds = new Set(items.map((t: any) => t.id));

  for (const oldId of stored) {
    if (!currentIds.has(oldId)) {
      // Old ID — try to find matching template by title
      const match = items.find((t: any) => t.title === await db.getTemplateName(oldId));
      if (match) {
        await db.updateTemplateId(oldId, match.id);
        migrated++;
      } else {
        failed.push(oldId);
      }
    }
  }

  return { migrated, failed };
}

Comment API Migration

The Comment API endpoints were refactored — Create Comment and Create Reply are deprecated in favor of Create Thread and Create Reply (v2).

// OLD (deprecated)
// POST /v1/designs/{id}/comments — deprecated

// NEW
// POST /v1/designs/{id}/comment_threads — Create Thread
// POST /v1/designs/{id}/comment_threads/{threadId}/replies — Create Reply

Pre-Upgrade Assessment

async function assessCanvaIntegration(token: string): Promise<void> {
  const checks = [
    { name: 'Users API', path: '/users/me' },
    { name: 'Designs List', path: '/designs?limit=1' },
    { name: 'Brand Templates', path: '/brand-templates?limit=1' },
    { name: 'Exports', path: '/exports' },  // Will 405 (POST only) but confirms route exists
  ];

  for (const check of checks) {
    try {
      const res = await fetch(`https://api.canva.com/rest/v1${check.path}`, {
        headers: { 'Authorization': `Bearer ${token}` },
      });
      console.log(`[${res.ok || res.status === 405 ? 'OK' : 'WARN'}] ${check.name}: HTTP ${res.status}`);
    } catch (e: any) {
      console.log(`[FAIL] ${check.name}: ${e.message}`);
    }
  }
}

Breaking Change Detection

// Monitor API responses for deprecation signals
function checkForDeprecationWarnings(response: Response, endpoint: string): void {
  const deprecation = response.headers.get('Deprecation');
  const sunset = response.headers.get('Sunset');
  const link = response.headers.get('Link');

  if (deprecation) {
    console.warn(`[DEPRECATION] ${endpoint}: deprecated=${deprecation}, sunset=${sunset}`);
    console.warn(`  Migration guide: ${link}`);
    // Alert ops team
  }
}

Upgrade Branch Workflow

# 1. Create upgrade branch
git checkout -b upgrade/canva-api-changes

# 2. Check Canva changelog for breaking changes
# https://www.canva.dev/docs/connect/changelog/

# 3. Download latest OpenAPI spec for diff
curl -o openapi-new.yml https://www.canva.dev/sources/connect/api/latest/api.yml
diff openapi-old.yml openapi-new.yml | head -100

# 4. Run integration tests against staging
CANVA_ACCESS_TOKEN=$STAGING_TOKEN npm test

# 5. Deploy to staging first
# 6. Monitor for 24 hours before production

Rollback Procedure

// Feature-flag controlled rollback
const USE_NEW_COMMENT_API = process.env.CANVA_NEW_COMMENT_API === 'true';

async function createComment(designId: string, message: string, token: string) {
  if (USE_NEW_COMMENT_API) {
    return canvaAPI(`/designs/${designId}/comment_threads`, token, {
      method: 'POST',
      body: JSON.stringify({ message }),
    });
  }
  // Fallback to deprecated endpoint during transition
  return canvaAPI(`/designs/${designId}/comments`, token, {
    method: 'POST',
    body: JSON.stringify({ message }),
  });
}

Output

The upgrade produces a compatibility matrix, artifact/config versions, redacted test receipt, feature-flag decision, and rollback reference. It excludes tokens, design contents, signed URLs, and tenant-identifying data.

Examples

Pin the prior client version, test the new version against a synthetic design export, compare the validated schema and policy decision, and promote only after owner approval. If a new scope or response field is unexpected, leave the flag disabled and restore the prior release.

Error Handling

Issue	Cause	Solution
404 on endpoint	Endpoint removed or renamed	Check changelog for replacement
Old template IDs fail	ID format migration	Re-fetch template list
Deprecated header	Endpoint sunsetting	Migrate to replacement
Response schema changed	New/removed fields	Update Zod schemas, add optional chaining

Resources

• Canva Changelog
• OpenAPI Spec
• Canva API Reference

Next Steps

For CI integration during upgrades, see canva-ci-integration.