Payables
A resource describing a payment that needs to be made to a Company.
A Payable is a payment from you to another company.
With Routable, you can send a payment immediately via check or bank transfer, or schedule it to be sent on a future date.
You can specify the bank account or address to send to, or you can have your vendor go through your branded flow and submit it themselves. You can even mark a payment as paid externally, and use Routable as the bridge between you and your accounting software.
Types of Payables
Routable supports creating several different types of Payables.
Bank Transfer (type=ach
)
- Create this payable when you explicitly want to pay your vendor via bank transfer.
- Your vendor must have an existing PaymentMethod
where type=bank
.
Check (type=check
)
- Create this payable when you explicitly want to pay your vendor via check.
- Your vendor must have an existing PaymentMethod
where type=address
.
Cross-border (type=international
)
- Create this payable when paying a vendor in another country.
- Your vendor must have an existing PaymentMethod
where type=international
. They can create this in the Invite a Company or Accept Payment flows.
- You must have an existing Accounts where type=bank
in order to process an international
transaction.
Vendor Choice (type=vendor_choice
)
- Create this payable when you want your vendor to be able to choose their preferred payment method.
- You may use this when your vendor has no existing payment methods and they will be prompted to submit a payment method via our onboarding flow.
External (type=external
)
- Create this payable when you want to track a payment that was made outside of Routable.
Cross-border Payments
In addition to transfers within the United States, Routable supports payments to vendors in many additional countries. We'll need just a little more information, but now you can pay your foreign vendors as easily as your domestic ones! See our Cross-border Payments guide for more details.
Payable Status
Payables can be in one of several statuses that indicate their state. Let's take a look.
Typical Flow
Typically, Payables transition from Pending => Processing => Initiated => Completed.
Payables in a Completed state indicate that the payment has been successfully completed.Unsuccessful payments will end in either an Issue or Failed state, and may require Routable Support to intervene.


