API Version 2023-03-14
2023-03-14
is Rutter's first API version that ships a set of breaking changes. As part of this change, we are labeling our existing API as version 2023-02-07
.
Please refer to our versioning policy to understand what we consider a breaking change.
To support versioning, we are changing our root URL - https://production.rutterapi.com/versioned
. Note that the new root URL ends with /versioned
. Our legacy root URL is https://production.rutterapi.com
, which is identical to version 2023-02-07
.
To switch to the versioned Rutter API, you'll also need to specify the X-Rutter-Version
header with a valid version (e.g., 2023-03-14
). 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:
- Checking the change changelog below for the breaking changes introduced by the new version.
- 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
- Checking the changelog below for the breaking changes introduced by the new version.
- Update your webhook code to handle both the old and new version of each object.
- 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.
Breaking changes
Note that changes in response objects affect the responses of both GET
and POST
endpoints. All breaking changes are listed below.
/accounting/company_info
Response object for: GET /accounting/company_info
- The
platform_id
field has been removed. - The
legal_name
field is now nullable. - The
base_currency_code
field has been renamed tocurrency_code
and is now required. - The
createdAt
field has been renamed tocreated_at
and is now nullable. - The
updatedAt
field has been renamed toupdated_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 tobalance
. - 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 tocurrency_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 tocurrency_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 theaccount_id
field
- The
currency
field has been renamed tocurrency_code
. - The
line_items.amount
field has been renamed toline_items.total_amount
. - The
issue_date
field has been renamed totransaction_date
.
Request object for: POST /accounting/journal_entries
- The
currency_code
field is now required. - The
created_at
field has been renamed totransaction_date
. - The
line_items.amount
field has been renamed toline_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 tolinked_purchase_orders
. - The
currency
field has been renamed tocurrency_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 anumber
.sub_total
is now anumber
.tax_amount
is now anumber
.total_amount
is now anumber
.amount_due
is now anumber
.line_items.discount_amount
is now anumber
.line_items.sub_total
is now anumber
.line_items.tax_amount
is now anumber
.line_items.total_amount
is now anumber
.line_items.discount_percentage
is now anumber
.
- 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
- The
Request object for: POST /accounting/bills
- The
currency
field has been renamed tocurrency_code
. - The
line_items.amount
field has been renamed toline_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 tocurrency_code
. - The
total_amount
field is now anumber
. - The
txn_date
field has been renamed totransaction_date
. - The
line_items
field has been removed in favor of the newlinked_bills
field. Thelinked_bills
field contains only bills tied to the payment and unlikeline_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 tocurrency_code
. - The
currency_rate
field has been removed. - The
line_items
field has been removed in favor of the newlinked_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 anumber
.remaining_amount
is now anumber
.linked_bills.allocated_amount
is now anumber
.
- 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 toline_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 toline_items.total_amount
and is now anumber
. - The
total_quantity
field is now anumber
. - The
total_amount
field is now anumber
. - 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 torefund
. 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 totransaction_date
. - The
line_items.amount
field has been renamed toline_items.total_amount
and is now anumber
.
Request object for: POST /accounting/expenses
- The
expense_date
field has been renamed totransaction_date
. - The new
expense_type
field is required and can be one ofexpense
orrefund
. - The
line_items.amount
field has been renamed toline_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
.