Shopify – NetSuite D2C implementation guide

A complete implementation guide for merchants and support teams deploying the Celigo Shopify – NetSuite Direct-to-Consumer integration template.

Just getting started? Start here

If you want basic order, customer, fulfillment, and inventory sync up and running, you only need a handful of flows. Follow sections in order: Prerequisites → Install → Initial Setup → Settings → enable the core flows. You can add payouts, returns, exchanges, and transfers later.

1. Prerequisites
2. Install
3. Initial Setup
4. Settings
5. Core Flows
6. Enable and Schedule

What this template does

The Shopify – NetSuite D2C template connects your Shopify storefront to NetSuite so that both systems share a single, accurate version of your business data. Orders placed on Shopify flow into NetSuite automatically. Inventory levels managed in NetSuite appear on your storefront in near real time. Fulfillments, refunds, returns, and cancellations update both systems without manual entry.

The template is built on Shopify's Admin GraphQL API and Celigo's native NetSuite adaptor. It ships as 32 pre-built flows that you install, configure, and enable — no custom development required for standard D2C operations.

What merchants gain

• Operations teams stop keying orders by hand. Every Shopify order lands in NetSuite within minutes.
• Customer service sees the same order data in both systems, with no reconciliation lag.
• Finance teams get a clean bank reconciliation: every Shopify Payments payout maps to the right NetSuite GL transaction.
• Merchandising manages the product catalog and pricing in NetSuite and publishes to Shopify automatically.
• Warehouse teams close the fulfillment loop: item fulfillments posted in NetSuite mark Shopify orders as shipped and send tracking emails to customers.

Who this guide is for

This guide is written for:

• Merchants and store owners who are setting up the integration themselves or overseeing an implementation.
• Support teams who need to understand how each flow works in order to diagnose issues and answer merchant questions.
• NetSuite administrators who are preparing NetSuite for the integration (bundle installation, roles, saved searches).

All 32 flows at a glance

The template ships with 32 flows grouped by function. All flows are disabled by default — you enable them in a specific order after completing setup. Section First-time enablement walks through the exact sequence.

Prerequisites

Complete every item in this section before installing the template. Skipping prerequisites is the single most common cause of errors on new installations.

NetSuite requirements

Shopify requirements

• A Shopify store with Admin API access. Basic Shopify plans include this; verify your plan supports API access if you are on a legacy plan.
• The store owner's login credentials — the store owner account is required to authorize the Celigo Shopify app during connection setup. This cannot be done with a staff account.

The OAuth authorization will request the following API scopes. All are required:

Celigo requirements

• An active Celigo integrator.io account with the Shopify – NetSuite connector license. Contact your Celigo account manager if you are unsure whether your subscription includes this connector.
• Only account owners in integrator.io can authorize the Shopify connection. Ensure the person performing setup has account owner permissions in Celigo.

Install the Template

Find the template in the Celigo marketplace

The template is available in two regional versions. Use the link that matches your Celigo account region:

Configure connections

During installation, Celigo will prompt you to configure two connections. Both must be fully authorized before any flow can run.

Shopify Store connection (OAuth 2.0)

This is the single Shopify connection used by all 32 flows — orders, products, inventory, fulfillments, returns, and payouts all use the same connection. It authenticates to your Shopify store via OAuth 2.0 using the Shopify Admin GraphQL API.

NetSuite connection (Token-Based Authentication)

Initial Setup

Before you enable any transactional flow, you must run three one-time setup flows in a specific order and complete two additional configuration steps. This section is the most important part of a new installation — getting it right prevents a category of hard-to-diagnose errors later.

Step 1 · Sync your Shopify store

The very first action after installation is to run the Shopify store to NetSuite custom record (add) flow. This creates a custom record in NetSuite that represents your Shopify store. Every other flow in the template references this record at runtime — if it does not exist, they will all error.

Step 2 · Select the store in Settings

