Migrate from Shopify

This guide maps Shopify’s model onto Flightdeck so you can plan a move with your eyes open. Some things transfer cleanly and immediately; some are operator-assisted today because the self-serve surface has not shipped yet. We name each one honestly rather than implying parity that does not exist.

The short version: Flightdeck’s strong, shipped story is consuming a provisioned store headlessly — you build a frontend against @dscodotco/sdk and place real orders through checkout.submit. Getting your catalog in is a scripted loop over the merchant API, not a one-click importer. Plan for that and the migration is straightforward.

Concept mapping

What transfers cleanly, and what is operator-assisted

Being blunt about the seams saves you a surprise mid-migration.

Orders and webhooks

On Shopify you would subscribe to orders/create. On Flightdeck the equivalent is the orders.placed outbound webhook, dispatched from the outbound webhook edge with an envelope that carries a required tenant_ref and is self-contained (a consumer never has to call back to use it). Point your fulfillment or ERP integration at that instead of orders/create. The full event catalog, envelope shape, and delivery/retry semantics are in Webhooks; order state values (placed, processing, shipped, refunded, …) are in Order lifecycle.

Checkout is one shot, not a redirect

This is the biggest behavioral difference from Shopify. There is no hosted checkout page and no redirect. Your server submits the cart and the card together in a single call, and the platform authorizes payment, runs the fraud floor, prices the authoritative total (shipping + tax), and places the order — or returns an honest decline.

// Server-side only — a Route Handler, server action, or edge function.
const result = await store.checkout.submit(
  {
    customer_ref: "guest:shopper@example.com",
    items: [{ variant_id: "var_123", quantity: 1 }],
    card: { ccnumber: "4111111111111111", ccexp: "12/28", cvv: "123" },
  },
  { idempotencyKey: `cart-${cartId}:attempt-1` },
);

Because your server touches raw card fields, that server is inside PCI-DSS scope (SAQ D territory) — the same fact of life as any non-hosted integration. Keep card data on the browser-to-your-HTTPS-handler-to-API path, never logged or stored. The full body shape, the tender order (store credit, then gift card, then card), the fraud floor, and how to read every outcome branch are in Checkout.

Importing your Shopify catalog

There is no bulk importer. The shipped, honest pattern is a scripted, idempotent loop over the merchant catalog API, keyed on the product slug so it converges on re-run instead of duplicating. These are fdk_ merchant routes under scope manage:own_catalog; the tenant is carried by the credential.

type ImportRow = {
  slug: string;                     // Shopify "Handle" maps here — unique per tenant
  name: string;                     // Shopify "Title"
  description?: string;             // Shopify "Body (HTML)" — strip or keep as needed
  status?: "draft" | "active";      // set at create time only; default active
  variants: { sku: string; price_cents: number; label?: string }[];
};
 
// Shopify's decimal price string -> integer cents.
const toCents = (price: string) => Math.round(Number(price) * 100);

const API = "https://api.ruo.pro";
const KEY = process.env.FLIGHTDECK_FDK_KEY!; // manage:own_catalog
 
async function call(method: string, path: string, body: unknown) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { authorization: `Bearer ${KEY}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  return { status: res.status, json: await res.json() };
}
 
for (const row of rows) {
  const created = await call("POST", "/v1/merchant/catalog/products", {
    slug: row.slug,
    name: row.name,
    description: row.description ?? null,
    status: row.status ?? "active",
  });
 
  let productId: string;
  if (created.status === 201) {
    productId = created.json.product.id;
  } else if (created.json.error?.code === "slug_exists") {
    // Imported on a previous run — look it up and continue.
    const found = await call("GET", "/v1/merchant/catalog/products", {});
    productId = found.json.products.find((p: any) => p.slug === row.slug).id;
  } else {
    throw new Error(`create failed for ${row.slug}: ${created.json.error?.message}`);
  }
 
  for (const v of row.variants) {
    const vres = await call("POST", `/v1/merchant/catalog/products/${productId}/variants`, {
      sku: v.sku,
      price_cents: v.price_cents,
      label: v.label ?? null,
      currency: "usd",
    });
    // A duplicate SKU is likewise refused, not duplicated — safe to re-run.
    if (vres.status !== 201 && vres.json.error?.code !== "sku_exists") {
      throw new Error(`variant ${v.sku} failed: ${vres.json.error?.message}`);
    }
  }
}

curl https://api.ruo.pro/v1/merchant/catalog/products \
  -H "Authorization: Bearer fdk_your_key_here"

A realistic migration order

Related

• Build a storefront from scratch — the flagship consumer tutorial.
• Import an existing catalog — the scripted import in full.
• Checkout — the one-shot order-placement contract.
• Webhooks — the orders.placed event and delivery semantics.
• Migrate from a headless CMS — if you are coming from a custom storefront rather than Shopify.