New: payments, credit notes, tax mapping and order reconciliation for Zoho Books — see all features
Order Sync

How to Backfill Historical Shopify Orders into Zoho (Dry Run First)

Send past Shopify orders into Zoho without creating duplicates. Backfill by date range or order number, preview the result with a dry run, and bring existing orders up to date with invoices, payments, and credit notes.

When you need a backfill

Live order sync only helps from the day you turn it on. Everything before that is still sitting in Shopify, and there are several good reasons to bring it across:

  • You have just installed the connector and want this quarter's orders in Zoho, not only tomorrow's.
  • Auto sync was off for a few days and you need to fill the gap.
  • You switched on payments or refund credit notes and want existing orders brought up to date.
  • You are moving from another connector or from manual entry and need to catch up without duplicating what is already there.

The risky way to do this is to select a few hundred orders and hope. The Backfill tab gives you a controlled way: pick exactly which orders, preview what would happen, then run it for real.

What a backfill actually runs

A backfill is not a separate import with its own rules. It sends past Shopify orders through the same sync as live orders, with your current settings. For each order, the app reads the order as it is now and does whatever Zoho is still missing, in a fixed order: documents first, then the invoice, then payments, then credit notes, then tracking, then voiding for cancelled orders.

Two consequences follow from that design.

First, whatever you have configured under Order Settings and Documents & Accounting applies. If orders are created as Sales order, then invoice when paid with Record payments on, a paid order from last month arrives with its sales order, its invoice, and its payment in one pass.

Second, it is safe to run again. Each step is recorded on the Shopify order before the next one starts, so an order already in Zoho is brought up to date and never created twice.

You will find it under Orders, on the Backfill tab, in a section called Run an order backfill. Zoho has to be connected first.

Pick the orders: date range or order numbers

There are two ways to say which orders you mean.

By date range is the default. Set a Start date and an End date, or click one of the quick ranges: Week to date, Month to date, or Last 30 days. Dates are in UTC, so an order placed late in the evening in your local time may fall on the next day. If the edges matter, widen the range by a day.

By order numbers is for targeted fixes. Paste the numbers into the box, separated by commas or new lines, for example #1001, #1002. A bare number is treated as an order number, so 1001 works too. Only those orders are synced and no date scan happens. This is the right mode when support hands you a list of orders that never reached Zoho.

Dry run first

Tick Dry run and the button changes to Start dry run. A dry run writes what would happen for each order to Logs and creates nothing in Zoho. Nothing is written to Shopify either.

Open Logs afterwards and filter Status to Dry run. Each order has a row listing the actions the real run would take, such as creating a sales order, creating the invoice from it, recording a payment of a given amount through a given gateway, or creating a credit note for a refund. An order that needs nothing says so.

A few things a dry run is especially good at catching:

  • A document option that raises no invoice while payments or refunds are switched on.
  • Orders your filters would hold back. Those get no dry run row, so a row count lower than the number of orders queued is itself a signal.
  • Payments going through a gateway you have not mapped yet.

One limit to keep in mind: a dry run plans from what Shopify knows. It does not search Zoho for an existing document with the same reference, so an order that would be linked rather than created in the real run shows up as a create.

If you have just set up tax mapping, pair the dry run with the checks in the tax mapping guide. If you have just switched on payments, read recording Shopify payments in Zoho Books first.

Only missing orders, or bring everything up to date

The checkbox Only orders that are not in Zoho yet is ticked by default. With it ticked, any order that already has a Zoho link is counted and left alone. This is what you want for filling a gap.

Untick it when the goal is to update existing orders. The backfill then also visits orders already in Zoho and adds whatever they are missing: an invoice that is now due, a payment that was never recorded, a credit note for a refund. This is the mode to use right after you turn on a new accounting feature. Turn on Create a credit note when an order is refunded, untick the checkbox, backfill the last month, and refunds from before the change get their credit notes. The details of that flow are in Shopify refunds to Zoho credit notes.

