Basics

Rutter is a unified RESTful API for B2B Financial Products—connect to any commerce, payments, accounting, or ads system in a single API. We offer a range of product options with different capabilities and price points, as well as the ability to fine-tune our API to your needs.

To get started, click through the endpoints to learn more about the functionality across our APIs and check out our Postman Collection to test our API endpoints.

Organization

API reference pages are divided by the object with which the endpoints interact. For example, there is a single page for Bill Payments, but within the page there are endpoints for creating, updating, and listing bill payments.

Each API reference page has roughly three sections:

1. Overview

   A brief description of the Rutter entity and the set of endpoints.

2. Object

   A description of the object representing the associated data model.

3. Endpoints

   A list of endpoints available in the API. This will include a description of the endpoint, the HTTP method, the request and response body, and platform support.

Rutter supports API versioning - all APIs are prefixed with /versioned/ and a version must be supplied in the header by using the key X-Rutter-Version. The supported values are: 2024-08-31, 2024-04-30, 2023-03-14, and 2023-02-07.

Breaking API changes are changes that disrupt the working implementation of our customers. This can happen if we change our endpoints in a way that our customers do not expect them to change. We have a strict policy to never make a breaking change on an published version of our API.

Things we do not consider as breaking changes:

• Adding new API endpoints (e.g. POST /accounting/bill_credit_applications).
• Adding new optional request parameters to existing API endpoints.
• Making a previously required request parameter optional.
• Adding new property fields to existing API responses.
• Changing the order of property fields in existing API responses.
• Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.

All other API changes may be considered a breaking change. This includes (but is not limited to):

• Removing an API endpoint.
• Making a previously optional request parameter required.
• Adding a required request parameter to existing API endpoints.
• Removing or renaming property fields from existing API responses.
• Changing the property field type of existing API responses.
• Changing the property field of existing API responses that was non-nullable as nullable.
• Changing values of an enum type. Note that there are a couple of exceptions to this rule: we may add new values to enum's for platforms we support and for currency codes.

Please see the API upgrades page for more information on differences between our various API versions.

Authorizing Requests

Rutter uses your client_id and client_secret keys to control access to our API via HTTP Basic Auth. You can find your keys in your dashboard for each of our API environments (sandbox, production).

When making an API request to the server, Rutter expects your client_id and client_secret to be Base64 encoded within the Authorization header. The header is formed by concatenating the word Basic, followed by a space ( ), and a base64 encoded string of the client_id, a colon (:), and the client_secret.

Authorization: Basic base64({client_id}:{client_secret})

Authorizing Access for a Given Connection

To identify a specific connection, Rutter uses the access_token query parameter.

This token is generated by Rutter and is unique to each connection. The access token is acquired by hitting the Exchange Tokens endpoint.

Rutter uses standard HTTP error codes that follow common industry practices. However, we also utilize a few custom error codes for specific conditions unique to Rutter. These custom codes are designed to offer detailed insights into the nature of the issue, accompanied by actionable error messages wherever possible.

If you are experience any of these errors and are unsure what to do, please reach out to our support team.

Actionable Error Codes

Server Error Codes

Error Response

If you receive an error, you will receive an object with the following properties:

Error Codes

For error_types of CONNECTION_ERROR, the following error_codes may be returned:

• PRODUCT_NOT_READY
• PRODUCT_NOT_ALLOWED
• INVALID_CREDENTIALS
• LINK_ERROR
• ENDFORM_NOT_AVAILABLE
• CONNECTION_DISABLED
• NEEDS_UPDATE
• NO_CREDENTIALS
• PENDING
• IS_DUPLICATE
• ENDPOINT_NOT_SUPPORTED_FOR_YOUR_ORGANIZATION
• ENTITY_NOT_READY

When making a request for data, Rutter will paginate the returned data if the data set is too large. You'll know when pagination has occurred if the next_cursor field is supplied. The next_cursor is a generated base64 encoding of the timestamp and id of the next entity (e.g. an order, a transaction).

To proceed to the next page, set the query parameter cursor to the next_cursor value. A response without a next_cursor field can either signify the last page or that the response was small enough where pagination was not required.