After the store sync flow has created the NetSuite store record, you must return to the integration's Settings page and select that store from a dropdown. This selection tells the integration which store record to associate with all subsequent flows.

Step 3 · Sync markets

Run the Shopify markets to NetSuite (add) flow. This flow reads your Shopify Markets configuration (including currency and region settings) and creates corresponding records in NetSuite. These records are used by the order flow to assign the correct currency and tax treatment to each order.

Step 4 · Sync business entity

Run the Shopify business entity to NetSuite (add) flow. This flow syncs your Shopify business entity information — relevant for Shopify Payments multi-entity setups and legal entity separation. The payout flows depend on this record to correctly attribute deposits.

Step 5 · Build the item ID map

Run the Shopify products to item ID map (add or update) flow. This flow reads your Shopify product catalog and creates cross-reference records in NetSuite that map each Shopify product variant (by SKU) to its corresponding NetSuite item internal ID.

This mapping is the structural backbone of the integration. Every order flow, fulfillment flow, and inventory flow depends on these records to resolve Shopify line items into NetSuite item records. Without them, order imports will fail because NetSuite cannot identify which item is on each order line.

Step 6 · Set up discount items

If your store uses Shopify discounts (cart-level promotions, line-item markdowns, or both), you must complete this step before enabling the order flow. Skipping it means orders with discounts will error at import because NetSuite cannot resolve the discount item reference.

There are three actions to complete for each discount item you plan to use:

For cart-level discounts

For line-item discounts

Repeat the same three steps for line-level discounts: create a separate NetSuite discount item for line-level discounts, select it under Sync Shopify line-level discounts in Settings, and create a matching Item ID map record in NetSuite with the exact same item name.

Configure Settings

The integration's Settings page controls how data moves between Shopify and NetSuite. Most settings are configured once at go-live and rarely changed. This section explains each setting group, what each field does, and what happens if you leave it at its default.

Settings are grouped on the page as follows:

• Order settings
• Discount and tax settings
• Shipping and payment mappings
• Product and inventory settings
• Billing settings
• Payout settings

Each field in the Settings form is tagged with one of three labels:

Order settings

These settings control how Shopify orders are picked up and how they land in NetSuite.

Discount and tax settings

Tax settings have hard requirements because tax posting is critical to your GL. Discount settings are conditional — only relevant if you use discounts.

Shipping and payment mappings

Both mappings are conditional. They are only strictly necessary when you have more than one shipping method or payment gateway — but skipping them when multiple values exist means every order lands on the default and reports incorrectly downstream.

Product and inventory settings

These settings control how NetSuite catalog data and inventory levels are published to Shopify.

Billing settings

Billing settings are only relevant if you are using the auto-billing flow (Flow 20: NetSuite sales order to NetSuite invoice or cash sale). If auto-billing is not in scope for your implementation, leave these at their defaults.

Payout settings

These settings are required before enabling any of the three payout flows.

NetSuite saved searches

The template relies on 30 saved searches in NetSuite, all installed by the Shopify Connector bundle (81289). They are prefixed customsearch_celigo_shopify_ and are referenced by the integration at runtime.

Flows: Orders and Customers

This group contains six flows covering the full bidirectional order and customer lifecycle. For most merchants, the Shopify → NetSuite order flow and the two customer sync flows are the most critical flows in the entire integration.

What this flow does

On each scheduled run, the flow queries Shopify for orders that match your configured filter (new or updated since the last run). For each order, it:

1. Retrieves the customer's address history from Shopify.
2. Retrieves any order-level metafields.
3. Retrieves fulfillment order details (assigned warehouse locations, delivery methods) for each line item.
4. Creates or updates the customer record in NetSuite.
5. Routes the order to either a Cash Sale or Sales Order branch (see routing logic below).

Routing logic: Cash Sale vs. Sales Order

The flow uses first-matching-branch logic to decide the NetSuite record type:

What to configure

