Zendesk to Plain Migration: The Complete Technical Guide

Zendesk to Plain Migration: The Complete Technical Guide

Migrating from Zendesk to Plain means moving from a broad, enterprise-grade helpdesk to an API-first, GraphQL-native support platform built for B2B engineering teams. The fastest path is Plain's built-in Zendesk importer, which handles end users, tickets, messages, and tags automatically. But if your scope includes custom field mapping, organization-level data, attachment preservation, knowledge base content, or granular control over the migration, you'll need to supplement with API scripting or a managed service.

This guide covers every viable approach, the data model translation, API constraints on both sides, and the edge cases that break most migrations.

Disclosure: This guide is published by ClonePartner, a company that offers managed migration services. We have a commercial interest in one of the approaches described below. We've aimed to provide technically accurate guidance regardless of which path you choose.

Why Teams Move from Zendesk to Plain

The migration pattern we see most is technical B2B companies — developer tools, infrastructure, API platforms — that have outgrown Zendesk's UI-first model and want deeper programmatic control over their support stack.

Common drivers:

• API-first architecture. Plain exposes a fully public GraphQL API where every object is readable and writable. Zendesk's REST API has grown organically but carries legacy constraints and tighter rate limits on lower-tier plans (200 req/min on Team vs. 2,500 on Enterprise Plus).
• Engineering-team collaboration. Plain integrates natively with Linear, GitHub, and Jira for escalation workflows. Zendesk can do this through Marketplace apps, but the plumbing is heavier.
• Bring Your Own AI agent. Plain's architecture lets you connect Claude, GPT, Gemini, or custom models directly via Machine Users — no per-resolution fees.
• Cost structure. Plain includes AI on every plan. Zendesk's per-agent cost scales faster, especially once you add the High Volume API add-on ($35/agent/month on Suite plans) or Advanced AI features.

Plain is purpose-built for B2B technical support. If you're running high-volume B2C, e-commerce, or multi-brand support with complex routing, Zendesk's breadth is likely still a better fit. Know what you're trading before you start.

Core Data Model Differences

Before writing any migration code, understand the structural mismatch. These two platforms model support data differently.

The biggest structural gap: Zendesk Organizations don't have a direct 1:1 import path into Plain. Plain auto-assigns Companies based on email domain, and Tenants serve as the primary organizational grouping. A customer can belong to one Company but can be added to multiple Tenants. Use Company for the business identity. Use Tenant when you need to model your product's workspace, org, or billing boundary. (plain.com)

If your Zendesk setup relies heavily on organization-level custom fields, membership rules, or shared organization tickets, you'll need to plan how that context maps to Plain's Company + Tenant model before writing any migration code.

Migration Approaches

There are six viable paths. Each carries different trade-offs for scope, control, and engineering effort.

1. Plain's Native Zendesk Importer

Plain ships a built-in Zendesk importer accessible from Settings → Zendesk importer. (help.plain.com)

How it works:

1. Enter your Zendesk subdomain and authenticate.
2. Plain imports all end users as Customers, all tickets as Threads, all messages (including internal notes) as notes, and all ticket tags as Labels.
3. Closed/Solved tickets become DONE threads; everything else becomes TODO.
4. After the initial import, new end users, tickets, messages, and tags created in Zendesk are auto-synced into Plain.

When to use it: You want the fastest possible migration, your data needs are standard (users, tickets, conversation history, tags), and you don't need granular control over field mapping.

Pros:

• Zero engineering effort
• Includes ongoing sync for new records after initial import
• Imported data won't trigger webhooks or auto-responders (safe to run in production)

Cons:

• No custom field mapping — Zendesk custom ticket fields don't carry over as Thread Fields
• Organizations are not imported as Companies or Tenants
• Status mapping is coarse (only TODO vs. DONE)
• Changes to existing Zendesk tickets after the initial import (status, priority, assignee) do not keep syncing (help.plain.com)
• No granular filtering — it's all-or-nothing
• Available on Plain's Horizon and Frontier plans

Complexity: Low Scalability: Good for small to mid-size accounts. Large accounts (500K+ tickets) may take hours.

2. API-Based Migration (Zendesk REST → Plain GraphQL)

