Syncing 

The syncing system for the Shopify Connection works by leveraging actions. Each time Gadget goes to sync the connected shop, Gadget creates a new shopifySync record and dispatches the run and either the complete or error actions based on the outcome of the sync.

There are two types of syncs for the Shopify connection: API-triggered or manual.

API-triggered Syncs 

An API-triggered sync can be initiated via the API Playground, JS clients, or the api object in any action or route code. There are many ways that you can use API-triggered syncs. The three main ways are after a shop installation, on a model's action, and syncing data within a specified date range.

Sync on shop install 

It may be necessary to run an initial sync upon installation. For example, you may want to display all products on a user interface immediately after a merchant installs your app. To do this, use the onSuccess function on the Shopify Shop model's install action with the following code:

Sync by model 

You can optionally pass a models parameter to the runSync call to specify which particular Shopify models to sync. For example, if you wish to sync all products in your backend, but not orders, the models should be passed as an array of model API identifiers. If the models parameter is omitted or is an empty array, all Shopify models will be synced.

Sync by date-time 

You may want to limit syncing to recent records. To do this, you can pass the syncSince parameter to indicate which records Gadget should sync. Without this parameter, the API-triggered sync will copy every record to Gadget, regardless of when it was created or updated.

By default, Gadget will check the shopifyUpdatedAt field for each Shopify record, and only sync records created or updated within the specified window.

The timestamp used to sync records can be configured using syncSinceBy:

• syncSinceBy: "updated_at": Use shopifyUpdatedAt to sync records updated in the syncSince time window (default).
• syncSinceBy: "created_at": Use shopifyCreatedAt to sync records created in the syncSince time window.

You can also sync the most recently created records with syncSinceBy: "created_at":

Sync by count 

You can limit the number of records synced with the syncLast parameter. This will sync only the most recent N records, which is useful when you only need a subset of the latest data rather than all records.

By default, records are ordered by the updated_at timestamp coming from Shopify (the shopifyUpdatedAt field in Gadget), but you can control this with the syncLastBy parameter:

• syncLastBy: "updated_at": Use shopifyUpdatedAt to sort records by last updated (default).
• syncLastBy: "created_at": Use shopifyCreatedAt to sort records by created date.

You can also sync the most recently created records with syncLastBy: "created_at":

Sync by count and date-time 

You can combine syncLast with syncSince to get the most recent N records within a specific date range:

Forced syncs 

A sync will not update any fields or run any actions if the shopifyUpdatedAt value in the payload is less than or equal to the shopifyUpdatedAt value currently stored on the record. There are certain situations, such as Shopify API version upgrades, where you may want to backfill new values or re-run your actions on existing records. In these situations, you can run a sync with the force field set to true. A forced sync will update all values and re-run all actions on applicable records.

You can run a forced sync on an individual store by calling the runSync function on the shopifySync model:

The globalShopifySync API can be used to force a sync across multiple stores.

Manual syncs 

A sync will be queued (without a syncSince set) when clicking the "Sync" button found on the Installs page. This will make a call to the shopifySync model's run Action. The install page can be found via the left nav bar or by navigating to Settings -> Plugins -> Shopify.

This sync may take some time to complete, depending on how much data the shop has.

Sync-only models 

When adding a Shopify Connection, you may have opted to connect to Shopify models that do not offer webhooks. Gadget refers to these as sync-only models, meaning that they can only be kept up to date by running a sync on a schedule.

When you add one or more sync-only models to your Gadget database, Gadget will also add a global action, api/actions/scheduledShopifySync.js, that runs once per day to fetch and save data for those models. You can customize this action's schedule by altering its trigger and change how it behaves by editing the code.

For more information on models that are currently sync only refer to our available Shopify models for details here

Sync-only fields 

A small number of fields on Shopify models are also sync-only. This means that they are not created or updated on webhooks, but are set only during a sync. To handle changes to these fields you can detect the trigger type in your onSuccess function by checking the trigger property in the action context.