• Complete all six Initial Setup steps before enabling.
• Configure Order settings — especially the filter type and lag setting.
• Configure Discount and tax settings if your store uses discounts.
• Configure Shipping and payment mappings if you have multiple shipping methods or payment gateways.

What to check if orders are not syncing

See Orders not syncing in Troubleshooting.

---

What this flow does

Reads from the saved search customsearch_celigo_shopify_orderexpor_2, which filters for NetSuite sales orders that did not originate from Shopify (preventing echo loops). For each qualifying order, the flow creates an order record in Shopify with line items, pricing, customer reference, and transaction details.

When to enable this flow

Enable this flow only if your team enters sales orders directly in NetSuite that need to appear in Shopify. For stores where 100% of orders originate in Shopify, this flow can remain disabled.

---

What this flow does

Queries Shopify for customers created or updated since the last run. For each customer, looks up an existing NetSuite customer by email. If a match is found, the record is updated. If no match is found, a new customer is created. Address information, phone, and company details are included.

What to check if customers are not syncing

See Customer duplicates in Troubleshooting.

---

What this flow does

Reads the saved search customsearch_celigo_shopify_ctmr_crtn_pd for customers created or updated in NetSuite. For each customer, looks up whether a matching Shopify customer exists (by email). Routes to a Create branch or Update branch accordingly. After creation or update, also syncs customer metafield definitions and values from NetSuite attributes.

---

When to enable this flow

Enable this flow if your store uses a billing model where payment is authorized or captured at checkout but the NetSuite record is a Sales Order (not a Cash Sale) — for example, B2B customers on net terms, or stores where billing happens after fulfillment. The deposit record bridges the gap between Shopify's payment capture and NetSuite's invoice-based billing flow.

How it works

Reads the saved search customsearch_celigo_shopify_trans_to_ns for Shopify payment transactions tied to orders. Creates a Customer Deposit in NetSuite against the corresponding Sales Order. When the billing flow later creates an Invoice, it can apply this deposit to close the balance.

---

When to enable this flow

Enable this flow if your store accepts payment methods beyond standard credit cards and Shopify Payments — for example, gift cards, store credit, layaway payments, or custom integrations. If all your orders use a single standard payment method that maps cleanly to a NetSuite payment method, this flow can remain disabled.

Flows: Fulfillment

Fulfillment flows close the loop between your warehouse operations and your Shopify storefront. The NetSuite → Shopify direction is the most visible to customers: it triggers the "your order has shipped" email with tracking information. The Shopify → NetSuite direction is relevant when fulfillment is initiated in Shopify (for example, by a 3PL that uses Shopify as its order management interface).

What this flow does

Reads customsearch_celigo_shopify_fulfillments for new item fulfillments in NetSuite. For each fulfillment, checks the current Shopify order fulfillment status to prevent duplicates, retrieves the assigned fulfillment order IDs and locations from Shopify, then creates the fulfillment using the Shopify fulfillmentCreate GraphQL mutation. Tracking numbers, carrier names, and tracking URLs are included when available.

This flow supports:

• Multiple tracking numbers per shipment
• Split shipments (partial fulfillments on a single order)
• Carriers not natively recognized by Shopify (via tracking URL)

What to configure

• Ensure location mapping in Product and inventory settings is configured if you have multiple fulfillment locations.
• Set a 5-minute lag to allow tracking numbers to finalize on NetSuite fulfillment records before export. See Scheduling best practices.

---

When to enable this flow

Enable this flow if your fulfillment workflow starts in Shopify. If NetSuite is your warehouse management system and item fulfillments always originate in NetSuite, this flow can remain disabled — use the NS → Shopify direction only.

---

When to enable this flow

Enable this flow only if you process exchanges where the replacement item costs more than the returned item (upsell exchanges). The additional charge creates a fulfillment hold in Shopify until payment is captured. If you do not process exchanges, or your exchange flows never require additional payment, this flow can remain disabled.

Flows: Products and Inventory