Build a custom script that extracts from Zendesk's REST API and loads into Plain's GraphQL API.

How it works:

1. Extract users, organizations, tickets, and comments from Zendesk using incremental export endpoints.
2. Transform data: map statuses, flatten organization data into Tenant/Company structures, convert custom fields to Thread Field schemas.
3. Load into Plain using GraphQL mutations: upsertCustomer, importThread, importThreadMessages, and the attachment upload flow. (plain.com)
4. Rebuild relationships: link Customers to Companies, assign Tenants, apply Labels.

When to use it: You need custom field mapping, organization migration, attachment handling, selective data filtering, or historical timestamp preservation.

Pros:

• Full control over every record and transformation
• Preserves timestamps, author attribution, and attachments
• Idempotent re-runs via externalId — safe to resume after failures
• Imported threads don't trigger SLAs or auto-responders

Cons:

• Significant engineering effort (see Timeline Estimates below for sizing variables)
• Must handle rate limits on both sides
• Error handling, retries, and relationship sequencing are your responsibility
• Attachment re-upload logic is non-trivial

Complexity: High Scalability: Excellent with proper batching and cursor-based pagination.

3. CSV Export → Transform → API Import

A hybrid approach: export from Zendesk using its native CSV/JSON export, transform offline, then load via Plain's GraphQL API.

How it works:

1. Enable data exports in Zendesk (account owner may need to contact Zendesk support to activate this).
2. Export tickets, users, and organizations as JSON or CSV from Admin Center → Account → Tools → Reports → Export.
3. Transform the exported files: clean data, map fields, restructure for Plain's model.
4. Load into Plain using GraphQL mutations or the TypeScript SDK.

When to use it: Your Zendesk plan doesn't support high API rate limits but does support bulk export, or you want an offline transformation step for auditing.

Pros:

• Avoids Zendesk API rate limits during extraction
• Transformation can be done offline with any tool (Python, SQL, spreadsheets)

Cons:

• Zendesk's CSV export doesn't include ticket comments or attachments — you'll still need the API for those (support.zendesk.com)
• Export tools are not available on Zendesk Team plans
• No ongoing sync capability
• JSON exports on large accounts can take up to 24 hours

Complexity: Medium Scalability: Good for extraction; limited by Plain's API rate limits on the load side.

4. Managed Migration Service

Hand the migration to a team that specializes in helpdesk data moves — ClonePartner, or a similar provider.

How it works:

1. Provider connects to both Zendesk and Plain via API.
2. A sample migration runs on a subset of data for review.
3. Field mapping is configured and approved.
4. Full migration executes, often over a weekend.
5. Delta sync captures any records created during the migration window.

When to use it: You have limited engineering bandwidth, complex data (custom objects, multi-level relationships), or strict timelines.

Pros:

• No internal engineering time
• Handles edge cases the provider has seen before
• Usually includes validation and delta sync

Cons:

• Cost (varies by volume and complexity)
• Less control over transformation logic
• Requires vendor trust with API credentials

Complexity: Low (for your team) Scalability: Handles enterprise volumes.

5. Custom ETL Pipeline

Deploy a purpose-built data pipeline (e.g., Airflow, dbt) to extract Zendesk data into a staging store, transform it, build ID crosswalks, and push to Plain through controlled workers.

When to use it: Multi-brand, compliance-heavy, M&A scenarios, custom objects, or when Zendesk is one of several source systems being consolidated.

Pros:

• Full auditability and replay capability
• Most reliable for large-scale migrations

Cons:

• Longest delivery time and most testing
• Risk of over-engineering for a one-time event

Complexity: High Scalability: Enterprise.

6. Middleware Platforms (Zapier, Make, n8n)

Use an integration platform to orchestrate the data flow between Zendesk and Plain.

When to use it: You want lightweight, ongoing sync for a small subset of data — not a full historical migration.

Pros:

• No-code/low-code setup
• Good for ongoing sync of new tickets

Cons:

• Not designed for bulk historical migration
• Middleware rate limits stack on top of API rate limits
• Transformation logic is limited to what the platform supports
• Cost scales with volume (per-task pricing)

