API Upgrades

Upgrading API Versions

Please refer to our versioning policy to understand what we consider a breaking change.

To switch to a different version of the Rutter API, one needs to specify the X-Rutter-Version header with a valid version (e.g., 2023-03-14).

Note for our older customers: our new root URL is https://production.rutterapi.com/versioned and ends with /versioned. If you are not using this, you are likely still using our legacy root URL: https://production.rutterapi.com. The legacy root URL doesn't support the X-Rutter-Version header, as it only supports our first API version: is identical to version 2023-02-07. Note that switching to the new root URL with a version of 2023-02-07 from the legacy root URL should be completely safe.

When you are ready to upgrade API versions, you can begin by:

  1. Checking the changelog below for the breaking changes introduced by the new version.
  2. Handle the changes in request and response bodies and update the X-Rutter-Version request header.

If you are subscribed to Rutter webhooks, you can upgrade the version of your webhook payloads by

  1. Checking the changelog below for the breaking changes introduced by the new version.
  2. Update your webhook code to handle both the old and new version of each object.
  3. In the Rutter Dashboard, update the version of your webhook payloads sent to your Webhook URL.

We recommend that you test your webhook code first by deploying a separate test handler and registering that to subscribe to the new version of webhooks in the Rutter Dashboard.

API Version: unstable

This is the version of Rutter's API that ships a set of breaking changes on top of our latest stable API. It is not recommended to be used in production until we release a new stable version. Think of it as an experimental version that you can use to test new features and provide feedback.

Breaking changes

Note that changes in response objects affect the responses of GET, POST, and PATCH endpoints.

/accounting/company_info

Response object for: GET /accounting/company_info

  • created_at is now nullable.
  • updated_at is now nullable.

/accounting/customers

Response object for: GET /accounting/customers, GET /accounting/customers/:id, POST /accounting/customers, and PATCH /accounting/customers/:id

  • updated_at is now nullable.

/accounting/vendors

Response object for: GET /accounting/vendors, GET /accounting/vendors/:id, POST /accounting/vendors, and PATCH /accounting/vendors/:id

  • The currency_code field has been renamed to currency_codes and returns an array instead of a single value.

API Version: 2023-03-14

This is Rutter's latest stable API version.

Breaking changes

Note that changes in response objects affect the responses of GET, POST, and PATCH endpoints.

/accounting/company_info

Response object for: GET /accounting/company_info

  • The legal_name field is now nullable.
  • The base_currency_code field has been renamed to currency_code and is now required.
  • The createdAt field has been renamed to created_at and is now nullable.
  • The updatedAt field has been renamed to updated_at and is now nullable.

/accounting/accounts

Response object for: GET /accounting/accounts, GET /accounting/accounts/:id, and POST /accounting/accounts

  • The current_balance field has been renamed to balance.
  • The updated_at field is now nullable.

Request object for: POST /accounting/accounts

  • The currency_code field is now required.

/accounting/vendors

Response object for: GET /accounting/vendors, GET /accounting/vendors/:id, and POST /accounting/vendors

  • The platform_id field is now required.
  • The currency field has been renamed to currency_code.
  • The status field is now required.
  • The created_at field is now nullable.
  • The updated_at field is now nullable.

Request object for: POST /accounting/vendors

  • The currency field has been renamed to currency_code.

/accounting/journal_entries

Response object for: GET /accounting/journal_entries, GET /accounting/journal_entries/:id, and POST /accounting/journal_entries

  • The following fields have been removed:
    • currency_rate
    • line_items.platform_id
    • line_items.tax_amount
    • line_items.account_ref in favor of the account_id field
  • The currency field has been renamed to currency_code.
  • The line_items.amount field has been renamed to line_items.total_amount.
  • The issue_date field has been renamed to transaction_date.

Request object for: POST /accounting/journal_entries

  • The currency_code field is now required.
  • The created_at field has been renamed to transaction_date.
  • The line_items.amount field has been renamed to line_items.total_amount.

/accounting/bills