This group manages your product catalog and inventory levels. NetSuite is the system of record for catalog data — prices, descriptions, images, and item attributes originate in NetSuite and sync to Shopify. For most merchants, these flows run on a longer interval (hourly or every few hours) since catalog changes are less time-sensitive than orders.

What syncs

• Product title and description
• Selling price and compare-at (MSRP) price from the configured NetSuite price levels
• Product images
• Metafields (if the metafields flow is also enabled)
• HS codes and country of origin
• Inventory tracking status (controlled by the Shopify Do Not Track Inventory field on the NetSuite variant)

After creating or updating the Shopify product, the flow writes the Shopify product and variant IDs back to the NetSuite Item ID map record.

Matrix items vs. simple items

Use this flow for items that have a parent-child matrix structure in NetSuite (for example, a T-shirt with size and color variants). For standalone items with no variants, use the simple items flow. Both flows can run simultaneously.

---

What syncs

Same fields as the matrix items flow (title, description, price, compare-at, images, HS codes, country of origin, inventory tracking status). After creating the Shopify product, the Shopify product ID is written back to the NetSuite Item ID map.

---

When to enable this flow

Enable this flow if you have product attributes stored in NetSuite that your Shopify theme displays using metafields. Common examples: fabric content, sizing guides, warranty information, regulatory certifications. If your product data only needs title, description, and price from NetSuite, this flow can remain disabled.

---

---

What this flow does

Reads per-item, per-location inventory quantities from NetSuite using the saved search. Updates Shopify inventory levels using the inventorySetQuantities GraphQL mutation. Supports:

• Simple items, matrix items, kit/assembly items, and item groups
• Multi-location inventory with 1:1 or many-to-1 location mapping
• Inventory aggregation across multiple NetSuite locations into a single Shopify location

What to configure

Set NetSuite locations to pick inventory from and Location mapping in Product and inventory settings if you have multiple warehouses or Shopify locations.

---

When to enable this flow

Enable this flow if you manage inventory across multiple warehouse or retail locations and use NetSuite Transfer Orders to move stock between them. Not relevant for single-location operations.

---

Flows: Billing

The billing flows handle the conversion of NetSuite Sales Orders into billed transactions and the corresponding update of Shopify order status. These flows are only relevant if your billing model creates invoices or cash sales in NetSuite after order entry — they are not needed if you always create Cash Sales directly from Shopify orders.

Routing logic

---

What this flow does

Reads invoices and cash sales from NetSuite that are linked to Shopify orders. For each billing record, retrieves the Shopify order total for validation, then marks the Shopify order as paid using the orderMarkAsPaid GraphQL mutation. Routes to an Invoice or Cash Sale branch based on the NetSuite record type.

Flows: Refunds

Refund flows handle money moving back to customers. Both directions exist: Shopify-initiated refunds (customer service refunds through Shopify admin) sync to NetSuite, and NetSuite-initiated refunds (credit memos created in the ERP) sync back to Shopify.

Routing logic

Saved searches used

• customsearch_celigo_shopify_bll_tp_exp — Identifies whether the original NetSuite transaction was an invoice or cash sale, determining which branch the router takes.
• customsearch_celigo_shopify_rfd_dp_exp — Finds the Customer Deposit for orders that were never billed (cancelled after payment, partially fulfilled).
• customsearch_celigo_shopify_rfnd_cm_amt — Returns the already-applied Credit Memo balance to prevent double-refunding on partial refunds.

---

Flows: Returns and Exchanges

This is the most complex flow group in the template, involving four interconnected flows that manage the full return and exchange lifecycle between Shopify's Returns API and NetSuite Return Authorizations (RMAs). These flows must be enabled together and in the correct order.

What this flow does

Finds orders with return requests in Shopify. For each return, retrieves: return line details (items, quantities, restocking fees, return shipping fees), any linked exchange order, the original NetSuite order lines for linkage, and returnable fulfillment records.