Complexity: Low Scalability: Poor for bulk migration. Acceptable for low-volume ongoing sync.

Approach Comparison

Recommendations by scenario:

• Small team, standard data, fast timeline: Start with Plain's native Zendesk importer. It's included in your plan, it's fast, and it handles core objects.
• Mid-size account with custom fields and org data: API-based migration or managed service, depending on engineering availability.
• Enterprise with 500K+ tickets and strict requirements: Managed migration service or custom ETL. The edge cases at scale consume more engineering time than most teams expect.
• Ongoing sync between Zendesk and Plain: Plain's native importer supports this for new records. For more granular control, build a webhook-driven sync using Zendesk triggers + Plain's GraphQL API.

Timeline Estimates

Migration timelines vary based on concrete variables, not abstract "size" categories. The primary factors:

These estimates assume one engineer working on the migration. The extraction phase is typically 20% of the effort; transformation and edge case handling is 50%; loading and validation is 30%.

When Not to Build In-House

DIY migrations fail in predictable ways:

• Broken relationships. Customer-to-Company links, Tenant assignments, and thread-to-customer associations silently break when IDs don't map cleanly.
• Incomplete conversation history. Missing internal notes, orphaned attachments, or out-of-order messages make historical threads unusable.
• Underestimated scope. The extraction is the easy part. Transformation — handling edge cases, duplicates, encoding issues, and null fields — takes 3–5x the expected effort.
• Hidden API costs. Zendesk's incremental export endpoint is capped at 10 requests per minute. A million-ticket account takes hours just to extract, and a single dropped connection means re-running from the last cursor.

The failure mode is rarely "the API call failed." It's usually "the relationships looked fine until agents tried to work real tickets on Monday."

Pre-Migration Planning

Data Audit Checklist

Before migrating, inventory everything in your Zendesk instance:

• Tickets: Total count, date range, statuses. How far back do you need?
• Users (end-users): Active vs. suspended vs. deleted. Deduplicate by email.
• Organizations: Which ones are actively used? Do they carry custom fields?
• Agents: Active and legacy. Legacy agents must exist in Plain to preserve assignment history.
• Custom fields: Ticket fields, user fields, org fields. Which are still in use? Document data types.
• Tags: Full list. Which map to Plain Labels?
• Macros and triggers: These won't migrate — document them for manual rebuild.
• Attachments: Total size. Any formats that might not transfer?
• Knowledge base (Zendesk Guide): Articles, categories, sections. Count and languages.
• Satisfaction ratings: Plain doesn't import CSAT data from Zendesk. Export separately (see CSAT Data Handling).
• Custom objects (Sunshine): Inventory all object types, relationships, and record counts.

Define Migration Scope

Not everything needs to move. Common exclusions:

• Spam and suspended tickets
• Test tickets and internal test users
• Tickets older than 2–3 years (unless required for compliance)
• Deleted or suspended user accounts
• Unused custom fields and tags

Migration Strategy

For Zendesk to Plain, a big-bang cutover (migrating all historical data over a weekend) is the most common approach, paired with a delta sync just before go-live to catch tickets created during the migration window. Plain's native importer is essentially a big-bang approach with built-in ongoing sync. For API-based migrations, a phased or newest-first strategy reduces risk.

Data Model and Object Mapping

This is where migrations succeed or fail. Every Zendesk object needs a destination in Plain's schema.

Object-Level Mapping

Field-Level Mapping

Migration Architecture and API Constraints

The data flow follows a standard ETL pattern:

Zendesk (REST API / Export) → Extract → Transform → Load → Plain (GraphQL API)

Maintain a durable ID crosswalk at every stage — Zendesk IDs to Plain IDs — so you can audit, resume, and roll back.

Authentication Setup

Zendesk: Create an API token in Admin Center → Apps and integrations → Zendesk API → Zendesk API Settings. Enable token access. Use the format {email}/token:{api_token} for basic auth. For production migrations, Zendesk recommends OAuth — create an OAuth client in Admin Center and use the resulting access token. API tokens will be permanently deactivated on April 30, 2027. (developer.zendesk.com)

