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 ofAMAZON, EBAY, ETSY, FNAC, WALMART, SHOPEE, LAZADA, MERCADOLIBRE, ALIBABA, SHOPLINE, PRESTASHOP, SHOPIFY, MAGENTO, WOO_COMMERCE, SQUARESPACE, WIX, SHOPER, SHOPLAZZA, BIG_COMMERCE, SALLA, ZID, COMMERCELAYER, WEBFLOW, GUMROAD, ECWID, PAYPAL, SQUARE, STRIPE, CLOVER, MOLLIE, PAYNL, AUTHORIZENET, RECHARGE, CHARGIFY, CHARGEBEE, RECURLY, KASHFLOW, SAGE_INTACCT, SAGE_INTACCT_V2, DYNAMICS365, ZOHOBOOKS, EXACTONLINE, FREEAGENT, QUICKBOOKS, QUICKBOOKS_DESKTOP, FRESHBOOKS, XERO, SAGE_BUSINESS_CLOUD, SAGE_50, NETSUITE, WAVE, MONEYBIRD, SAGE200CLOUD, MX, PLAID, TELLER, ODOO, TALLY, GOOGLE, FACEBOOK, TIKTOK, INTUIT_BANK_FEEDS, SAGE, QUICKBOOKS_HRIS, BAMBOO_HR, or GUSTO.
Endpoints
GET
/connections
GET
/connections/access_token
GET
/connections/status
POST
/connections/create
PATCH
/connections/:id
DELETE
/connections/:id
POST
/connections/incremental_sync
POST
/connections/access_token/invalidate
POST
/connections/backfill

List Connections

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

Request Parameters

    statusenumqueryOptional

    Filter results by connection status. If omitted, will return all active, not_ready, and unhealthy connections.

    One ofactive, unhealthy, not_ready, needs_reauth, disabled, or any.

Response Body

Fetch a Connection

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

Request Parameters

    access_tokenstringqueryRequired

    The access token of the connection.

Response Body

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

Create a Connection

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

Create connections programmatically using the Create a Connection API. There are three 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.
  • For Intuit Bank Feeds only, all new connections must be created by calling this endpoint with the body "platform": "INTUIT_BANK_FEEDS". Please see our guide for more details.

A connection's access_token is unique and does not expire. To rotate the access_token for a connection, you can use the /connections/access_token/invalidate endpoint. This endpoint generates a new access_token while invalidating the old one.

Sync Configuration

You can optionally include a syncConfig field when creating a connection to customize how data is synced. This allows you to specify which entities to sync, historical data timeframes, and incremental sync frequency. Sync configuration is currently supported for most accounting platforms.

For complete details about sync configuration structure and options, see Sync Configuration.

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:
    platformenum

    The underlying platform.

    One ofBIG_COMMERCE, AMAZON, SHOPIFY, PRESTASHOP, SHOPER, WOO_COMMERCE, MAGENTO, EBAY, LAZADA, FNAC, SQUARE, STRIPE, QUICKBOOKS, NETSUITE, WALMART, XERO, ZOHOBOOKS, or INTUIT_BANK_FEEDS.
    scopestringOptional
    syncConfigobjectOptional

    Optional sync configuration for the connection. Supported for Dynamics 365 Business Central, FreshBooks, Moneybird, NetSuite, Odoo, QuickBooks, QuickBooks Desktop, Sage Business Cloud, Sage Intacct v2, Stripe, Xero, and Zoho Books.

    Show syncConfig attributes
    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 ofna, eu, 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

    seller_idstringOptional

    For OAuth connections, the Walmart Seller ID.

    oauth_client_secretstring

    Walmart Developer OAuth Client Secret

    oauth_refresh_tokenstringOptional

    Walmart OAuth Refresh Token. If provided, the connection is created as an OAuth 2.0 connection.

    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

    Credentials for Zoho Books

    oauth_client_idstring

    OAuth Client ID

    organization_idstring

    Zoho Books Organization ID

    oauth_access_tokenstring

    OAuth Access Token

    oauth_client_secretstring

    OAuth Client Secret

    oauth_refresh_tokenstring

    OAuth Refresh Token

    regionstringOptional

    Zoho region (e.g., com, eu, in, com.au)

