Create Payable Item

A payable item is a gross amount of funds to be paid to a Worker. Creating a payable item places it in a "pending" status and does not automatically pay it out: you need to request the pay-out of Payables in order for them to be paid.

Common examples of payable items include bonuses, stipends, mileage, expense reimbursements, or work performed by contractors.

👍

Use the Timesheets API to record employees' hours

Don't use the Payables API to pay employees for hours worked. Instead, use the Timesheets API to record employees' hourly wages. That allows us to pay them in full compliance with labor law. You should use the Payables API to record any non-hourly wage amounts to employees, like per diems, stipends, or bonuses.

Using the Payables API

• You assign each payable item an earning type in its earningType field so it can be categorized correctly. We support custom earning types, so just contact your account executive or [email protected] to configure your earning types.
• You provide a unique identifier for each payable item in its externalId field. This ID should be meaningful to you, because we use this ID as an idempotency key to prevent creating multiple payable items that represent the same amount. See the Payables API guide for more information.
• You can optionally provide the unitRate and unitCount fields as metadata for amounts like miles driven, deliveries completed, or other unit-based pay amounts.

Paying out payable items

There are two ways to pay-out a payable item:

1. Immediately, which pays it out as quickly as possible (also known as off-cycle).
2. With payroll, which automatically includes it as part of the worker's regularly scheduled payroll cycle, and pays it out once payroll is approved.

📘

Contractors and employees work differently

Only W-2 employees, not contractors, are included in regularly scheduled payroll cycles, so while you can pay out payable items to employees either "immediately" or "with payroll", contractors can only be paid using the "immediately" option. See the Payables Guide for more information.

Payable items are created in a "pending" state. In this "pending" state, payable items are available to be paid out at a future time, but are not paid out right away. Instead, paying out a payable item to a contractor (or off-cycle to an employee), can be triggered by calling the Process Payable Items for Payout endpoint, which processes payable items into payments.

The following scenarios are an overview of how to pay workers in different classifications:

Are you only paying contractors?

You have to call Process Payable Items for Payout in order for any payable items to be paid out.

Are you only paying employees?

You have to choose whether you want employees' payable items to be paid out immediately or with regular payroll. By default, employees' payable items will wait for regular payroll and won't be paid out immediately.

See the includeWorkersOnRegularPayCycle parameter in the Process Payable Items for Payout API endpoint to control this.

Are you paying both contractors and employees?

You have to call Process Payable Items for Payout in order for any payable items to be paid out to contractors.

For employees, you have to choose whether you want employees' payable items to be paid out immediately, as they are for contractors, or wait for them to be included with regular payroll. By default, employees' payable items will wait for regular payroll and won't be paid out immediately.

See the includeWorkersOnRegularPayCycle parameter in Process Payable Items for Payout to control this.