Plain: Generate an API key in Settings → API Keys. Select the workspace you're migrating into. The key needs permissions for customer management, thread management, and attachment uploads. Store the key securely — it cannot be retrieved after creation.

Extraction from Zendesk

The Incremental Export API is the recommended extraction path for tickets, users, and organizations:

# Fetch tickets updated since a given timestamp
curl https://{subdomain}.zendesk.com/api/v2/incremental/tickets/cursor.json?start_time=1609459200 \
  -u {email}/token:{api_token}

Key constraints:

• Incremental exports are limited to 10 requests per minute (30 with the High Volume API add-on)
• Returns up to 1,000 records per page with cursor-based pagination
• Ticket comments require a separate call per ticket: GET /api/v2/tickets/{id}/comments.json
• Attachments must be downloaded individually from their content_url
• Archived tickets (closed > 120 days) are excluded from some standard API endpoints but are included in incremental exports

Loading into Plain

Plain's GraphQL API accepts mutations for creating and updating every object type. For historical migrations, use the import mutations (importThread, importThreadMessages) rather than standard create mutations — they preserve original timestamps and don't trigger SLAs or auto-responders. (plain.com)

# Upsert a customer
mutation {
  upsertCustomer(input: {
    identifier: { emailAddress: "user@example.com" }
    onCreate: {
      fullName: "Jane Doe"
      email: { email: "user@example.com" isVerified: true }
      externalId: "zd_user_12345"
    }
    onUpdate: {
      fullName: { value: "Jane Doe" }
      externalId: { value: "zd_user_12345" }
    }
  }) {
    customer { id fullName }
    error { message }
  }
}

# Import a historical thread
mutation {
  importThread(input: {
    customerIdentifier: { emailAddress: "user@example.com" }
    externalId: "zd_ticket_98765"
    title: "Cannot access API dashboard"
    status: DONE
    createdAt: "2024-03-15T10:00:00Z"
    labelTypeIds: ["lt_billing", "lt_bug"]
    components: [
      { componentText: { text: "I'm getting a 403 error..." } }
    ]
  }) {
    thread { id status }
    error { message }
  }
}

Plain's import mutations are idempotent on externalId, so you can safely resume after failures without creating duplicate threads or messages. (plain.com)

Rate Limit Management

Both platforms return rate limit headers. Your migration script must read Retry-After (Zendesk) or x-ratelimit-reset (Plain) headers and back off accordingly. Never hard-code sleep intervals — use the headers.

Step-by-Step Migration Process

Step 1: Configure Plain Workspace

Before importing any data:

1. Create your Plain workspace and configure support channels (email, Slack, etc.).
2. Generate an API key in Settings → API Keys with permissions for customer, thread, and attachment management.
3. Set up Thread Field schemas in Settings → Thread Fields for any Zendesk custom ticket fields you need to preserve. Match data types exactly — Plain rejects mutations with type mismatches.
4. Create Labels matching your Zendesk tags (or the subset you want to keep).
5. Create Tenants for each Zendesk Organization you want to map.
6. Add Users (agents) to Plain. Agent IDs must exist before you can assign threads.
7. Configure Tiers if you use Zendesk SLA policies tied to organization tiers.

Step 2: Extract from Zendesk

Use the incremental export for bulk extraction. Handle rate limits and HTTP errors with header-based backoff:

import requests
import time
import json
import logging
 
ZENDESK_SUBDOMAIN = "yourcompany"
ZENDESK_EMAIL = "admin@yourcompany.com"
ZENDESK_TOKEN = "your_api_token"
 
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
 
def extract_tickets(start_time=0):
    url = f"https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/incremental/tickets/cursor.json"
    params = {"start_time": start_time}
    auth = (f"{ZENDESK_EMAIL}/token", ZENDESK_TOKEN)
    
    all_tickets = []
    while url:
        resp = requests.get(url, params=params, auth=auth)
        
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 60))
            logger.warning(f"Rate limited. Retrying after {retry_after}s")
            time.sleep(retry_after)
            continue
        
        if resp.status_code >= 500:
            logger.error(f"Server error {resp.status_code}. Retrying in 30s")
            time.sleep(30)
            continue
            
        if resp.status_code >= 400:
            logger.error(f"Client error {resp.status_code}: {resp.text}")
            raise Exception(f"Unrecoverable error: {resp.status_code}")
        
        data = resp.json()
        all_tickets.extend(data.get("tickets", []))
        logger.info(f"Extracted {len(all_tickets)} tickets so far")
        url = data.get("after_url") if not data.get("end_of_stream") else None
        params = {}  # after_url includes params
    return all_tickets

