Foundations

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

idstring

The UUID of the connection. Generated by Rutter.

orgIdstring

Your organization id.

platformenum

The underlying platform.

One ofAMAZONEBAYETSYFNACWALMARTSHOPEELAZADAMERCADOLIBREALIBABASHOPLINEPRESTASHOPSHOPIFYMAGENTOWOO_COMMERCESQUARESPACEWIXSHOPERSHOPLAZZABIG_COMMERCESHOPWARECOMMERCELAYERWEBFLOWGUMROADECWIDPAYPALSQUARESTRIPECLOVERMOLLIEPAYNLAUTHORIZENETRECHARGECHARGIFYCHARGEBEERECURLYKASHFLOWSAGE_INTACCTDYNAMICS365ZOHOBOOKSEXACTONLINEFREEAGENTQUICKBOOKSQUICKBOOKS_DESKTOPFRESHBOOKSXEROSAGE_BUSINESS_CLOUDSAGESAGE_50NETSUITEWAVEMONEYBIRDPLAIDODOOTALLYGOOGLEFACEBOOK, or TIKTOK.
Example Connection Object
{
  "id": "00000000-0000-0000-0000-000000000000",
  "orgId": "00000000-0000-0000-0000-000000000000",
  "platform": "SHOPIFY"
}

Create a Connection

POST /versioned/connections/create
Supported for: All Platforms

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.

Request Body

    All of:

    platformenum

    The underlying platform.

    One ofBIG_COMMERCEAMAZONSHOPIFYPRESTASHOPSHOPERWOO_COMMERCEMAGENTOEBAYLAZADAFNACSQUARESTRIPEQUICKBOOKSNETSUITEWALMART, or XERO.
    scopestringoptional

    Any of:

    Credentials for BigCommerce

    oauth_client_idstringoptional

    BigCommerce App Client ID

    oauth_access_tokenstring

    BigCommerce Store Access Token

    store_urlstring

    BigCommerce merchant .mybigcommerce.com domain URL

    oauth_client_secretstringoptional

    BigCommerce App Client Secret

    Credentials for Amazon

    amazon_access_key_idstring

    AWS User Access Key ID

    oauth_client_idstring

    SP-API App Client ID

    amazon_secret_access_keystring

    AWS User Secret Access Key

    amazon_seller_regionenum

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

    One ofnaeu, or fe.
    amazon_selling_partner_rolestring

    AWS Role ARN used in SP-API app

    oauth_client_secretstring

    SP-API App Client Secret

    oauth_refresh_tokenstring

    SP-API Refresh Token

    Any of:

    Credentials for Shopify Private App

    basic_passwordstring

    Private Shopify App Password

    basic_usernamestring

    Private Shopify App API Key

    store_urlstring

    Shopify merchant .myshopify.com domain URL

    Credentials for Shopify Public App

    oauth_client_idstring

    Shopify Public App Client ID

    oauth_access_tokenstring

    Shopify Merchant Access Token

    oauth_client_secretstring

    Shopify Public App Client Secret

    store_urlstring

    Shopify merchant .myshopify.com domain URL

    Credentials for PrestaShop

    api_keystring

    PrestaShop API Key

    store_urlstring

    PrestaShop merchant domain URL

    Credentials for Shoper

    oauth_access_tokenstring

    Shoper merchant OAuth Access Token

    oauth_refresh_tokenstring

    Shoper merchant OAuth Refresh Token

    store_urlstring

    Shoper merchant domain URL

    Credentials for WooCommerce

    basic_passwordstring

    WooCommerce Rest API Consumer Secret

    basic_usernamestring

    WooCommerce Rest API Consumer Key

    store_urlstring

    WooCommerce merchant website URL

    Credentials for Magento

    basic_passwordstring

    Magento Admin User Password

    basic_usernamestring

    Magento Admin User Username

    store_urlstring

    Magento merchant website URL

    Credentials for eBay

    oauth_client_idstring

    Ebay Developer OAuth Client ID

    oauth_client_secretstring

    Ebay Developer OAuth Client Secret

    oauth_refresh_tokenstring

    Ebay OAuth Refresh Token

    Credentials for Lazada

    oauth_client_idstring

    OAuth Client ID

    countrystring

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

    oauth_access_tokenstring

    OAuth Access Token

    oauth_client_secretstring

    OAuth Client Secret

    oauth_refresh_tokenstring

    OAuth Refresh Token

    Credentials for Fnac

    partner_idstring

    Partner ID

    shop_idstring

    Shop ID

    keystring

    Key

    Credentials for Square

    oauth_client_idstring

    Square Developer OAuth Client ID

    oauth_client_secretstring

    Square Developer OAuth Client Secret

    oauth_refresh_tokenstring

    Square OAuth Refresh Token

    Credentials for Stripe

    account_idstring

    Stripe Account ID

    oauth_access_tokenstring

    Stripe OAuth Access Token

    Credentials for Quickbooks

    oauth_client_idstring

    OAuth Client ID

    realm_idstring

    Realm ID

    oauth_client_secretstring

    OAuth Client Secret

    oauth_refresh_tokenstring

    OAuth Refresh Token

    environmentstringoptional

    Environment (e.g. sandbox)

    Credentials for Netsuite

    token_idstring

    Token ID

    consumer_keystring

    Consumer Key

    consumer_secretstring

    Consumer Secret

    store_namestring

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

    token_secretstring

    Token Secret

    Credentials for Walmart

    oauth_client_idstring

    Walmart Developer OAuth Client ID

    oauth_client_secretstring

    Walmart Developer OAuth Client Secret

    Credentials for Xero

    oauth_client_idstring

    OAuth Client ID

    tenant_idstring

    The Xero Tenant ID

    user_idstring

    The Xero User ID

    oauth_client_secretstring

    OAuth Client Secret

    oauth_refresh_tokenstring

    OAuth Refresh Token