Red arrows indicate transitions that are possible but require support's intervention
Blue arrows indicate transitions that are possible but occur external to Routable.
Changeable - Non-Processing
needs_approval
needs_approval
An item in this state requires a user to take action on the item in the Routable dashboard per your account's approval settings.
ready_to_send
ready_to_send
An item in this state requires either user action in the dashboard or an API call to move the item into pending
, canceled
, or externally_paid
scheduled
scheduled
An item in this state will move to pending
automatically on the date_scheduled
Unchangeable - Non-Processing
pending
pending
An item in this state requires vendor or customer action and will be automatically transitioned to processing
when the required action is completed.
Depending on the scenario, it is possible to transition an item in this state to either canceled
or externally_paid
by contacting [email protected]
Unchangeable - Processing
processing
processing
An item in this state is actively being processed.
Note: A Payable only remains in the processing
status for a few microseconds during Routable's backend processing. As a result, we do not fire status_changed
Webhook events for the processing
status. In your webhooks, listen for the the initiated
status instead.
issue
issue
An item in this state indicates that there was an issue when trying to initiate the payment.
Please contact [email protected] and our support team can help restart the payment or move it into other final states (e.g. canceled
or externally_paid
).
initiated
initiated
An item in this state has had the payment initiated with our banking partners
failed
failed
An item in this state has failed after initiating the payment.
Please contact [email protected] and our support team can help restart the payment or move it into other final states (e.g. canceled
or externally_paid
).
Final
canceled
canceled
An item in this state has been canceled.
externally_paid
externally_paid
An item in this state has been marked as externally paid.
completed
completed
An item in this state has been paid.
Note: In some cases, payments may fail after they have Completed
status. This happens when banks are late notifying us about an error with the bank account. When this happens you will receive an email notification alerting you about the failed payment.
Webhook Events for Payables
Routable supports three webhooks for monitoring changes made to Payables, whether through the API or the Routable Dashboard. They are:
item.create
when a Payable is first createditem.status_change
when a Payable transitions from onestatus
to anotheritem.approval_change
when a Payable's approval status has been changed by one of your designated Approvers
Important: Use Idempotency Keys when Creating and Updating Payables
We highly recommend that you supply an idempotency key when creating payables to prevent duplicate requests. These keys are stored for a period of 24 hours.
If a request fails due to a network error, you can safely retry the same request with the same key and guarantee that your request had exactly one effect. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.
All requests with the same key will be considered attempts for the same request. It is therefore important that you use unique keys. We suggest using random values, such as UUIDs.
A note on status codes
Please note that it is possible for this endpoint to return a
202
response that indicates that we are still processing the request. To ensure that the payment has been created, you may attempt to retrieve it using the returned ID orself
link.
Scheduling Payables
Routable supports 3 different ways of scheduling your payables based on the value supplied for send_on
.
Sending a Payable Today
- To send a payable today, set it to today's date in Pacific time.
- Use this when you want to send a payable ASAP.
Sending a Payable in the Future
- To send a payable in the future, set send_on
to a future date in Pacific time.
- Use this when you want to send a payable in the future.
Sending a Payable with no defined date
- To create a payable with no specified date, set send_on
to null
.
- Use this when you want to prepare a payable to be sent. This can be useful when testing out your integration.
Updating Payables
Payables can be updated while they are in any of the Changeable
statuses listed above.
Versioning of Payables
Payables have a version
number, which is an integer that starts with 1 when the Payable is first created. If you plan on editing your Payables, you should store the version number along with the Payable ID. When you submit a PATCH
request to update a Payable, you must include the current version
number. This is verified against Routable's data to ensure that you are editing the most recent version of the Payable and that you have not missed a change that has occurred elsewhere, such as by an automated process or on the Routable Dashboard. If you submitted a version
number that does not match our current data, a 409 Conflict
status will be returned. The returned Payable object will contain the new, incremented version
number.
Line Items
When Payables are updated, you can make changes to the line items as well.
To make no changes to any of the Payable's line items, omit the
line_items
property entirely from the Update Payable request.
If you are adding, updating or deleting any line items, line items that are not changing should have just their
id
included in the Update Payable request.
// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged
"line_items": [
{
"id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
}
],
To add a new line item, add a new line item data structure without an
id
to the line_items
array.
Default Contacts
When sending Payables via our API, we will notify all contacts associated with the company based on the values specified for their default_contact_for_payable_and_receivable
field.
// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged
// The second line item will be added. In the following code samples, it will have
// id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee".
"line_items": [
{
"id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
},
{
"quantity": "2",
"unit_price": "25.00",
"amount": "50.00",
"style": "item",
"description": "This line item is being added."
}
],
To update an existing line item, submit the line item data with updated fields, and include the line item's
id
.
// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged.
// The line item with id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee" will be updated.
"line_items": [
{
"id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
},
{
"id": "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee",
"quantity": "3",
"unit_price": "25.00",
"amount": "75.00",
"style": "item",
"description": "This line item is being edited."
}
],
To delete a line item, submit an Update Payable request with that line item omitted entirely from the
line_items
array. Note that you cannot delete the last line item on a Payable.
// The line item with id "3b87b3d5-30d5-4bd0-a268-71f635ba973e" will remain unchanged.
// The line item with id "9cf8f634-ba8d-4521-8ccf-523e2ba2d4ee" will be deleted.
"line_items": [
{
"id": "3b87b3d5-30d5-4bd0-a268-71f635ba973e"
}
],
Default Approvals
When sending payables via our API and a payable requires approvals per your approval settings we will automatically fill the appropriate team members.
We do this by finding all applicable levels of approval and requesting approvals from all team members.
For example, you can set up your account so that:
- Any Payable over $1,000 requires a first level approval from either Angela or Oscar.
- Any Payable over $2,000 requires a second level approval from both Michael and Andy.
When creating a payable for $1,100, the API would request approval from both Angela and Oscar.
When creating a payable for $2,100, the API would request approval from both Michael and Andy for the second level as well as Angela and Oscar on the first level.
Accounting Software Integration
If you have an accounting application such as QuickBooks Online or Oracle NetSuite integrated with your Routable account, you will need to provide some extra data when creating a Payable. The ledger
object is reserved for this purpose. Each application requires different fields on the Payable, and in some cases, the Payable's line items as well.
Visit the API Reference for a full listing of fields required for your accounting application. If you need to import configured and customized fields in Accounting Software from your accounting application, you'll need to contact the Routable Developer Experience team to assist.
Updated about 5 hours ago