Step 3: Transform Data

The transformation layer handles:

• Status mapping: new, open → TODO; pending → SNOOZED; on-hold → TODO or SNOOZED based on your semantics; solved, closed → DONE
• User deduplication: Zendesk allows multiple users with similar emails; Plain enforces email uniqueness
• Organization → Tenant mapping: Map Zendesk organization_id to Plain Tenant externalId
• Custom field conversion: Cast Zendesk field values to match Plain Thread Field types. Plain's schema is strict — passing a string into an enum field fails the entire mutation.
• Tag → Label mapping: Normalize spelling and casing, filter out irrelevant tags before creating Labels
• HTML → compatible format: Convert Zendesk HTML comments into the format expected by Plain (often Markdown or plain text, depending on the component used)

Step 4: Load into Plain

Use Plain's TypeScript SDK (@team-plain/typescript-sdk) or direct GraphQL calls. The high-level migration loop:

for zendesk_ticket in zendesk_incremental_export():
    customer = plain_upsert_customer(
        email=zendesk_ticket.requester_email,
        external_id=f'zd_user_{zendesk_ticket.requester_id}',
        full_name=zendesk_ticket.requester_name,
    )
 
    thread = plain_import_thread(
        customer_email=zendesk_ticket.requester_email,
        external_id=f'zd_ticket_{zendesk_ticket.id}',
        title=zendesk_ticket.subject,
        status=map_status(zendesk_ticket.status),
        priority=map_priority(zendesk_ticket.priority),
        created_at=zendesk_ticket.created_at,
        labels=map_tags(zendesk_ticket.tags),
        thread_fields=map_custom_fields(zendesk_ticket.custom_fields),
        tenant_id=resolve_tenant(zendesk_ticket),
    )
 
    for batch in chunk(map_comments_and_notes(zendesk_ticket), 25):
        uploaded_attachment_ids = upload_needed_attachments(batch)
        plain_import_thread_messages(
            thread_id=thread.id,
            messages=attach_ids(batch, uploaded_attachment_ids),
        )

importThreadMessages batches up to 25 messages per call. Upload attachments before referencing them — Plain deletes unused uploaded attachments after 24 hours. (plain.com)

Error Handling for Plain's GraphQL API

Plain's strict schema means you'll encounter errors beyond rate limits. Handle them explicitly:

def handle_plain_response(response, context_id):
    """Handle Plain GraphQL mutation responses."""
    data = response.json().get("data", {})
    
    # Check for top-level GraphQL errors
    if response.json().get("errors"):
        for error in response.json()["errors"]:
            logger.error(f"GraphQL error for {context_id}: {error['message']}")
            # Schema violations (wrong type, invalid enum) are not retryable
            if "validation" in error.get("extensions", {}).get("code", ""):
                log_skip(context_id, error["message"])
                return None
            raise RetryableError(error["message"])
    
    # Check for mutation-level errors (e.g., from upsertCustomer)
    mutation_result = list(data.values())[0] if data else {}
    if mutation_result.get("error"):
        error = mutation_result["error"]
        logger.error(f"Mutation error for {context_id}: {error['message']}")
        # Log and skip non-retryable errors; raise retryable ones
        if error.get("type") == "VALIDATION":
            log_skip(context_id, error["message"])
            return None
        raise RetryableError(error["message"])
    
    return mutation_result
 
def log_skip(context_id, reason):
    """Log skipped records for post-migration review."""
    with open("skipped_records.jsonl", "a") as f:
        f.write(json.dumps({"id": context_id, "reason": reason}) + "\n")

Common failure patterns:

• VALIDATION errors: A Thread Field received a string value but expected an enum. Fix in the transform layer; these are not retryable.
• NOT_FOUND errors: A referenced customer, tenant, or label doesn't exist. Check import ordering.
• bulk_partial_failure on importThreadMessages: Some messages in the batch succeeded, others failed. Log per-message results. Don't retry the entire batch — only retry the failed messages. (plain.com)