For models that support webhooks, sync-only fields will initially be null when a record is first created via a webhook. These fields are populated during the nightly reconciliation sync process.

If you need these fields to be populated immediately you should fetch the data yourself using the Shopify API and update the record manually.

To detect changes in sync-only fields and perform actions based on those changes, use the record.changed() method in your action code. For example:

The current list of sync only fields are:

scheduledShopifySync global action 

If you add any sync-only models to your Shopify connection, Gadget will automatically place a global action called scheduledShopifySync in your project's global actions folder.

This action allows you to control how the scheduled sync is run.

It calls on the globalShopifySync function to run the sync process. This function takes in the following parameters for the sync:

• apiKeys: the list of Shopify APP API keys to trigger a sync for
• syncSince: the start date to start syncing data from, by default: In the action code we create a new Date object representing a specific point in time, const syncSince = new Date(Date.now() - 25 * HourInMs) sets syncSince to a Date object that represents the time exactly 25 hours before the current time. The reason we've set the start of the sync to 25 hours before the current time is as a best practice to leave additional leeway time to avoid any possible errors there might be in the exact timing of the sync.
• syncSinceBy: whether to use "created_at" or "updated_at" as a time window when using syncSince (optional, defaults to "updated_at")
• syncLast: the maximum number of records to sync per model (optional)
• syncLastBy: whether to order by "created_at" or "updated_at" when using syncLast (optional, defaults to "updated_at")
• models: the list of model API identifiers to trigger syncs for, by default: We create a syncOnlyModels object that maps through an array of the existing available models with the Shopify connection and filter through identifying for sync-only models

You can also edit the rest of the action to configure it to your preference, by default the action is scheduled to run daily but you can configure the time it's run, head to the scheduler trigger associated with the action and set a time interval of your preference, like below:

If you also want to configure and add additional models to be synced with the sync-only models, you can do so by adding your custom preference in the models param as an array like below:

To remove a sync-only model from being included in the scheduled sync, head to Settings -> Plugins -> Shopify and click the Edit button to edit your API scopes and simply unselect the model.

Filtering syncs 

Gadget supports filtering which records are synced when you run a sync by only these parameters:

• syncSince to sync data changed since a specific date
• syncSinceBy to control whether syncSince uses "created_at" or "updated_at"
• syncLast to sync only the most recent N records per model
• syncLastBy to control whether syncLast orders by "created_at" or "updated_at"
• models to sync only specific set of models
• apiKeys to sync data for only specific Shopify apps in your Gadget app

Filtering by other parameters is not supported, but you can always modify your model actions to return without saving, or modify the parameters before saving to adjust what data is synced.

Syncs and webhook filters 

When a sync is run, it syncs all the enabled fields for the models you have selected, and all rows in the models you have selected. Webhook filters or the includeFields option that apply to webhooks will have no effect on the sync.

Sync error handling 

If an error occurs during a sync, the Shopify Sync model's Error action will be called. For example, here's how you teach Gadget to alert you via SMS when a sync fails.

• id is the Shopify Sync id that was created
• errorMessage contains a generate description of the error or errors
• errorDetails contains a all error messages (if more than 1 occurred) joined by a \n

The best way to debug why a sync may have failed is to search for errors through your logs. Use the following log query to filter by sync ID (replace {syncId} with ID of the sync that has failed):

Abort a running sync 

If you've accidentally synced the wrong model or perhaps have a long ongoing sync, you do have the ability to abort a running sync.

1. During an ongoing sync, head over to your shopifySync model.

2. Select the abort action and then click Run Action

3. Then invoke your action within the GraphQL playground, and once ran, your sync is then successfully aborted

Adding the abort action to older shopifySync models 

1. To add the abort action, head to your shopifySync model and create a new action called abort

2. Then paste the following code within the abort action code file

3. Now that you've successfully added the action you can abort a running sync and can follow the steps above to do so.