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

Sync Logs, Retries, and Zoho API Limits: Keeping Shopify and Zoho in Step

Sync that fails quietly is worse than no sync. Learn how Zync queues and retries every job, how to read the Logs page, retry failed orders, export a CSV, and what happens when your Zoho API limit is reached.

Sync that fails quietly is worse than no sync

A manual process fails loudly. If nobody types the orders into Zoho, everyone knows. An automated one can fail in silence. An order hits a tax that Zoho does not recognise, the sync stops, and the gap sits there until month-end, when the totals do not match and someone spends an afternoon finding out why.

So the real test of a connector is not whether it syncs on a good day. It is what it does on a bad one, and how quickly you find out. In Zync that comes down to three things: a queue that retries, a log that tells you the truth, and sensible behaviour when Zoho says stop.

Every sync is a queued job

Nothing in Zync talks to Zoho while Shopify is waiting for an answer. A webhook arrives, or you select a sync button, and the work is placed on a queue. A background worker picks it up.

That design has three practical effects:

  • Spikes are absorbed. A flash sale produces a long queue, not dropped orders.
  • Failures are retried. Each job gets up to three attempts, with a wait that starts at one minute and grows with each attempt. A brief Zoho outage or a timeout usually clears on its own.
  • Stores are isolated. Jobs are grouped by shop, so each store's work runs in its own lane.

Orders get one more protection. Shopify often sends several webhooks for the same order within a second: created, paid, updated. Zync processes one job per order at a time, so two of those cannot both conclude that the order is missing from Zoho and each create a document.

Why a retry does not create duplicates

Retrying is only safe if the second attempt knows what the first one did. An order sync is several steps: the documents, then the invoice when it is due, payments, credit notes, tracking, and a void if the order was cancelled. Any step can be interrupted.

Zync handles this in two ways.

First, progress is saved after each step, on the Shopify order itself. The custom.zoho_order_id metafield holds the main Zoho document, and custom.zoho_sync_state records which invoice, payments, credit notes, and shipments have been dealt with. A retry reads that state and continues from where the last attempt stopped.

Second, before creating anything Zync asks Zoho whether it already exists. Documents carry the Shopify order name as their reference number, and each payment and credit note carries a reference that identifies the Shopify transaction or refund behind it. If a previous attempt created the record but lost the reply, the retry finds it in Zoho and links it.

The result is that the same order can be synced any number of times, by a webhook, a retry, a manual sync, or a backfill, and Zoho ends up with one set of documents. The details of those links are in how records are linked.

The Logs page at a glance

Open Logs from the app navigation. The top of the page is a row of tiles: counts of what happened in the last 24 hours by status, and Orders needing attention.

Every row in the table below has one of four statuses:

  • Success. The work was done. For orders you will see separate rows for each thing that happened, such as a document created, a payment recorded, or a credit note settled.
  • Failed. The sync was attempted and did not go through. The message carries the reason.
  • Skipped. Your settings held the record back, and the message says which setting.
  • Dry run. A backfill dry run worked out what it would do and wrote it here without touching Zoho.

The columns are When, Type, Status, Message, Zoho ID, and Actions. The page shows 50 rows at a time, newest first.

One deliberate choice keeps the page readable: a failing order produces one Failed row, not one per attempt. Three automatic attempts do not turn into three rows.

Filtering and searching

The filter bar has five controls:

  • Type: order, product, customer, or inventory.
  • Status: any of the four above.
  • From and To: a date range.
  • Search: text from the message, an order, or a Zoho ID.

Two searches cover most questions. To follow one order, search for its number and read its rows in sequence. To find every record hit by one problem, search for a word from the error message. A line under the filters shows how many logs match, with Clear filters to reset.

Orders needing attention, and retrying

A raw count of failures is not very useful. An order that failed at nine and synced at ten is not a problem any more. Orders needing attention counts only orders whose most recent result is a failure, which is the list someone actually has to deal with.

When that number is above zero, a banner appears with Retry all failed orders. It queues those orders to sync again, up to 500 at a time. Each failed order row also has its own Retry button.

The order of work that saves the most time:

  • Read the message on a few failed rows. Failures usually come in groups with one cause.
  • Fix the cause. That might be a missing tax in Zoho, a required field on documents, or a disconnected account.
  • Select Retry all failed orders.

Retrying before fixing the cause just produces the same failures with a newer timestamp. Retrying after is safe for the reasons above: an order already in Zoho is brought up to date, not created again. Common causes and their fixes are listed in troubleshooting.

Skipped is not failed

