What should I check first when Shopify Odoo sync fails?

Start with the failed job record. Identify the workflow, Shopify reference, Odoo model or error, queue status, and whether the failure is transient, configuration-related, permission-related, or data-related.

Is it safe to retry a failed Shopify Odoo sync job?

It is safe only if the connector uses idempotent writes and stable Shopify-to-Odoo identifiers. Fix configuration or data errors first, then retry through the queue instead of creating records manually.

What causes most Shopify Odoo sync failures?

Common causes are missing product links, unmapped taxes, warehouse mapping gaps, Odoo access rights, company context errors, expired credentials, rate limits, duplicate webhook delivery, and partial records from interrupted writes.

When should a failed job not be retried immediately?

Do not retry immediately when the failure is caused by missing tax mapping, wrong warehouse mapping, missing product identity, Odoo permission issues, or invalid company context. Fix the root cause first.

Shopify Odoo Failed Sync Root-Cause Playbook

Failed sync jobs are data, not just errors

A failed Shopify Odoo sync job is not only a problem to clear. It is evidence about the integration. The failure tells the team which workflow broke, which record was affected, which system rejected the operation, and whether the underlying cause is transient or structural.

Treating every failed job as "retry it and hope" creates duplicate records, partial orders, wrong stock, and accounting cleanup. Treating failed jobs as root-cause data lets operations fix the mapping, access, or product issue that caused the failure.

This playbook supports the Shopify Odoo sync errors, orders not showing in Odoo, inventory mismatch, and retry failed jobs content cluster. Use it when a Shopify order, product, inventory update, refund, fulfillment event, or customer record does not sync cleanly into Odoo.

Step 1: identify the workflow

Do not start by asking whether "sync is down." Start by identifying which workflow failed.

Classify the failed job as one of these:

Order sync.
Product sync.
Customer sync.
Inventory sync.
Refund sync.
Fulfillment sync.
Historical import.
Scheduled sync.
Image or media sync.
Credential or connection test.

This matters because each workflow has different root causes. An image sync failure rarely affects finance. A refund sync failure can. A product sync failure may explain an order failure. An inventory failure may be a location mapping issue rather than a product issue.

The job should show the Shopify reference where possible: order number, product ID, variant ID, customer ID, inventory item, fulfillment ID, or refund ID. If the connector does not show the affected record, troubleshooting becomes guesswork.

Step 2: separate transient failures from configuration failures

Some failures are temporary. Others will fail forever until the setup changes.

Transient failures include:

Shopify API throttling.
Odoo rate limits.
Network timeouts.
Short Odoo downtime.
Temporary Shopify API errors.

These can usually retry with backoff.

Configuration failures include:

Missing tax mapping.
Missing warehouse mapping.
Product not linked to Odoo.
Odoo user lacks access rights.
Wrong company context.
Invalid Odoo field mapping.
Missing Odoo service product for fees or tips.

These should not be retried blindly. The retry will probably fail again or create partial state. Fix the mapping or access issue first, then retry through the queue.

Data failures include:

Missing SKU or barcode.
Invalid address country or state.
Customer email mismatch.
Product variant shape mismatch.
Refund referencing a line that did not sync cleanly.

These require record correction or an explicit fallback rule.

Step 3: inspect the Shopify source record

The Shopify record is the source for many workflows. Open the source record and check the fields the job needed.

For order failures, check:

Order number.
Financial status.
Customer and address.
Line items and variant IDs.
Discounts.
Taxes.
Shipping, duties, tips, and additional fees.
Refunds or edits.
Fulfillment status.

For product failures, check:

Product status.
Variants.
SKUs and barcodes.
Options.
Images.
Metafields.
Existing Odoo ID metafield if used.

For inventory failures, check:

Shopify location.
Inventory item ID.
Variant product link.
Whether the location is active.

The goal is to learn whether Shopify sent a record the connector was configured to handle. If the source record has missing or unexpected data, fix the data or adjust the connector rule before retrying.

Step 4: inspect the Odoo target context

Odoo failures often come from context, not the raw record. The same payload may succeed in one company and fail in another.

Check:

Odoo database and version.
Selected Odoo company.
User access rights.
Allowed companies.
Target model, such as sale.order, account.move, product.product, res.partner, or stock.quant.
Warehouse or location.
Tax records.
Fiscal position.
Product existence.
Custom field existence and type.

If the job failed with an Odoo error, read it literally. Odoo errors often point to missing access, invalid fields, missing required values, or company restrictions. Do not hide that information behind "sync failed." The exact Odoo response is the fastest path to root cause.

Order failure root causes

