Managing Rutter Connections

After a business 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 go to the configuration page in your dashboard.

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

If you try to fetch data from Rutter before the connection is ready, you will receive a PRODUCT_NOT_READY error.

Force Fetch

It is possible to send requests when a connection is not ready by setting the force_fetch=true query parameter in your requests to Rutter's Order and Transaction endpoints. At present, this feature only works for these two endpoints. Please keep in mind the returned data may be incomplete.

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 Data Batching 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 Data Batching

We allow prioritizing the initial sync of data so that a customer can get the most recent N months of data within a minimal period of time. Please reach out to support@rutterapi.com or the customer success manager to configure this.

For example, say a business has 24 months of historical data. A Rutter customer can first prefetch the most recent 6 months of orders and products, followed by the most recent 8 months of customers, and then the remaining 18 months of orders and products and the remaining 16 months of customers.

After these initial 24 months of orders, products, and customers have been synced, we start a continuous data sync every 10 minutes. We'll send PRODUCT_CREATED and PRODUCT_UPDATED as new product changes come in, as well as, ORDER_CREATED and ORDER_UPDATED for new orders.

In table form, the above scenario looks like this:

BatchData IncludedWebhook Fired
1Most recent 6 months of orders and productsINITIAL_UPDATE
2Most recent 8 months of customersHISTORICAL_UPDATE
3The remaining 18 months of orders and products and the remaining 16 months of customersHISTORICAL_UPDATE
N/AAny future orders/productsPRODUCT_CREATED, PRODUCT_UPDATED, ORDER_CREATED, ORDER_UPDATED

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 Unhealthy

Occasionally, connections may be marked as unhealthy if Rutter encounters transient errors, such as rate limits, when connecting with the merchant's data. In these cases, Rutter will automatically try to recover the connection and move it back to a healthy state. If the connection fails repeatedly, it will be marked as disabled.

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.