Skipped rows worry people who do not need to worry. A skip means the app did what you told it to. The message names the rule: a payment status that is not in your filter, an order source you excluded, an order placed before your sync start date, an order with no customer when guest orders are set to be skipped, or an order that was cancelled before it synced.

The useful question to ask of a skipped order is whether the rule still reflects what you want. If you see paid web orders being skipped, a filter is tighter than you meant it to be. The filters are described in order settings.

A skipped order is not forgotten either. If it changes later so that it passes your filters, for example it gets paid, the update brings it into Zoho then.

Dry run rows

On the Backfill tab you can tick Dry run before starting. Each order is worked through with your current settings and the plan is written to Logs with the Dry run status: which documents would be created, which payments would be recorded, which credit notes would be raised. Nothing is created in Zoho.

It is the cheapest way to check a settings change. Run it over a week of orders, filter Logs to Dry run, and read what would happen. See backfilling historical orders for the full procedure.

Export CSV and deleting logs

Export CSV downloads the logs that match your current filters, newest first, up to 5,000 rows. Each row has the time, type, status, direction, the record ID, the Zoho ID, and the message. That is what an accountant or auditor usually wants: filter to orders for the month and hand over the file. Paired with a reconciliation report it answers both what is in Zoho and how it got there.

Delete logs clears history, for the current filters or for everything. It asks you to confirm first, and it has a safety built in: failed syncs are kept unless you have filtered to the Failed status yourself. Deleting logs changes nothing in Zoho or Shopify. It cannot be undone.

When the Zoho API limit is reached

Zoho caps how many API calls an organisation can make, per minute and per day, and the ceiling depends on your Zoho plan. A large backfill or a busy sale can reach it. Zoho uses the same error for both kinds of limit, and a daily limit can last for hours.

A connector that treats this as an ordinary error fails order after order until the limit lifts and leaves you with a wall of red. Zync treats it as a pause:

  • The moment Zoho refuses a call, your store is marked as paused until the time Zoho is expected to accept calls again.
  • A banner appears on every page of the app: Zoho API limit reached. Syncing is paused and resumes on its own in about N min; nothing is lost.
  • Orders that hit the limit are not failed. They are put back on the queue to run after the pause, spread out so they do not all hit Zoho in the same second.
  • If you have raised or reset your limit in Zoho, select Resume now on the banner and syncing starts again immediately.

The banner is there so that a quiet sync is not mistaken for a broken one. If nothing is arriving in Zoho and the banner is showing, the right action is usually none. If you reach the limit regularly, the guide to Zoho API limits covers how to reduce the load.

A five-minute weekly routine

  • Open Logs and look at Orders needing attention. Zero is the goal.
  • If it is not zero, read the reasons, fix the cause, and retry.
  • Glance at the Skipped count for the last 24 hours. A sudden jump means a filter or a setting changed.
  • Once a month, run Reconcile for the period and export the order logs for your records.

You can also sync straight from where you work. Zync adds Sync to Zoho actions to product, order, and customer pages in the Shopify admin, including bulk actions on the list pages, so fixing a single record does not require opening the app.

Next step

Open Logs now and filter Status to Failed. If the list is empty, you are done. If it is not, the message column tells you where to start. The full reference is in the logs guide, and the feature overview is on the sync logs page.

TopicsMonitoringSync LogsRetriesZoho API LimitsOrder SyncTroubleshooting
FAQ

Common questions

What happens when a sync to Zoho fails?
The job is retried automatically, up to three attempts with a growing wait between them. If the last attempt also fails, the Logs page shows one Failed row for that record with the reason, and you can retry it from there.
Is it safe to retry an order that partly synced?
Yes. Each step saves its progress on the Shopify order, and before creating anything Zync checks Zoho for a document, payment, or credit note that already carries the same reference. A retry continues where the last attempt stopped and does not create a second copy.
What does the Zoho API limit banner mean?
Zoho has told the app to slow down. Syncing for your store is paused and resumes on its own when the limit lifts. Orders that hit the limit are queued again to run later, so nothing is lost. If you have raised or reset your Zoho limit you can select Resume now.
What is the difference between Skipped and Failed?
Skipped means your settings held the record back on purpose, for example an order whose payment status is not in your filter. Failed means the sync was attempted and Zoho or Shopify rejected it. Only Failed rows need fixing.
Can I export the sync log?
Yes. Select Export CSV on the Logs page. The file contains the logs matching your current filters, newest first, up to 5,000 rows.
Does deleting logs remove anything from Zoho or Shopify?
No. Deleting logs only clears the history shown in the app. Failed syncs are kept unless you have filtered the page to the Failed status before deleting.

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.