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
You can configure Rutter to fetch initial data for a connection in batches. This enables you to prioritize fetching the most important data for your use case and start using your Rutter connections as soon as possible, while populating additional data in the background over a longer window of time.
To configure initial sync batches, click "edit" on the Data Sync Configuration page, then "+ Add Batch" under the Initial Sync section.
For example, say a business has 24 months of historical data. A Rutter customer has a product that requires expenses and invoices. This customer might configure their data sync in 3 batches. Their first batch would fetch the most recent 6 months of expenses. As soon as that first batch completes its initial sync, the connection will be ready to use. Meanwhile, their second batch will fetch the most recent 6 months of invoices. After that completes, a third batch will sync the remaining 18 months of expenses and invoices.
After these initial 24 months of data have been synced, Rutter begins running a continuous data sync every 60 minutes. We'll send Entity Created and Entity Updated as new changes come in.
In table form, the above scenario looks like this:
| Batch | Data Included | Webhook Fired |
|---|---|---|
| 1 | Most recent 6 months of expenses | INITIAL_UPDATE |
| 2 | Most recent 6 months of invoices | HISTORICAL_UPDATE |
| 3 | The remaining 18 months of expenses and invoices | HISTORICAL_UPDATE |
| N/A | Any future expenses and invoices | EXPENSE_CREATED, EXPENSE_UPDATED, INVOICE_CREATED, INVOICE_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.