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., 2024-08-31).

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.

Breaking Changes: 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 for general use 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.

/accounting/sales_orders

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

  • line_items[].item.id is now nullable. Its value will not be null except in the unusual case when the item could not be synced. (In previous versions it was an empty string in similar circumstances.)

/accounting/invoices

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

  • linked_payments[].id is now nullable. Its value will not be null except in the unusual case when the payment could not be synced. (In previous versions it was an empty string in similar circumstances.)
  • linked_payments[].allocated_date is now nullable. Its value will not be null except in the unusual case when the allocated date could not be synced. (In previous versions it was an empty string in similar circumstances.)

/accounting/invoice_credit_memos

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

  • The issue_date field now returns a string in YYYY-MM-DD format.
  • The allocated_at field has been renamed to allocated_date and now uses the YYYY-MM-DD format.
  • The remaining_amount, total_amount, and line_items[].tax_amount fields now return numbers instead of strings.
  • line_items[].amount has been renamed to line_items[].total_amount and now returns a number instead of a string.
  • The status enum is now all lowercase.
  • The linked_invoices[].allocated_date is no longer optional and is now nullable.
  • The line_items[].item_id field has been removed in favor of line_items[].item.id.
  • The line_items[].quantity field has been removed in favor of line_items[].item.quantity.
  • The line_items[].unit_amount field has been removed in favor of line_items[].item.unit_amount.
  • The line_items[].id, line_items[].discount_amount, line_items[].discount_percentage, line_items[].sub_total, line_items[].additional_fields.rev_rec_start_date, and line_items[].additional_fields.rev_rec_end_date fields have been removed.

Breaking Changes: 2024-08-31

This API version is our most-recent and stable API version.

In this version, we respond with a HTTP 400 Bad Request error for any requests that contain unknown query parameters or request body fields. This is to help you catch mistakes in API calls as early as possible.

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

/accounting/accounts

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

  • updated_at is now nullable.

/accounting/invoices

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

  • issue_date is now nullable.

/accounting/invoice_payments

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

  • The additional_fields.reference_number field has been removed in favor of the top-level reference field.

Request object for: POST /accounting/invoice_payments

  • The additional_fields.reference_number field has been removed in favor of the top-level reference field.

/accounting/customers

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

  • The status enum is now all lower case and INACTIVE has been mapped to archived.

Breaking Changes: 2024-04-30

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/invoices

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

  • account_id is now nullable.
  • total_discount has been renamed to discount_amount and is now a number instead of a string.
  • The following fields are now numbers instead of strings: amount_due, sub_total, tax_amount, and total_amount.
  • currency_code is now an enum.
  • The following fields on line_items have been removed: item_id, quantity, and unit_amount.
  • An item field has been added to line_items which contains id (previously item_id), quantity, and unit_amount.
  • The id field on line_items has been removed as it contained the same value as platform_id. Going forward, please use the value of platform_id instead of id.
  • amount on line_items has been changed to total_amount and is now a number instead of a string.
  • The following fields on line_items are now numbers instead of strings: discount_amount, discount_percentage, sub_total, and tax_amount.
  • amount on linked_payments has been changed to allocated_amount and is now a number instead of a string.
  • date on linked_payments has been changed to allocated_date.

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

Breaking Changes: 2023-03-14

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