Creates an RMA in NetSuite linked to the original sales order. Also creates item receipt records and updates the cross-reference with the Shopify return ID. Separate RMAs are created for original orders and exchange orders. If no matching sales order is found in NetSuite, a standalone unverified RMA is created.

---

Routing logic

---

Routing logic

Uses all-matching-branches routing — both branches can execute on the same record:

---

Routing logic

Each branch creates the exchange order and updates related records: RMA links, credit memo status, and invoice status. The saved searches act as guard rails to ensure the exchange order is only created once and that the offsetting credit exists before proceeding.

Flows: Cancellations

Cancellation flows handle orders that are cancelled in either system, ensuring both Shopify and NetSuite reflect the cancelled state.

---

Flows: Payouts

The three payout flows together form a pipeline that reconciles Shopify Payments settlements against NetSuite GL transactions and creates bank deposit records. They must run in sequence and only after all transactional flows (orders, refunds, billing) have completed for a given period.

What this flow does

Queries the Shopify Payments API (through the same Shopify Store connection — no separate Payments connection is needed) for payouts matching the configured status filter. For each payout, retrieves individual payout transactions and associated fees, then creates a custom record in NetSuite capturing the payout summary.

---

Saved searches used

• customsearch_celigo_shopify_pay_for_reco — Exports payouts that need reconciliation.
• customsearch_celigo_shopify_pay_trans_re — Returns payout transaction detail for matching.
• customsearch_celigo_shopify_pay_ns_trans — Finds the matching NetSuite GL transactions (invoices, cash sales, credit memos, refunds) for each payout line. This is the search that closes the loop between Shopify Payments settlements and your NetSuite general ledger.

---

Enable Flows and Schedule

Enabling flows in the wrong order is the most common cause of errors on new installations. This section covers which flows depend on which, the recommended first-time enablement sequence, and how to set schedules and lag times for production operation.

Dependency order

Each flow depends on records created by earlier flows. This table shows what each flow requires before it can run successfully.

First-time enablement sequence

Follow this sequence when enabling flows for the first time on a new installation. Complete each group before moving to the next.

Scheduling best practices

Most flows filter source records by modification or creation timestamp. Each run, the flow asks: "What changed since the last time I ran?" A lag setting subtracts a small buffer from that timestamp so records have time to reach their final state before being picked up.

Troubleshooting

This section covers the most common issues across all flow groups. For each issue, the fastest path to diagnosis is to open the failing record in the Celigo flow dashboard, examine both the source payload and the error response, and identify which step failed (export, lookup, transformation, or import). Each stage has different root causes.

Orders not syncing

• Check the order's financial status. The order must match the status configured in Order settings (authorized, captured, or paid). An order in pending status will not sync unless Sync pending payment orders is enabled.
• Check the lag setting. If the lag is set to 15 minutes, an order placed 5 minutes ago will not be picked up on the current run — it will appear on the next run after the lag window clears.
• Check the delta timestamp. If the order was placed before the flow's current delta timestamp, it will not be picked up. This can happen after a flow is re-enabled following a pause. Reset the delta or adjust it to cover the missing window.
• Check for POS orders. If the order is a Shopify POS order and Sync POS orders as Sales Orders does not match the order's fulfillment status, the router may generate an error. Verify your POS setting matches your fulfillment workflow.
• Check for Item ID map gaps. If the order contains a line item with no matching NetSuite item (no Item ID map record), the import step will fail. Locate the failing SKU in the error log and create a map record for it.

Customer duplicate errors

• The customer import uses email as the matching key. If multiple NetSuite customer records share the same email address, the lookup returns ambiguous results and the import errors. Deduplicate customers in NetSuite before going live.
• Check subsidiary assignment. If your NetSuite account uses subsidiaries and the customer's subsidiary does not match the expected value, the import may fail or create a duplicate. Verify the subsidiary mapping in the customer import step.

Inventory not updating in Shopify

