Payable

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 a 202 Accepted response that indicates that we are still processing the request. To ensure that the Payable has been successfully created, you may attempt to retrieve it using the returned ID or self 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:

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.