Payable
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 PaymentMethod to send to, or you can have your vendor go through your branded flow and submit it themselves. You can even mark a Payable
as paid externally, using Routable as the bridge between your application's processing of that payment and your integrated accounting software.
If you have turned on Approval Rules for your account, Routable will automatically identify the appropriate TeamMembers to request approvals from depending on the Payable
amount, and notify them of a request for approval. All you need to do is set up your approval rules, and the API takes it from there. Payables
will be created in a needs_approval
state if they are being held pending one or more approvals.
A note on status codes
Please note that it is possible for
POST
requests to return a202 Accepted
response that indicates that we are still processing the request. To ensure that thePayable
has been successfully created, you may attempt to retrieve it using the returned ID orself
link.
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
.
- Expedited delivery_methods
such as ach_next_day
, ach_same_day
and real_time_payment
must be funded from your Routable balance
Account
.
Check (type=check
)
- Create this Payable
when you explicitly want to pay your vendor via a physically mailed check.
- Your vendor must have an existing PaymentMethod
where type=address
.
International (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 Account where type=bank
in order to process an international
transaction.
External (type=external
)
- Create this Payable when you want to track a payment that was made outside of Routable.
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.
International Payments
In addition to transfers within the United States, Routable supports payments to vendors in more than 200 other 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 International Payments guide for more details.
Payable Lifecycle
Payables
have a lifecycle consisting of several statuses that change as the payment is created, processed and ultimately delivered. You can listen for webhook events to be notified when a Payable
is created or changes state. This is a good idea when you are maintaining a copy of Payable
data in your application, for example, in a data warehouse.
Best Practice: Use Idempotency Keys
Routable supports the use of Idempotency Keys to help protect against inadvertent repeated transactions. We strongly recommend using this optional feature when automating
Payables
.
Adding Attachments to Payables
You may want to track File Attachments alongside your Payables
, for example, a CSV of the inventory received on a purchase order or a PDF of an invoice. You can attach one or more files, and they will be attached to the invoice in both Routable and your integrated accounting software.
Scheduling Payables
Routable supports three different ways of scheduling your Payables
based on the value supplied for send_on
in the Create a Payable request:
Sending a Payable Immediately
- To send a Payable
today, set the send_to
field to today's date in Pacific time.
- This is the default behavior if the send_on
field is omitted from your request.
- The Payable
will immediately transition into the pending
status.
Sending a Payable on a Defined Date in the Future
- To create a scheduled
Payable
on a defined date in the future, set send_on
to a future date in Pacific time.
Holding a Payable
- To create a Payable
in a ready_to_send
status, explicitly set send_on
to a value of null
.
- Use this when you want to prepare a Payable
to be sent but not send it yet. This can be useful when testing out your integration. This strategy is also helpful when you intend to add additional line items over time to "snowball" a Payable
with many small payments, for example with microtransactions, and then pay them with a single transfer of funds.
Vendor Notification
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 message
field may contain an additional message you wish to include with emails to your vendors. Its value may include a limited subset of HTML tags:
b | blockquote | br | h1 - h6 | header | hr |
li | ol | p | pre | q | small |
span | strong | sub | sup | table | tbody |
td | tfoot | th | thead | tr | u |
ul | var | wbr |
Updating Payables
Payables
can be updated while they are in any of the Changeable
statuses.
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.
// 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"
}
],
Marking Existing Payables as Paid Outside of Routable
If you need to mark a Payable
as externally paid after it's been created, send an Update a Payable call with the ID of a Payable
in an editable state, change the type
field to external
, and provide the same data in the type_details
field of your payload as you would have had the Payable
been created as type = external
originally.
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 11 months ago