Connections
The Connection Object
The Connections endpoints are used to manage Connections, which are the individual storefronts, payment processors, or accounting systems that businesses have shared with you. You can use these endpoints to create a new connection manually and send an authentication link directly to a merchant, or get access to the raw credentials for a specific platform (Shopify, WooCommerce, Quickbooks Online, etc.).
To understand the lifecycle of a Connection and the important events that occur when a merchant connects/disconnects their platform, see Connection Lifecycle.
Properties
id
stringRequiredThe UUID of the connection. Generated by Rutter.
orgId
stringRequiredYour organization id.
platform
enumRequiredThe underlying platform.
Create a Connection
Create connections programmatically using the Create a Connection API. There are two ways to use this API:
- Create a connection that allows the merchant to select which platform they want to connect. This is done by leaving the request body empty.
- Create a connection with existing credentials. This is done by specifying the platform and including the associated credentials (OAuth, Basic Auth, etc.) for the connection. Rutter will use these fields to make the authenticated API requests to the platform. To see what values are required for each platform, see the Platform Specific Required Body Params table below or contact support@rutterapi.com for more support.
Connection URL
One of the returned fields in the connection object from the Create a Connection endpoint is the link_url
, which is a unique, stable link that you can send to a business for Business Authentication.
The link_url
points to the Rutter Link web app, which handles the authentication flow for each Ecommerce platform. Once the merchant completes the Link authentication flow, a CONNECTION_UPDATED event will be fired to your Webhook URL, and you will be able to fetch data for their store through this Connection.
There are a few query parameters that you can specify to a connection URL to customize the authentication experience. Here are some examples:
Loads the authentication flow directly to the Wix-specific step: https://link.rutterapi.com/connection/123?platform=wix
Loads the authentication flow directly to the Wix-specific step and on completion the merchant will be redirected to Google: https://link.rutterapi.com/connection/123?platform=wix&redirect_url=https%3A%2F%2Fwww.google.com
Query Param | Example Value | Description |
---|---|---|
platform | SHOPIFY | If platform is specified, the Rutter Link flow will start directly at the authentication process for the specified platform, skipping the screen for choosing the platform. See Supported Platforms for the respective ENUM values. |
redirect_url | https://www.google.com?q=customparameter | If redirect_url is specified, the merchant will be redirected to the URL specified, and a public_token query parameter for the connection will be added to this url. If the value is https://www.google.com?q=customparameter , the final URL will be https://www.google.com?q=customparameter&public_token=PUBLIC_TOKEN |
shopifystore | example | if shopifyStore is specified, the Shopify authentication screen will be pre-filled with the store URL. If the value is example , Rutter Link will show example.myshopify.com |
Request Body
All of:
platform
enumRequiredThe underlying platform.
scope
stringAny of:
Credentials for BigCommerce
oauth_client_id
stringBigCommerce App Client ID
oauth_access_token
stringRequiredBigCommerce Store Access Token
store_url
stringRequiredBigCommerce merchant .mybigcommerce.com domain URL
oauth_client_secret
stringBigCommerce App Client Secret
Credentials for Amazon
amazon_access_key_id
stringRequiredAWS User Access Key ID
oauth_client_id
stringRequiredSP-API App Client ID
amazon_secret_access_key
stringRequiredAWS User Secret Access Key
amazon_seller_region
enumRequiredRegion of Amazon seller - must be one of na (North America), eu (Europe), or fe (Far East).
amazon_selling_partner_role
stringRequiredAWS Role ARN used in SP-API app
oauth_client_secret
stringRequiredSP-API App Client Secret
oauth_refresh_token
stringRequiredSP-API Refresh Token
Any of:
Credentials for Shopify Private App
basic_password
stringRequiredPrivate Shopify App Password
basic_username
stringRequiredPrivate Shopify App API Key
store_url
stringRequiredShopify merchant .myshopify.com domain URL
Credentials for Shopify Public App
oauth_client_id
stringRequiredShopify Public App Client ID
oauth_access_token
stringRequiredShopify Merchant Access Token
oauth_client_secret
stringRequiredShopify Public App Client Secret
store_url
stringRequiredShopify merchant .myshopify.com domain URL
Credentials for PrestaShop
api_key
stringRequiredPrestaShop API Key
store_url
stringRequiredPrestaShop merchant domain URL
Credentials for Shoper
oauth_access_token
stringRequiredShoper merchant OAuth Access Token
oauth_refresh_token
stringRequiredShoper merchant OAuth Refresh Token
store_url
stringRequiredShoper merchant domain URL
Credentials for WooCommerce
basic_password
stringRequiredWooCommerce Rest API Consumer Secret
basic_username
stringRequiredWooCommerce Rest API Consumer Key
store_url
stringRequiredWooCommerce merchant website URL
Credentials for Magento
basic_password
stringRequiredMagento Admin User Password
basic_username
stringRequiredMagento Admin User Username
store_url
stringRequiredMagento merchant website URL
Credentials for eBay
oauth_client_id
stringRequiredEbay Developer OAuth Client ID
oauth_client_secret
stringRequiredEbay Developer OAuth Client Secret
oauth_refresh_token
stringRequiredEbay OAuth Refresh Token
Credentials for Lazada
oauth_client_id
stringRequiredOAuth Client ID
country
stringRequiredCountry Code for Merchant (e.g. id, sg, th)
oauth_access_token
stringRequiredOAuth Access Token
oauth_client_secret
stringRequiredOAuth Client Secret
oauth_refresh_token
stringRequiredOAuth Refresh Token
Credentials for Fnac
partner_id
stringRequiredPartner ID
shop_id
stringRequiredShop ID
key
stringRequiredKey
Credentials for Square
oauth_client_id
stringRequiredSquare Developer OAuth Client ID
oauth_client_secret
stringRequiredSquare Developer OAuth Client Secret
oauth_refresh_token
stringRequiredSquare OAuth Refresh Token
Credentials for Stripe
account_id
stringRequiredStripe Account ID
oauth_access_token
stringRequiredStripe OAuth Access Token
Credentials for Quickbooks
oauth_client_id
stringRequiredOAuth Client ID
realm_id
stringRequiredRealm ID
oauth_client_secret
stringRequiredOAuth Client Secret
oauth_refresh_token
stringRequiredOAuth Refresh Token
environment
stringEnvironment (e.g. sandbox)
Credentials for Netsuite
token_id
stringRequiredToken ID
consumer_key
stringRequiredConsumer Key
consumer_secret
stringRequiredConsumer Secret
store_name
stringRequiredStore Name (for sandbox you should put it in the form '1000000_SB1')
token_secret
stringRequiredToken Secret
Credentials for Walmart
oauth_client_id
stringRequiredWalmart Developer OAuth Client ID
oauth_client_secret
stringRequiredWalmart Developer OAuth Client Secret
Credentials for Xero
oauth_client_id
stringRequiredOAuth Client ID
tenant_id
stringRequiredThe Xero Tenant ID
user_id
stringRequiredThe Xero User ID
oauth_client_secret
stringRequiredOAuth Client Secret
oauth_refresh_token
stringRequiredOAuth Refresh Token
Response Body
connection
objectRequiredconnection
attributes1{
2 "platform": "SHOPIFY",
3 "oauth_client_id": "CLIENT_ID",
4 "oauth_access_token": "ACCESS_TOKEN",
5 "store_url": "shopifystore.myshopify.com",
6 "oauth_client_secret": "CLIENT_SECRET"
7}
1{
2 "connection": {
3 "id": "00000000-0000-0000-0000-000000000000",
4 "access_token": "00000000-0000-0000-0000-000000000000",
5 "link_url": "https://link.rutterapi.com/connection/00000000-0000-0000-0000-000000000000"
6 }
7}
List Connections
Response Body
connections
arrayRequiredconnections
attributesFetch a Connection
Request Parameters
access_token
stringqueryRequiredThe access token of the connection.
Response Body
connection
objectRequiredconnection
attributes- QuickBooks
- Shopify
- Woo Commerce
- Amazon
Fetch a Connection Status
The Connection Status endpoint allows you to retrieve information about a connection's historical and recent data syncs.
Not every platform has detailed support for sync information about each data object, e.g. fields within the total
property. If a platform does not support a metadata field, the value will be null
.
Request Parameters
access_token
stringqueryRequiredThe access token of the connection.
Response Body
connection
objectRequiredconnection
attributesstatus
objectRequiredstatus
attributesDelete a Connection
Request Parameters
id
stringpathRequiredThe Rutter connection ID to delete.
Response Body
success
booleanRequiredtrue
if the delete operation succeeded.
1{
2 "success": true
3}
Schedule Incremental Sync
The Schedule Incremental Sync API endpoint allows you to manually trigger an Incremental Sync for a given connection. This will sync all objects that have been updated or created since the last sync. An example of when you may want to trigger an Incremental Sync is if you know new objects have been created in a platform, and you want to sync these new objects as soon as possible (rather than wait for Rutter's scheduled Incremental Sync to run).
NOTE: This functionality should only be used on a one-off basis. Rutter automatically schedules Incremental Syncs periodically and one doesn't typically need to make this API call except in rare cases. For each Incremental Sync triggered, Rutter may skip that many scheduled Incremental Syncs.
After receiving a success response, a sync will be queued and started shortly. You will begin to receive webhooks for updated/created objects if you are subscribed to them.
Request Parameters
access_token
stringqueryRequiredThe access token of the connection.
Response Body
success
booleanRequiredtrue
if the operation succeeded.
1{
2 "success": true
3}
Schedule Backfill
The Schedule Backfill API endpoint allows you to manually trigger a data backfill for a given connection. This will sync all data from the start date until now for the Rutter object provided. An example is if you make an update to an existing connection's Data Fetch Configuration, and you want to sync all historical data for the new objects you've added into the Data Fetch Configuration.
NOTE: This functionality should only be used on a one-off basis. If you trigger a Backfill, this will pause the scheduled Incremental Syncs that Rutter automatically performs for the connection until the Backfill is complete.
After receiving a success response, a sync will be queued and started shortly.
Request Parameters
access_token
stringqueryRequiredThe access token of the connection.
Request Body
start_date
stringRequiredThe start date of the backfill (e.g. 2023-02-07), up to 5 years ago.
end_date
stringThe end date of the backfill (e.g. 2023-03-14). If none provided, defaults to today.
entity
enumRequiredThe Rutter Entity for which you would like to create a backfill
include_webhooks
booleanYou can receive webhooks for updated/created objects found during the backfill if you are subscribed to them by including true
here. Defaults to false.
remarks
stringRemarks for why you are creating this backfill.
Response Body
success
booleanRequiredtrue
if the operation succeeded.
1{
2 "success": true
3}
Have questions?
Contact support for personalized guidance.