Step 5: Rebuild Relationships

After loading core objects:

1. Assign Customers to Tenants using the addCustomerToTenants mutation.
2. Update Company assignments if email-domain-based auto-assignment doesn't match your org structure.
3. Apply Thread Fields to threads with custom data.
4. Add Labels to threads based on tag mapping.

Step 6: Handle Attachments

Zendesk attachments are hosted on their CDN. To migrate them, your script must download the file from Zendesk's content_url, upload it to Plain's attachment endpoint, and reference the resulting asset ID in the corresponding thread message. Plain allows up to 100 attachments per message, but email attachments cap at 6 MB. (plain.com)

For inline images embedded directly in Zendesk comment HTML, parse the HTML, download the image, upload it to Plain, and rewrite the image source URL. Zendesk-hosted inline images may require authentication to view, so they won't render if you carry over the raw HTML.

Step 7: Validate

See the Validation and Testing section below.

Knowledge Base Migration (Zendesk Guide → Plain Help Center)

Zendesk Guide articles don't transfer via Plain's native importer. This requires a separate migration path.

Zendesk Guide Data Model

Zendesk Guide organizes content hierarchically:

• Categories → Sections → Articles
• Articles contain HTML body content, optional attachments, labels, and metadata (author, creation date, draft/published status)

Extraction

Use the Zendesk Help Center API to extract articles:

# List all articles (paginated, 100 per page)
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles.json?per_page=100 \
  -u {email}/token:{api_token}
 
# Get article body and metadata
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}.json \
  -u {email}/token:{api_token}
 
# List article attachments (inline images, PDFs)
curl https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/attachments.json \
  -u {email}/token:{api_token}

Key fields to extract: title, body (HTML), section_id, draft, promoted, created_at, updated_at, label_names, and attachments.

Transformation

• Convert Zendesk Guide HTML to the format expected by Plain's Help Center (check Plain's docs for supported content format — typically Markdown or structured content)
• Map Zendesk Categories/Sections to Plain Help Center collections or categories
• Download and re-host any inline images — Zendesk-hosted image URLs will break after migration
• Preserve the section hierarchy as much as Plain's Help Center structure allows

Loading

Plain's Help Center API supports article creation programmatically. Create collections first (mapping from Zendesk categories/sections), then create articles within those collections.

What Doesn't Transfer

• Article view counts and vote data
• Community posts and comments (Zendesk Gather)
• Content blocks shared across articles
• Article-level permissions (restricted articles by user segment)

CSAT Data Handling

Plain doesn't import Zendesk satisfaction ratings. To preserve this data:

Export CSAT Data from Zendesk

# Export satisfaction ratings (paginated)
curl https://{subdomain}.zendesk.com/api/v2/satisfaction_ratings.json?per_page=100 \
  -u {email}/token:{api_token}

Each rating includes: id, score (good/bad), comment, ticket_id, requester_id, assignee_id, created_at, and updated_at.

Storage Options

1. CSV/JSON archive: Export all ratings with associated ticket IDs. Store in S3 or your data warehouse. Cross-reference using zd_ticket_{id} external IDs if you need to look up CSAT for a specific thread later.
2. Data warehouse: Load into your analytics database (BigQuery, Snowflake, etc.) for historical CSAT reporting.
3. Thread Fields: If you need CSAT visible per-thread in Plain, create a Thread Field (e.g., zendesk_csat_score with values good/bad) and populate it during migration. This is a static snapshot — it won't update.

Sunshine Custom Objects

Zendesk Sunshine custom objects (custom object types, records, and relationships) have no equivalent in Plain. Three handling strategies, depending on how the data is used:

Strategy 1: Flatten into Thread Fields

If custom objects contain per-ticket metadata (e.g., a "Contract" object linked to tickets), extract the relevant fields and map them to Thread Fields.

Example: A Zendesk custom object "Contract" with fields contract_id, renewal_date, plan_tier:

