Connection Lifecycle

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 see the Configuring a Speedup section below.

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 orders and transactions 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 prefetching of data so that a customer can get the most recent N months of products, orders, or customers within a minimal period of time. Please reach out to [email protected] 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 webhooks as new product changes come in, as well as, ORDER_CREATED and ORDER_UPDATED webhooks 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 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.


What’s Next