Rutter allows for an extremely generous rate limit, which is designed to accommodate the vast majority of use cases. The current limit allows 500 requests in a window of 10 seconds.

When using Rutter's read endpoints, you will not experience the normal rate limits imposed by a specific platform (e.g. QuickBooks or Shopify).

Rutter's write endpoints pass requests directly to their respective platforms and will be subject to each platform's unique rate limits.

How does Rutter resolve rate limit issues?

In order to offer the fastest access to your users' data, Rutter uses a combination of caching and webhooks to store the latest data for a given connection. When you send requests to Rutter's API, most of the time, the data will be cached and returned immediately. One exception is when a customer first authorizes you to use their data. Rutter will begin downloading the data immediately, but it will not be ready until the INITIAL_UPDATE webhook fires.

How does Rutter cache data and keep it up-to-date?

Rutter does an "initial sync" of a user's data when they authenticate your app. This may take hours to days depending on the size of the data. Once this process completes, Rutter automatically updates data from the platform on a regular cadence.

You will receive notifications via a webhook whenever there are new events associated with a Connection or change in data.

This webhook fires after an initial data download for a Connection has been completed. You can now send requests to Rutter to fetch merchant data.

Attempting to fetch data from a Connection without receiving the INITIAL_UPDATE webhook will return a PRODUCT_NOT_READY error.

If your organization has data batching enabled, this webhook will fire after a batch of historical data for a Connection has been synchronized. You can continue to fetch data while this process occurs.

Whenever data changes inside of a platform, you will receive a webhook notifying you of the change. There are three types of changes - creates, updates, and deletes.

Every entity webhook contains a type corresponding to the entity, a code corresponding to the type of change, the entity that has been affected, and the access token related to that entity.

Fired after a new entity of a certain type has been created for a connection.

Fired after a new entity of a certain type has been updated for a connection.

Fired after a new entity of a certain type has been deleted for a connection. The final state of the entity before deletion is returned.

Asynchronous requests support idempotency - you can accomplish this by passing a distinct value through the Idempotency-Key request header, which serves as the unique key.

On many list endpoints, you can use the filter parameter to only return objects that match a certain criteria. Some examples of filterable endpoints are List Accounts and List Customers. To do this, you will use Rutter's custom query language as described below.

For string fields, you may use the = and ~ operators:

• = returns all objects matching the given value for that field. Matches are case sensitive.
• ~ returns all objects that include a word starting with the given value for that field. For example, ~ ru will return "Rutter" and "The Rutter API Company", but not "Truly". ~ is supported for any string field that is not an enum, date, or Rutter id. Matches are case insensitive.

The string value must be surrounded by double quotes (e.g., "...").

At this time, strings with double quotes " cannot be used in filters.

For number fields, you may use any of the following operators: =, <, <=, >, >=.

For string fields representing timestamps (such as created_at or updated_at), you may use any of the following operators: =, <, <=, >, >=. The timestamp value must be specified as a ISO 8601 string or in YYYY-MM-DD format and surrounded by double quotes (e.g., "...").

Multiple conditions can be grouped together within sets of parentheses (). The boolean operators AND and OR are supported. AND and OR operators have the same precedence, so please ensure you use parentheses as necessary for your desired output.

An example using cURL to get all accounts with a balance between $0 and $100 (both inclusive) might look something like this.

Add expand=platform_data as a query parameter to any GET endpoint. The response will include a platform_data object containing all raw data received from the platform for that API call.

Key Points

The platform_data object contains raw, unprocessed data directly from the source platform. Since this data isn't normalized, its structure and contents can vary significantly between different platforms.

Platform API changes may also affect the fields returned in platform_data without notice, so applications should handle these variations gracefully. Rutter makes no guarantees as to the structure or stability of fields returned in platform_data.

Finally, platform_data is only accessible for current Rutter endpoints. If you need to access data from endpoints not covered by Rutter's unified API, please contact your Rutter representative to discuss using our Passthrough API instead.

Get OpenAPI Spec