Response Body

    connectionobject
    Show connection attributes
Example Request Body
{
  "platform": "SHOPIFY",
  "oauth_client_id": "CLIENT_ID",
  "oauth_access_token": "ACCESS_TOKEN",
  "store_url": "shopifystore.myshopify.com",
  "oauth_client_secret": "CLIENT_SECRET"
}
Example Response Body
{
  "connection": {
    "id": "00000000-0000-0000-0000-000000000000",
    "access_token": "00000000-0000-0000-0000-000000000000",
    "link_url": "https://link.rutterapi.com/connection/00000000-0000-0000-0000-000000000000"
  }
}

List Connections

GET /versioned/connections
Supported for: All Platforms

Response Body

    connectionsarray
    Show connections attributes

Fetch a Connection

GET /versioned/connections/access_token
Supported for: AmazonBig CommerceChargebeeChargifyDynamics 365eBayEtsyFreshBooksLazadaMagentoMercado LibreNetSuitePayPalPrestashopQuickBooksQuickBooks DesktopRecurlySage Business CloudSage IntacctShopeeShoperShopifyShopwareSquareSquarespaceStripeWalmartWaveWixWoo CommerceXeroZoho Books

Request Parameters

    access_tokenstringquery

    The access token of the connection.

Response Body

    connectionobject
    Show connection attributes

Fetch a Connection Status

GET /versioned/connections/status
Supported for: All Platforms

Request Parameters

    access_tokenstringquery

    The access token of the connection.

Response Body

    connectionobject
    Show connection attributes
    statusobject
    Show status attributes

Delete a Connection

DELETE /versioned/connections/:id
Supported for: All Platforms

Request Parameters

    idstringpath

    The Rutter connection ID to delete.

Response Body

    successboolean

    true if the delete operation succeeded.

Example Response Body
{
  "success": true
}

Schedule Incremental Sync

POST /versioned/connections/incremental_sync
Supported for: All Platforms

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_tokenstringquery

    The access token of the connection.

Response Body

    successboolean

    true if the operation succeeded.

Example Response Body
{
  "success": true
}

Schedule Backfill

POST /versioned/connections/backfill
Supported for: All Platforms

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_tokenstringquery

    The access token of the connection.

Request Body

    start_datestring

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

    end_datestringoptional

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

    entityenum

    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_webhooksbooleanoptional

    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.

    remarksstringoptional

    Remarks for why you are creating this backfill.

Response Body

    successboolean

    true if the operation succeeded.

Example Response Body
{
  "success": true
}