Order sync failures usually come from product identity, taxes, customers, payment rules, record type, or Odoo access.

Common order root causes:

One Shopify line item is not linked to an Odoo product.
Product search-and-create is disabled or cannot find a match.
Shopify tax line has no Odoo tax mapping.
Odoo record type is misconfigured for the current order.
The customer cannot be matched or created.
Country or state mapping fails for the address.
The integration user cannot create the target Odoo record.
The order is unpaid and paid-only sync is enabled.
A partial record exists from a previous interrupted write.

Before retrying, decide whether the cause is data, mapping, or transient. A missing tax mapping will not become valid after five retries. A timeout might.

Inventory failure root causes

Inventory failures usually come from product links, location mapping, inventory direction, or permissions.

Common inventory root causes:

Shopify variant is not linked to the Odoo product.
Shopify location is not mapped to an Odoo warehouse.
Odoo warehouse belongs to a different company.
Inventory direction excludes the event.
Odoo user cannot read or write stock records.
Shopify inventory item or location is inactive.
A buffer or reservation rule creates an unexpected quantity.
The inventory job is delayed behind a burst of updates.

Inventory retries should be handled carefully. If the product link or location mapping is wrong, a retry will not help. If the failure is a rate limit, retry with backoff is appropriate.

Product failure root causes

Product sync failures often happen before launch or during catalog expansion.

Common product root causes:

Missing SKU or barcode for the configured match rule.
Variant option shape does not map cleanly to Odoo attributes.
Odoo custom field mapping points to a missing field.
Metafield value type does not match the Odoo target field.
Image upload fails separately from product identity sync.
Odoo version-specific product fields differ from the connector's write path.
Existing Odoo product has conflicting variant structure.

Product failures should be solved before broad order sync. If orders start before product identity is stable, order jobs will fail or create records the catalog team later has to clean.

Related pages: product matching, attribute sync, and metafield sync.

Refund and fulfillment failure root causes

Refund failures usually depend on the original order. Fulfillment failures usually depend on delivery state and direction.

Refund root causes:

Original order did not sync successfully.
Refund references a line that is not linked in Odoo.
Tax mapping for reversal is missing.
Retry would duplicate a refund without idempotent reference checks.
Odoo record state does not allow the expected reversal.

Fulfillment root causes:

Fulfillment direction is configured differently than expected.
Odoo delivery or picking cannot be found.
Shopify fulfillment location is not mapped.
Tracking data is missing or malformed.
Partial fulfillment line mapping is incomplete.
Duplicate fulfillment event was delivered.

For both workflows, retries should use the queue. Manual fixes can be necessary, but manual creation should not bypass identifiers if the connector later retries the same event.

Safe retry rules

Use these retry rules:

Retry transient failures after backoff.
Fix configuration failures before retrying.
Fix source data failures before retrying.
Do not manually create the Odoo record and then retry unless the connector can recognize the manual record.
Search for existing Odoo records by Shopify reference before assuming the job did nothing.
Retry through the connector queue so idempotency logic runs.

The safest retry path preserves the Shopify reference. If a partial Odoo record exists, the connector should complete or skip based on stable identifiers. If that behavior is not available, manual intervention needs a clear note to prevent duplicate work later.

Root-cause categories to track

Track failures by category over time:

Product identity.
Tax mapping.
Warehouse mapping.
Odoo access.
Company context.
Shopify API limit.
Odoo rate limit.
Credential expiry.
Address mapping.
Refund state.
Fulfillment state.

This turns support work into implementation improvement. If tax mapping causes repeated failures, the tax setup needs work. If product identity causes repeated order failures, product matching needs work. If rate limits are common, queue concurrency or job volume may need adjustment.

The goal is not zero failures. The goal is fewer repeated failures and faster recovery when a new edge case appears.

The one-page triage checklist

When a job fails, answer these questions:

Which workflow failed?
Which Shopify record is affected?
Which Odoo model or record is affected?
Is the failure transient, configuration-related, permission-related, or data-related?
Is there an existing partial Odoo record?
Does the job have a stable Shopify reference?
What setting or source data must be fixed before retry?
Is it safe to retry through the queue?
Should this root cause become a launch checklist item?

This checklist keeps the team from jumping straight to manual fixes. It also creates a trail for future incidents.

Where Synco fits

Synco Connector is built around queue-based, retry-safe processing. Jobs keep Shopify context, external operations run outside storefront requests, and failed jobs remain visible for review and retry. That does not eliminate every integration error. It makes errors recoverable.

Use this playbook with the Shopify Odoo go-live checklist and month-end close checklist. Together they cover launch readiness, operational recovery, and finance trust.