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 a pay code in its payCode field so it can be categorized correctly. We support custom pay codes, and you can use the Pay codes API to create and manage custom pay codes for each company. See the Guide to the Pay Codes API for the default pay codes and pay code 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.
• If you have Treasury Tipped Occupation Code data for a worker, you can optionally provide it in the ttocCode field. See List treasury tipped occupation codes for the list of valid values.

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.

Updating a payable item (upserting)

To update a payable item, simply call this endpoint again with the updated data structure, including its externalId field. If a payable with that ID exists, it will be automatically updated. If it doesn't, a new payable item will be created. This is an upsert operation.

If you want to allow correcting payable items that have already been paid-out, you can pass the correction-authorized=true query parameter. Without it, the request fails with an error. Corrections also require a label. If authorized, Everee will:

1. Archive the original payable item.
2. Create a one-time overpayment adjustment deduction for the original payable item's full amount, to be recovered from the worker's upcoming payments.
3. Create a replacement payable item from your request, to be paid out for its full amount.

The net effect is the difference between the original and corrected amounts: a corrected amount that's higher than the original results in the worker being paid the difference, and a lower one results in the difference being recouped.

The same query parameter lets you delete a payable item that has already been paid-out. The original payable item is archived and its amount is recouped through an overpayment adjustment deduction. The update and bulk delete endpoints never modify paid-out payable items.