Connection Lifecycle

After a merchant connects their platform with you, a new Connection is created. Each connection created in Rutter goes through the same stages:

Initial Sync

The Initial Sync stage represents when a connection is first made and Rutter attempts to sync data for the first time.

As soon as the connection is established, Rutter pulls data from all available endpoints (based on allowed scopes). Depending on the size of the connection (e.g. a merchant with 10 products vs. a merchant with 1 million products), this might finish instantly or in a few hours. Rutter optimizes fetching for each platform based on the maximum rate-limit. If you need a subset of data as quickly as possible or if you want to increase the initial synchronization speed, please see the Configuring a Speedup section below.

If you try to fetch data from Rutter at this stage, you will receive a PRODUCT_NOT_READY error.

When the connection is ready, you will receive a INITIAL_UPDATE webhook.

Historical Sync

The Historical Sync stage represents the stage after the Initial Sync is finished and Rutter attempts to sync the remaining batches of historical data for a connection.

By default, the initial download attempts to synchronize all historical data for a merchant so you have full access to the data once the INITIAL_UPDATE webhook is fired. In this case, you can ignore this stage.

It is possible to receive multiple webhooks if you have configured Rutter to prioritize other pieces of data. Please see the Configuring a Speedup section below.

Ongoing Data Synchronization

After the initial & historical synchronization is finished, Rutter subscribes to all available webhooks and regularly polls the merchant's platform to keep data synchronized. At this point, you will receive webhooks for all updates to the data, for example Order Webhooks.

Configuring a Speedup

We allow prefetching of data so that a customer can get the most recent N months of products or orders within a minimal period of time. Please reach out to [email protected] or the customer success manager to configure this.

For example, say we have 100 orders and 100 products uniformly distributed over the past 10 months. A customer can first prefetch the last month of 10 orders and the last month of 10 products. Next, a full refresh runs for the rest of the 90 orders and 90 products.

After these initial 100 orders and products have been sent, we start a continuous data sync every 10 minutes, sending PRODUCT_CREATED/PRODUCT_UPDATED and ORDER_CREATED/ORDER_UPDATED webhooks as new orders and products changes come in.

In table form, the above scenario looks like this:


Data Included

Webhook Fired


Most recent 10 orders



Most recent 10 products



The remaining 90 orders and 90 products



Any future orders/products


Connection Needs Update

If a merchant pauses the connection by uninstalling your application from their system, Rutter will fire a CONNECTION_NEEDS_UPDATE webhook. This means that Rutter can no longer synchronize the data and you will need to ask the merchant to reconnect their platform.

Once the merchant reconnects their platform, you will receive a CONNECTION_UPDATED webhook.

Connection Disabled

Disconnections can happen if a merchant shuts down their store or ends their subscription with the platform. In these cases, Rutter can no longer connect with the merchant's data, and you will receive a CONNECTION_DISABLED webhook and you may need to ask the merchant to reconnect or resolve the issue. To understand why a connection is disabled, you can use Fetch a Connection Status to see a list of standardized reasons.

Once the merchant reconnects their platform, you will receive a CONNECTION_UPDATED webhook.