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

idstringRequired

The UUID of the connection. Generated by Rutter.

orgIdstringRequired

Your organization id.

platformenumRequired

The underlying platform.

One ofAMAZONEBAYETSYFNACWALMARTSHOPEELAZADAMERCADOLIBREALIBABASHOPLINEPRESTASHOPSHOPIFYMAGENTOWOO_COMMERCESQUARESPACEWIXSHOPERSHOPLAZZABIG_COMMERCESHOPWARECOMMERCELAYERWEBFLOWGUMROADECWIDPAYPALSQUARESTRIPECLOVERMOLLIEPAYNLAUTHORIZENETRECHARGECHARGIFYCHARGEBEERECURLYKASHFLOWSAGE_INTACCTDYNAMICS365ZOHOBOOKSEXACTONLINEFREEAGENTQUICKBOOKSQUICKBOOKS_DESKTOPFRESHBOOKSXEROSAGE_BUSINESS_CLOUDSAGESAGE_50NETSUITEWAVEMONEYBIRDSAGE200CLOUDPLAIDODOOTALLYGOOGLEFACEBOOK, or TIKTOK.
Endpoints
POST
/connections/create
GET
/connections
GET
/connections/access_token
GET
/connections/status
DELETE
/connections/:id
POST
/connections/incremental_sync
POST
/connections/backfill

Create a Connection

POSThttps://production.rutterapi.com/versioned/connections/create

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 ParamExample ValueDescription
platformSHOPIFYIf 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_urlhttps://www.google.com?q=customparameterIf 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
shopifystoreexampleif 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:

    platformenumRequired

    The underlying platform.

    One ofBIG_COMMERCEAMAZONSHOPIFYPRESTASHOPSHOPERWOO_COMMERCEMAGENTOEBAYLAZADAFNACSQUARESTRIPEQUICKBOOKSNETSUITEWALMART, or XERO.
    scopestring

    Any of:

    Credentials for BigCommerce

    oauth_client_idstring

    BigCommerce App Client ID

    oauth_access_tokenstringRequired

    BigCommerce Store Access Token

    store_urlstringRequired

    BigCommerce merchant .mybigcommerce.com domain URL

    oauth_client_secretstring

    BigCommerce App Client Secret

    Credentials for Amazon

    amazon_access_key_idstringRequired

    AWS User Access Key ID

    oauth_client_idstringRequired

    SP-API App Client ID

    amazon_secret_access_keystringRequired

    AWS User Secret Access Key

    amazon_seller_regionenumRequired

    Region of Amazon seller - must be one of na (North America), eu (Europe), or fe (Far East).

    One ofnaeu, or fe.
    amazon_selling_partner_rolestringRequired

    AWS Role ARN used in SP-API app

    oauth_client_secretstringRequired

    SP-API App Client Secret

    oauth_refresh_tokenstringRequired

    SP-API Refresh Token

    Any of:

    Credentials for Shopify Private App

    basic_passwordstringRequired

    Private Shopify App Password

    basic_usernamestringRequired

    Private Shopify App API Key

    store_urlstringRequired

    Shopify merchant .myshopify.com domain URL

    Credentials for Shopify Public App

    oauth_client_idstringRequired

    Shopify Public App Client ID

    oauth_access_tokenstringRequired

    Shopify Merchant Access Token

    oauth_client_secretstringRequired

    Shopify Public App Client Secret

    store_urlstringRequired

    Shopify merchant .myshopify.com domain URL

    Credentials for PrestaShop

    api_keystringRequired

    PrestaShop API Key

    store_urlstringRequired

    PrestaShop merchant domain URL

    Credentials for Shoper

    oauth_access_tokenstringRequired

    Shoper merchant OAuth Access Token

    oauth_refresh_tokenstringRequired

    Shoper merchant OAuth Refresh Token

    store_urlstringRequired

    Shoper merchant domain URL

    Credentials for WooCommerce

    basic_passwordstringRequired

    WooCommerce Rest API Consumer Secret

    basic_usernamestringRequired

    WooCommerce Rest API Consumer Key

    store_urlstringRequired

    WooCommerce merchant website URL

    Credentials for Magento

    basic_passwordstringRequired

    Magento Admin User Password

    basic_usernamestringRequired

    Magento Admin User Username

    store_urlstringRequired

    Magento merchant website URL

    Credentials for eBay

    oauth_client_idstringRequired

    Ebay Developer OAuth Client ID

    oauth_client_secretstringRequired

    Ebay Developer OAuth Client Secret

    oauth_refresh_tokenstringRequired

    Ebay OAuth Refresh Token

    Credentials for Lazada

    oauth_client_idstringRequired

    OAuth Client ID

    countrystringRequired

    Country Code for Merchant (e.g. id, sg, th)

    oauth_access_tokenstringRequired

    OAuth Access Token

    oauth_client_secretstringRequired

    OAuth Client Secret

    oauth_refresh_tokenstringRequired

    OAuth Refresh Token

    Credentials for Fnac

    partner_idstringRequired

    Partner ID

    shop_idstringRequired

    Shop ID

    keystringRequired

    Key

    Credentials for Square

    oauth_client_idstringRequired

    Square Developer OAuth Client ID

    oauth_client_secretstringRequired

    Square Developer OAuth Client Secret

    oauth_refresh_tokenstringRequired

    Square OAuth Refresh Token

    Credentials for Stripe

    account_idstringRequired

    Stripe Account ID

    oauth_access_tokenstringRequired

    Stripe OAuth Access Token

    Credentials for Quickbooks

    oauth_client_idstringRequired

    OAuth Client ID

    realm_idstringRequired

    Realm ID

    oauth_client_secretstringRequired

    OAuth Client Secret

    oauth_refresh_tokenstringRequired

    OAuth Refresh Token

    environmentstring

    Environment (e.g. sandbox)

    Credentials for Netsuite

    token_idstringRequired

    Token ID

    consumer_keystringRequired

    Consumer Key

    consumer_secretstringRequired

    Consumer Secret

    store_namestringRequired

    Store Name (for sandbox you should put it in the form '1000000_SB1')

    token_secretstringRequired

    Token Secret

    Credentials for Walmart

    oauth_client_idstringRequired

    Walmart Developer OAuth Client ID

    oauth_client_secretstringRequired

    Walmart Developer OAuth Client Secret

    Credentials for Xero

    oauth_client_idstringRequired

    OAuth Client ID

    tenant_idstringRequired

    The Xero Tenant ID

    user_idstringRequired

    The Xero User ID

    oauth_client_secretstringRequired

    OAuth Client Secret

    oauth_refresh_tokenstringRequired

    OAuth Refresh Token