Response object for: GET /accounting/bills, GET /accounting/bills/:id, and POST /accounting/bills

  • The following fields are now nullable:
    • account_id
    • due_date
    • created_at
    • updated_at
  • The purchase_orders field has been renamed to linked_purchase_orders.
  • The currency field has been renamed to currency_code.
  • The line_items.id field has been removed.
  • The following fields have been removed in favor of the new line_items.item field:
    • line_items.item_id
    • line_items.unit_amount
    • line_items.quantity
  • The following fields have their types changed:
    • total_discount is now a number.
    • sub_total is now a number.
    • tax_amount is now a number.
    • total_amount is now a number.
    • amount_due is now a number.
    • line_items.discount_amount is now a number.
    • line_items.sub_total is now a number.
    • line_items.tax_amount is now a number.
    • line_items.total_amount is now a number.
    • line_items.discount_percentage is now a number.
  • The payments field has been removed in favor of two new fields:
    • The linked_payments field contains a list of bill payments
    • The linked_credit_memos field contains a list of applied bill credits

Request object for: POST /accounting/bills

  • The currency field has been renamed to currency_code.
  • The line_items.amount field has been renamed to line_items.total_amount.
  • The issue_date field is now required.

/accounting/bill_payments

Response object for: GET /accounting/bill_payments, GET /accounting/bill_payments/:id, and POST /accounting/bill_payments

  • The currency field has been renamed to currency_code.
  • The total_amount field is now a number.
  • The txn_date field has been renamed to transaction_date.
  • The line_items field has been removed in favor of the new linked_bills field. The linked_bills field contains only bills tied to the payment and unlike line_items, does not contain any rows related to credit memos or journal entries.

Request object for: POST /accounting/bill_payments

  • The currency field has been renamed to currency_code.
  • The currency_rate field has been removed.
  • The line_items field has been removed in favor of the new linked_bills field.

/accounting/bill_credit_memos

Response object for: GET /accounting/bill_credit_memos, GET /accounting/bill_credit_memos/:id, and POST /accounting/bill_credit_memos

  • The document_number field is now nullable.
  • The following fields have their types changed:
    • total_discount is now a number.
    • remaining_amount is now a number.
    • linked_bills.allocated_amount is now a number.
  • The following fields are now nullable:
    • linked_bills.id
    • created_at
    • updated_at

Request object for: POST /accounting/bill_credit_memos

  • The line_items.amount field has been renamed to line_items.total_amount.

/accounting/purchase_orders

Response object for: GET /accounting/purchase_orders, GET /accounting/purchase_orders/:id

  • The following fields have been removed:
    • vendor_name
    • posted_date
    • line_items.platform_id
    • line_items.item_name
    • line_items.quantity_bill
    • line_items.quantity_received
    • line_items.amount_received
    • line_items.amount_billed
  • The following fields have been removed in favor of the new line_items.item field:
    • line_items.item_id
    • line_items.unit_amount
    • line_items.quantity
  • The line_items.amount field has been renamed to line_items.total_amount and is now a number.
  • The total_quantity field is now a number.
  • The total_amount field is now a number.
  • The status field is now an enum with the following values:
    • open
    • closed
    • unknown

/accounting/expenses

Request object for GET /accounting/expenses

  • The endpoint now also returns expense refunds if the expense_type query parameter is set to refund. The default behavior is to return expenses only.

Response object for: GET /accounting/expenses, GET /accounting/expenses/:id

  • The account_id field is now nullable.
  • The expense_date field has been renamed to transaction_date.
  • The line_items.amount field has been renamed to line_items.total_amount and is now a number.

Request object for: POST /accounting/expenses

  • The expense_date field has been renamed to transaction_date.
  • The new expense_type field is required and can be one of expense or refund.
  • The line_items.amount field has been renamed to line_items.total_amount.

/accounting/expenses/refunds

This endpoint has been removed in favor of the /accounting/expenses endpoint. To create a new expense refund, use the POST /accounting/expenses endpoint and set the expense_type field to refund.

Previous
Basics
Next
Troubleshooting