# Extract custom object records linked to a ticket
def get_ticket_custom_object_data(ticket_id):
    # Zendesk Custom Object Records API
    resp = requests.get(
        f"https://{SUBDOMAIN}.zendesk.com/api/v2/custom_objects/contract/records",
        params={"filter[ticket_id]": ticket_id},
        auth=auth
    )
    records = resp.json().get("custom_object_records", [])
    if records:
        return {
            "contract_id": records[0]["custom_object_fields"]["contract_id"],
            "renewal_date": records[0]["custom_object_fields"]["renewal_date"],
            "plan_tier": records[0]["custom_object_fields"]["plan_tier"],
        }
    return {}

Create corresponding Thread Fields in Plain (contract_id as string, renewal_date as string, plan_tier as enum) and populate during thread import.

Strategy 2: Surface via Customer Cards

If custom objects contain customer-level data (e.g., subscription details, product usage), build a Customer Card that pulls from your own backend. This is the preferred approach when the data is dynamic — Customer Cards fetch fresh data on each load rather than storing a static snapshot.

Strategy 3: Archive Externally

If custom objects are used for internal workflows that won't continue in Plain, export the records and store them in your data warehouse for reference. Use the Zendesk Custom Objects API to extract all records:

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{object_type}/records.json \
  -u {email}/token:{api_token}

Multi-Brand Zendesk Setups

If your Zendesk instance uses multiple brands (separate support portals with distinct URLs, email addresses, and branding), each brand requires separate handling:

1. Map brands to Plain structure. Options:

   • Separate Plain workspaces per brand (full isolation, separate billing)
   • Labels to tag threads by brand origin (simpler, single workspace)
   • Tenants to separate brand-level views (if brands map to customer segments)

2. Extract per-brand. Use the brand_id filter on Zendesk's ticket API:

   curl "https://{subdomain}.zendesk.com/api/v2/tickets.json?filter [brand_id]={brand_id}" \
     -u {email}/token:{api_token}

3. Handle cross-brand users. A single Zendesk user can submit tickets across brands. In Plain, this customer will have one record regardless of which brand the original ticket belonged to.

4. Knowledge base per brand. Each Zendesk brand can have its own Help Center. Extract articles per brand and decide whether to consolidate or keep separate in Plain.

Edge Cases and Challenges

These are the issues that burn teams who don't plan for them:

• Duplicate customers. Zendesk allows multiple user records with overlapping emails (especially suspended/deleted users). Plain enforces email uniqueness. Deduplicate before loading — use the most recently active record.
• Missing requesters. Some Zendesk tickets have deleted or anonymous requesters. Create a fallback customer in Plain (e.g., "Unknown Customer") to maintain thread integrity.
• Multi-organization users. Zendesk supports users belonging to multiple organizations. Plain assigns one Company per customer. Decide which org wins, or use Tenants as the secondary grouping.
• Relationship ordering. If you import a thread with a tenantId, the customer must already be a member of that tenant. Load memberships first or fail fast. (plain.com)
• Side conversations. Zendesk Side Conversations (child tickets, Slack messages, emails) have no direct Plain equivalent. Import them as notes or separate threads.
• Suspended tickets. Tickets caught by Zendesk's spam filter. Decide whether to migrate or discard them.
• Ticket followers and CCs. Zendesk tickets can have CCs and followers. Plain threads support multiple participants but the mapping isn't 1:1. Plan how CC'd users appear.
• Partial failures. importThreadMessages can return per-message errors and a top-level bulk_partial_failure. Log at message granularity, not just ticket level. (plain.com)
• Status nuance. Zendesk pending and on-hold are not the same thing operationally. Pending stops the SLA clock and signals "waiting for the customer." On-hold stops the SLA clock but signals "waiting for an internal/third-party resolution." Don't map both blindly to one Plain state without understanding your team's workflow. (support.zendesk.com)
• Free email domains. Customers using gmail.com, outlook.com, yahoo.com, etc. will all be auto-assigned to the same Company in Plain. Override these assignments via API or exclude free domains from Company auto-assignment.

Limitations and Constraints

Be explicit about what you're giving up:

Validation and Testing

Never run a migration directly into your production Plain workspace without testing first. Use Plain's free trial to run a test migration with a subset of data before committing.