Response Body

    connectionobjectRequired
    Show connection attributes
Support by integration
All platforms
Example Request Body
JSON
1
{
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
}
Example Response Body
JSON
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

GEThttps://production.rutterapi.com/versioned/connections

Response Body

    connectionsarrayRequired
    Show connections attributes
Support by integration
All platforms

Fetch a Connection

GEThttps://production.rutterapi.com/versioned/connections/access_token

Request Parameters

    access_tokenstringqueryRequired

    The access token of the connection.

Response Body

    connectionobjectRequired
    Show connection attributes
Support by integration
  • Amazon
    Amazon
  • Big Commerce
    Big Commerce
  • Chargebee
    Chargebee
  • Chargify
    Chargify

Fetch a Connection Status

GEThttps://production.rutterapi.com/versioned/connections/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_tokenstringqueryRequired

    The access token of the connection.

Response Body

    connectionobjectRequired
    Show connection attributes
    statusobjectRequired
    Show status attributes
Support by integration
All platforms

Delete a Connection

DELETEhttps://production.rutterapi.com/versioned/connections/:id

Request Parameters

    idstringpathRequired

    The Rutter connection ID to delete.

Response Body

    successbooleanRequired

    true if the delete operation succeeded.

Support by integration
All platforms
Example Response Body
JSON
1
{
2
"success": true
3
}

Schedule Incremental Sync

POSThttps://production.rutterapi.com/versioned/connections/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_tokenstringqueryRequired

    The access token of the connection.

Response Body

    successbooleanRequired

    true if the operation succeeded.

Support by integration
All platforms
Example Response Body
JSON
1
{
2
"success": true
3
}

Schedule Backfill

POSThttps://production.rutterapi.com/versioned/connections/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_tokenstringqueryRequired

    The access token of the connection.

Request Body

    start_datestringRequired

    The start date of the backfill (e.g. 2023-02-07), up to 5 years ago.

    end_datestring

    The end date of the backfill (e.g. 2023-03-14). If none provided, defaults to today.

    entityenumRequired

    The Rutter Entity for which you would like to create a backfill

    One ofaccountaccounting_customerbalance_sheetbank_depositbank_transferbillbill_credit_memobill_paymentcash_flowclasscommerce_customercompany_infocurrenciescustomer_groupdepartmentexpenseincome_statementinvoiceinvoice_credit_memoinvoice_paymentitemsjournal_entrylocationorderpayment_methodpayment_termpayoutproductpurchase_ordersales_orderstoresubscriptionsubsidiarytax_ratestransaction, or vendor.
    include_webhooksboolean

    You can receive webhooks for updated/created objects found during the backfill if you are subscribed to them by including true here. Defaults to false.

    remarksstring

    Remarks for why you are creating this backfill.

Response Body

    successbooleanRequired

    true if the operation succeeded.

Support by integration
All platforms
Example Response Body
JSON
1
{
2
"success": true
3
}

Have questions?

Contact support for personalized guidance.

Contact support