Limits worth knowing

  • Date range runs handle up to 5,000 orders. If the range holds more, the run stops at that number and the summary tells you to run the rest as a second range. Splitting by month is an easy way to stay under it.
  • Runs by order number take up to 500 orders at a time.
  • Shopify only returns orders from the last 60 days unless the app has been granted access to all orders. If a range further back comes up empty, this is the reason.
  • Filters still apply. Payment status, fulfillment status, order source, and invoice options decide whether an order syncs, exactly as they do for live orders. The one exception is the Only sync orders placed on or after date, which a backfill ignores.
  • Cancelled orders that never synced are skipped when voiding on cancel is switched on. There is no point creating documents only to void them.

Every order runs as its own queued job, with up to three attempts and exponential backoff, and one job runs per order at a time. If Zoho's API limit is reached partway through a large run, a banner explains that syncing is paused and resumes on its own, and the waiting orders are queued again instead of failing. Nothing is lost. See Zoho API limits for what the pause looks like.

Moving from another connector

Migration is where duplicates usually come from, and three settings work together to prevent them.

  • Only sync orders placed on or after. Under Documents, set this date to your cutover day. Live sync then leaves older orders alone, so orders the previous connector already sent are not sent again by a stray update. A backfill ignores this date, which lets you deliberately reach back when you choose to.
  • The reference lookup. Before creating a document, the app looks in Zoho for one whose reference number is the Shopify order name, such as #1001. If it finds one, it links that document to the order instead of creating another. Documents that carry the order name as their reference are picked up this way.
  • Use the Shopify order number as the Zoho document number. If you want Zoho numbers to match Shopify from now on, tick this. If Zoho rejects a number because it is already used or contains a character it does not accept, that order falls back to Zoho's own numbering.

A cautious migration looks like this: set the start date, run a dry run over a small range that overlaps the old connector, read the rows in Logs, then run the real backfill in monthly slices.

Watch it in Logs

When you start a run, a message confirms it is queued and points you to Logs. The backfill writes a summary row saying how many orders were queued and how many were already in Zoho. After that, each order writes its own rows as it syncs.

Use the filters to keep track:

  • Type set to order and Status set to Failed shows what needs attention, with the reason.
  • Skipped shows orders held back by a filter, with the filter named.
  • Retry all failed orders queues every order whose latest result is a failure, and each failed row has its own Retry button.
  • Export CSV downloads the rows matching your filters if you want to hand the list to someone else.

The guide to logs, retries and API limits covers the Logs page in depth.

After the backfill: reconcile

A finished backfill tells you jobs ran. It does not prove the books agree. For that, open Reconcile and compare the same date range. The report shows how many Shopify orders matched a Zoho document with the same total, which are missing, and where the amounts differ. Orders that have never synced can be queued straight from that page. Reconciling before month-end walks through reading the report.

Next step

Open Orders, go to the Backfill tab, choose Last 30 days, tick Dry run, and click Start dry run. Read the results in Logs, fix anything that looks wrong in your settings, then untick Dry run and run it for real. The field reference is in the backfill documentation, and the order backfill overview explains where it fits in order sync.

TopicsBackfillOrder SyncDry RunZoho BooksZoho InventoryMigrationHistorical Orders
FAQ

Common questions

Can I sync old Shopify orders into Zoho?
Yes. Open Orders, go to the Backfill tab, and run a backfill by date range or by order numbers. Past orders go through the same sync as live orders, using your current settings.
Will a backfill create duplicate orders in Zoho?
No. An order that is already in Zoho is brought up to date, never created twice. Before creating a document, the app also looks in Zoho for one whose reference is the Shopify order name and links it if it exists.
What does a dry run do?
A dry run writes what would happen for each order to Logs and creates nothing in Zoho. Use it to check your settings, tax mapping, and payment setup before any real document is created.
How many orders can I backfill at once?
A date range run handles up to 5,000 orders and then tells you to run the rest as a second range. A run by order numbers takes up to 500 orders at a time.
Why does my backfill only find the last 60 days of orders?
Shopify only returns orders from the last 60 days unless the app has been granted access to all orders. Older orders are not visible to the backfill until that access is in place.
Does the backfill respect my order filters?
Yes, with one exception. Payment status, fulfillment status, order source, and invoice options all apply. The Only sync orders placed on or after date is ignored, because a backfill is asked for by date in the first place.

Connect Shopify and Zoho in an afternoon

Start a free trial, connect your Zoho org, and run a dry-run backfill to see exactly what would land in Zoho. No engineering required.