Record Count Comparison

After migration, compare counts across every object type:

Field-Level Validation

For a random sample (5–10% of records, minimum 100):

• Verify customer name, email, and externalId match
• Confirm thread status, title, and label assignments
• Check that conversation history (messages + internal notes) is complete and in order
• Validate Thread Field values against source Zendesk custom fields
• Open attachments to confirm they're not corrupted
• Verify that createdAt timestamps match the original Zendesk ticket creation dates

UAT Process

1. Have 2–3 agents use Plain for a day on migrated data.
2. Ask them to find specific historical tickets by customer or subject.
3. Verify that conversation context is sufficient for ongoing support.
4. Test reply flows, label assignment, and thread status changes.

Rollback Plan

For API-based migrations:

• Tag all migrated records with a source: zendesk_migration label
• Maintain a mapping file of Zendesk IDs → Plain IDs
• If rollback is needed, use the mapping file to identify and delete migrated records via API
• Keep Zendesk active (read-only) for at least 2 weeks post-cutover

For post-migration QA, pair this guide with Post-Migration QA: 20 Tests to Run After Your Help Desk Data Migration.

Post-Migration Tasks

Rebuild Automations

Nothing migrates automatically. Rebuild in Plain:

• Auto-responders: Configure for each support channel.
• Rules / Workflows: Recreate Zendesk triggers as Plain rules (assignment, labeling, SLA escalation).
• SLA policies: Set up per-tier SLAs in Plain's tier system.
• Integrations: Reconnect Linear, Jira, GitHub, Slack, and any webhook-based integrations.

Reroute Inbound Channels

Update your support email addresses (e.g., support@company.com) from Zendesk to Plain's inbound email handlers.

Team Onboarding

• Train agents on Plain's keyboard-first UI — it's substantially different from Zendesk.
• Walk through the Todo / Done / Snoozed workflow, Thread Fields, Labels, and Tenant-based filtering.
• Set up Customer Cards to surface data from your internal systems.
• Document the new escalation workflow (Plain → Linear/Jira).

Monitor for Data Gaps

For the first 2 weeks post-migration:

• Monitor for missing conversation history reported by agents
• Check that auto-sync (if using native importer) is capturing new Zendesk data
• Verify that Customer Card data is loading correctly
• Watch for rate limit errors in any ongoing sync scripts
• Review the skipped_records.jsonl log for any records that failed during migration

Best Practices

1. Back up everything first. Run a full JSON export from Zendesk before starting. Store it in S3 or equivalent.
2. Freeze Zendesk configuration. Implement a change freeze at least two weeks before migration. No new custom fields, no new macros.
3. Migrate newest data first. If using an API-based approach, start with the last 90 days. Let agents validate on recent, familiar data.
4. Don't migrate what you don't need. Spam, test tickets, and 5-year-old solved tickets rarely add value. Define a cutoff date.
5. Preserve Zendesk IDs. Always store the original Zendesk ID in Plain's externalId field. You'll need this for troubleshooting, auditing, and post-migration fixes.
6. Run a delta sync. Run your main migration over a weekend. Before go-live, run a delta script that only pulls tickets updated since the main migration started.
7. Keep Zendesk alive (briefly). Maintain your Zendesk instance in a read-only state for at least 30 days post-migration as a safety net.
8. Use idempotent imports. Plain's importThread and importThreadMessages mutations are idempotent on externalId, so you can resume after failures without duplicates.
9. Log everything. Write every skipped record, transformation decision, and error to a structured log file. Post-migration debugging without logs is guesswork.
10. Test with production data. Use a full copy of your Zendesk data for test runs, not a synthetic subset. Edge cases only surface with real data.

For a pre-migration walkthrough, see our Zendesk Migration Checklist and Help Desk Data Migration Playbook.

Making the Call

If your migration scope fits within Plain's native importer — users, tickets, messages, tags — start there. It's the lowest-risk, lowest-effort path, and it includes ongoing sync for new records.

If you need custom fields, organization-level data, knowledge base content, attachments with full fidelity, or selective filtering, you're looking at an API-based build or a managed service. The decision between those two comes down to engineering bandwidth and timeline.