Shopify Order Import

Import Shopify orders into the app with money, fulfilment, and later edits accurately kept.

involved Payments & Finance

What it adds

A resumable import of the connected store's orders, mirroring line items, discounts, taxes, and fulfilment state locally.

What your agent is told to do

1
Separate the initial backfill from the ongoing feed. The backfill walks history in a stable order behind a resumable cursor; the feed applies live updates as they arrive.
2
Key every imported order on the shop identifier together with the store's own order identifier, so re-running the import updates existing rows instead of duplicating them.
3
Store money as an exact decimal with its currency alongside it, and keep both the shop currency and the presented currency where they differ. Do not convert to a single display currency on the way in, because the original amounts cannot be recovered afterwards.
4
Treat an order as a state machine rather than a snapshot. Edits, cancellations, refunds, and partial fulfilments all arrive later as new versions of a record you already hold.
5
Customer identity and marketing consent are owned by Shopify Customer Sync. Link to the customer record that brief maintains rather than writing customer fields from an order payload.

Edge cases it handles

A backfill interrupted halfway must resume from its cursor without re-importing what it already wrote. Restarting from the beginning is acceptable only if every write is keyed and idempotent.
External identifiers are unique per store, not globally. Two connected shops will eventually produce the same order number, and an unscoped key silently overwrites one with the other.
Test orders placed while a store was in a sandbox or test payment mode must be flagged or excluded, or they will inflate every revenue figure the app reports.
An order can be edited after the fact, cancelled, refunded in part, and fulfilled across several shipments. Each of those is a later version of the same order and must replace the local state rather than add a second row.
Money must never pass through a floating-point value. Multi-currency stores also present two amounts for the same order, and the app has to record which is which.
Updates arrive for an order while the backfill is still running, sometimes before that order has been imported at all. Queue them and apply them by version or timestamp so older backfill data cannot overwrite a newer change.
Orders reference products and variants that may since have been deleted. Keep the title, price, and identifier the line item captured at the time rather than depending on a live product lookup.
A store with years of history will hit the provider's rate limits during a backfill. Pace the import and back off when refused rather than retrying in a tight loop.

Definition of done

A backfill can be interrupted and resumed, and re-running it produces no duplicate orders.
Order keys include the shop, so two connected stores cannot collide.
Cancelled, refunded, edited, test, and partially fulfilled orders each land in a distinct, queryable local state.
Money is stored as exact decimals with explicit currency, and multi-currency orders retain both amounts.
Updates arriving mid-backfill are applied in the correct order and are never overwritten by older data.
Customer records are linked from Shopify Customer Sync rather than created here.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Shopify Customer Sync

Paddle Subscription Checkout

WooCommerce Order Sync

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.