Response Body

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
}
200
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
    "name": "Example Connection"


7
  }


8
}

Update a Connection

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

Request Parameters

    idstringpathRequired

    The Rutter generated unique ID of the object.

Request Body

    namestring

    Customer-supplied unique name of the connection. Must be unique across all connections. Must be at most 30 characters.

Response Body

Example Request Body
JSON
1
{


2
  "name": "Example Connection"


3
}
200
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
    "name": "Example Connection"


7
  }


8
}

Delete a Connection

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

Request Parameters

    idstringpathRequired

    The Rutter connection ID to delete.

Response Body

200
Example Response Body
JSON
1
{


2
  "success": true


3
}

Trigger Incremental Sync

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

The Trigger 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.

Request Body

    object_typesarrayOptional

    The Rutter object types which you would like to sync. If an empty array is provided, no entities will be synced. If object_types is not defined, all entities will be synced.

    One or more ofaccount, accounting_customer, accounting_customer_refund, accounting_transaction, balance_sheet, bank_account, bank_account_balance, bank_account_details, bank_deposit, bank_transaction, bank_transfer, bill, bill_credit_memo, bill_payment, cash_flow, class, commerce_customer, company_info, currencies, customer_group, department, expense, income_statement, invoice, invoice_credit_memo, invoice_payment, items, journal_entry, location, order, payment_method, payment_term, payout, product, project, purchase_order, sales_order, sales_receipt, store, subscription, subsidiary, task, tax_agency, tax_rates, transaction, or vendor.

Response Body

200
Example Response Body
JSON
1
{


2
  "success": true


3
}

Invalidate Access Token

POSThttps://production.rutterapi.com/versioned/connections/access_token/invalidate

This endpoint generates a new access_token while invalidating the old one.

Request Parameters

    access_tokenstringqueryRequired

    The access token of the connection.

Response Body

200
Example Response Body
JSON
1
{


2
  "new_access_token": "00000000-0000-0000-0000-000000000000"


3
}

Trigger Data Recovery Backfill

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

The Trigger Data Recovery Backfill API endpoint is a heavyweight operation to reload all historical data for a given connection. Backfills can significantly impact a connection's performance and normal data sync cadence and should be used with care.

If you trigger a Backfill, this will pause the scheduled Incremental Syncs that Rutter automatically performs for the connection until the Backfill is complete. Backfills may also cause rate limits to be hit on the source platform due to the quantity of data being synced.

Backfills should only be used in two scenarios:

  1. You have added a new entity to your Data Sync Config and need to retrieve historical data for that entity.
  2. You have identified data gaps that need remediation. This is an extremely rare occurrence.

Do not use this endpoint for regular data syncs. Consider using our Trigger Incremental Sync endpoint instead.

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_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.

    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. Please be careful that depending on the order of the Rutter object types synced, webhooks sent in this way may be incomplete.

    object_typesarray

    The Rutter object types for which you would like to create a backfill. Note that linked objects will not be backfilled unless you specify them explicitly. For example, if you backfill invoice, this will not backfill invoice_payment for the same time period unless you also specify it.

    One or more ofaccount, accounting_customer, accounting_customer_refund, accounting_transaction, balance_sheet, bank_account, bank_account_balance, bank_account_details, bank_deposit, bank_transaction, bank_transfer, bill, bill_credit_memo, bill_payment, cash_flow, class, commerce_customer, company_info, currencies, customer_group, department, expense, income_statement, invoice, invoice_credit_memo, invoice_payment, items, journal_entry, location, order, payment_method, payment_term, payout, product, project, purchase_order, sales_order, sales_receipt, store, subscription, subsidiary, task, tax_agency, tax_rates, transaction, or vendor.
    remarksstringOptional

    Remarks for why you are creating this backfill.

Response Body

200
Example Response Body
JSON
1
{


2
  "success": true


3
}

Have questions?

Contact support for personalized guidance.

Contact support
Next
Tokens