• Check that the item exists in the Item ID map. If a NetSuite item has no map record, the inventory sync cannot resolve it to a Shopify product and will skip it silently.
• Check location mapping. If the NetSuite location that holds the inventory is not included in the NetSuite locations to pick inventory from setting, its quantities will not be exported. Verify the location is included and that the location mapping in Settings correctly maps it to a Shopify location.
• Check inventory tracking status. If the Shopify product variant has tracked set to false (controlled by the Shopify Do Not Track Inventory field on the NetSuite variant), Shopify will not show or enforce inventory quantities. Verify the tracking flag on the NetSuite item.

Fulfillment errors

• Check that the Shopify order has open fulfillment orders. If the order is already fully fulfilled in Shopify, the fulfillmentCreate mutation will fail because there are no open fulfillment lines to fulfill.
• Check fulfillment order ID matching. The flow retrieves assigned fulfillment order IDs from Shopify to match against NetSuite line items. If a line item's location in NetSuite does not correspond to an assigned Shopify fulfillment location, the match fails. Verify location mapping between systems.
• Check carrier name format. Shopify recognizes a specific set of carrier names for tracking URL generation. If the NetSuite carrier name does not match a recognized Shopify carrier, ensure a tracking URL is provided directly — Shopify will display the URL even without a recognized carrier name.

Refund routing to wrong branch

• Verify the billing transaction type in NetSuite. The refund router reads the saved search customsearch_celigo_shopify_bll_tp_exp to determine whether to route to the Cash Sale or Invoice branch. Preview this saved search in NetSuite for the affected order and confirm it returns the expected record type.
• For deposit-based refunds: Confirm the Customer Deposit record exists in NetSuite and is linked to the order. If the deposit was created manually (not by the customer deposit flow), verify the cross-reference fields are correctly populated.
• For partial refunds: The flow checks the saved search customsearch_celigo_shopify_rfnd_cm_amt to find the already-applied Credit Memo amount. If a previous partial refund was processed outside the integration, the remaining balance calculation may be off. Verify Credit Memo application amounts in NetSuite match what the flow expects.

RMA not syncing

• Verify the original Sales Order exists in NetSuite with the Shopify order ID in the cross-reference field. The RMA creation flow looks up the original order by this ID. If the order sync flow failed or was disabled when the original order came through, the lookup will fail and an unverified standalone RMA will be created instead.
• Check Shopify return status. The pending RMA approval flow only fires when the Shopify return status is REQUESTED. If the return has already been moved to a different status in Shopify (manually by a staff member, for example), this flow will not pick it up.
• Check for item receipt. The received RMA processing flow depends on an Item Receipt being posted against the RMA in NetSuite. If no receipt exists, the flow will not trigger for that RMA.

Exchange order not creating

• Verify the Shopify return is marked as an exchange and that a linked exchange order exists with a legacy order ID. The exchange flow filters specifically for orders tagged as exchanges — returns without linked exchange orders are not processed by this flow.
• Verify the original order's NetSuite record type matches a router branch. The router checks whether the original order was a salesorder or cashsale. If the NetSuite record type field is not populated correctly on the original order, neither branch will match and the flow will error.
• Check the transformation hook. The exchange flow uses a postResponseMap hook on the "Get returns from Shopify" lookup step to map exchange line items. Open the failing record in the flow dashboard and examine the hook output for transformation errors.
• Check credit memo status. The saved search customsearch_celigo_shopify_credit_statu acts as a guard — if the Credit Memo for the return has not yet been created or applied, the exchange order creation will be blocked. Verify the credit memo exists and its status matches what the search returns.

Billing flow not triggering

• Check the auto-bill status setting. The saved search customsearch_celigo_shopify_orders_billi filters for Sales Orders in a specific status. Confirm the setting (Pending Billing vs. Pending Fulfillment) matches the actual status the Sales Order is in after the order flow creates it. Preview the saved search in NetSuite to confirm it returns the expected orders.
• Check payment terms on the customer record. The billing router uses the presence of a Terms field to decide Invoice vs. Cash Sale. A customer with no terms set will always route to the Cash Sale branch. If you expect an invoice, verify the NetSuite customer record has payment terms populated.

Payout reconciliation variances

• A small number of variances is expected and normal. Shopify Payments fees, dispute fees, and minor rounding differences will always produce some variance. Investigate when the variance per payout exceeds a threshold you define for your business (for example, $50).
• Check the payout lag setting. If the lag is too short, the reconciliation flow may run before some transactions (especially refunds processed close to payout close) have reached NetSuite. A 24-hour lag is a safe starting point for most stores.
• Check for unsynced fees and disputes. Shopify Payments fees and dispute adjustments that posted to the payout but are not yet mapped to NetSuite GL transactions will appear as variances. Verify that the GL account mappings in payout settings cover all fee types you receive.
• Verify refund mapping. Refunds posting to the payout period must be matched to the correct Customer Refund or Credit Memo in NetSuite. If the refund flow has not run or created the correct record type, the payout reconciliation will show a variance for that line.

OAuth token expirations

• Shopify OAuth tokens can expire or become invalidated after a store-owner password change, an app uninstall/reinstall, or a change to the app's API scopes. When this happens, every flow using the Shopify connection will fail with an authentication error.
• Only the account owner in Celigo can reauthorize the Shopify connection. Ensure the person who has store owner access to both Shopify and the Celigo account owner role is available to reauthorize quickly if this occurs. Include this in your operations runbook.
• NetSuite TBA tokens do not expire automatically but should be rotated on a regular cadence (every 90–180 days is standard for security compliance). Schedule token rotation as a recurring maintenance task.
• Set connection failure alerts in Celigo. A connection outage cascades into errors across most flows simultaneously — it is distinctive and easy to diagnose if you have alerting in place, but disruptive if discovered manually hours later.

GraphQL rate limits and throttling

• Shopify's GraphQL API uses a leaky-bucket rate limit. Flows that process large batches of records with expensive queries will consume the bucket faster and trigger throttling before the batch completes.
• If flows report THROTTLED errors: Reduce the page size on the export step (fetch fewer records per API call) and spread the workload by setting a longer schedule interval. This is a trade-off between throughput and reliability — during peak periods you may need to accept longer sync delays.
• For inventory sync at scale: Use the inventorySetQuantities mutation with batches of 100–250 items per call rather than one item per call. Large catalogs syncing one SKU at a time will consistently throttle.
• Monitor query cost in logs. If your Celigo plan exposes the full GraphQL response, watch the extensions.cost.requestedQueryCost field. High values indicate queries that can be pruned by removing unnecessary fields from the selection set.

General debugging approach

When a flow is producing errors and the cause is not immediately obvious:

1. Find the failing record. In the Celigo flow dashboard, open the flow run that contains the error and locate the specific record(s) that failed. Each failed record has a detailed error log.
2. Identify the failing step. Errors at export, lookup, transformation, and import have different signatures. Export failures usually indicate a connection or query issue. Lookup failures indicate a missing or non-matching record in the target system. Transformation failures indicate a mapping or scripting error. Import failures indicate a payload or permissions issue.
3. For lookup failures: Find the saved search referenced by the failing lookup step (see NetSuite saved searches). Preview that search in NetSuite with the same filter values the flow used. If the search returns no results, the problem is the underlying data — the record does not exist or does not match the expected criteria.
4. For transformation failures: Check any handlebars expressions in the mapping for typos, missing field references, or fields that are null in the source payload. The flow dashboard shows the source payload for each failing record — use it to verify which fields are actually populated.
5. For import failures: Copy the generated payload from the flow error log and test it directly — against the NetSuite REST interface or the Shopify GraphiQL Explorer. This isolates whether the issue is the payload content, an API permission, or something in the integration platform itself.
6. Fix before retrying in bulk. Retrying records against an unresolved root cause generates noise in your error logs and can create partial records. Resolve the underlying issue first (fix the mapping, fill the missing data, correct the setting), then retry.