The Payables API is how you record and pay out wage amounts, contractor pay, stipend payments, expense reimbursements, and any other kind of non-hourly wages, to employees and contractors. You can't pay employees for their hourly wages with this API, because hourly wages have complex compliance rules. To do that, you'll want to send us timesheet data to the Timesheets API instead.
By using the Payables API, you'll create "payable items" in Everee. A payable item represents a single amount to be paid to a worker, coded under a specific pay code. We don't calculate the amount—you have to provide it to us, because payable amounts are often calculated using complex or custom rules we don't manage. There's a variety of additional settings and metadata you can use to make sure your payable items are set up exactly how you want them.
We won't move any money until a payroll admin approves itIn order to be paid out, payable items are first converted into "payments", which represent the movement of money. Creating a payable item, and even requesting it to be paid out ASAP, will not cause it to be paid automatically. All payments in Everee will pause for manual approval by a payroll admin before any money is actually transacted (unless you ask us to set up auto-approval).
Calling API endpoints in the Payables API won't cause money to move (unless you asked for that). A human has to clear it first. These humans will approve payments in the Everee admin portal, and that allows us to move money. As a result, paying employees and contractors is the same: the whole payroll batch gets reviewed & approved the same way, no matter who's getting paid.
This API automatically handles various complex scenarios like multiple pay rates, multiple work locations, tax jurisdiction determination, and custom pay codes, depending on what data you provide and the setup of an Everee instance. This is all documented below and in the API endpoints in this section of the API reference. Just let us know at [email protected] if you need any help.
📍 Work locations
When workers could be staffed at different work locations throughout a pay period, it's critical to assign the correct work location for each payable item to ensure the correct tax liability is determined for each location where wages are earned. Providing a value for the parameter workLocationId assigns payable items to a specific work location for tax purposes. It's likely you'll want to use this parameter.
Work locations must be created before you can assign shifts to them. There are no restrictions on how many work locations you can create. See the Work Locations API for more information about creating work locations.
Are you in the staffing industry? This is an integration requirementWhile there are cases in the staffing industry where employees work permanently or semi-permanently at the same location, it's generally a requirement when integrating with Everee to create work locations and assign payable items to them appropriately. Failing to manage work locations accurately will lead to serious tax consequences, so you should plan to include this in your integration.
If no value is provided, the work location assigned to the worker's profile is used by default.
When a payable is assigned on a payable item, the payable amount is subject to all employee– and employer–side taxes in effect for that location on the date the hours were worked (if you're paying an employee). These taxes are automatically applied to the payment that pays out wages for those hours, typically in the next payroll batch.
If a worker's payroll payment holds several payable items, each with different work locations, we automatically determine all taxes for each work location, and apply them all appropriately when calculating the gross-to-net.
💵 Employees and contractors are a little different
You can create payable items for both employees and contractors, but they're not paid in quite the same way, so you need to treat them a little differently in your integration. While both employees and contractors can be paid on an as-soon-as-possible basis (called "off-cycle" in payroll), only employees can be paid on a regular payroll cycle.
| Employees | Contractors | |
|---|---|---|
| Can be paid on a regular payroll cycle | ✅ Yes | ❌ No |
| Can be paid on an as-soon-as-possible basis | ✅ Yes | ✅ Yes |
Employees are easy peasy
If you're paying employees, just create payable items for all non-hourly wages and other amounts. Once you've created payable items, we will automatically include them in the regular payroll payments that we process for those employees. Easy! 💪
But there can be scenarios where you want to pay certain payable items to employees outside the regular payroll cycle. This could a payroll advance, expense reimbursement, or a similar item. In this case, you can call the Process Payable Items for Payout API endpoint to tell us to process certain payable items outside of the regular payroll cycle. This will allow a payroll admin to approve and pay out those payable items separately. Once approved, they'll be locked and won't be paid again on the next regular payroll.
But what about contractors?
Remember how we said that only employees can be paid on a regular payroll cycle? That means when you're paying contractors, you MUST call the Process Payable Items for Payout API endpoint to let us know that it's time to prepare payments for contractors. If you don't call that API endpoint, we won't process payable items at all, and contractors won't get paid. That's not good.
Calling that endpoint doesn't cause contractors to be paid instantly! Instead, it processes payable items for contractors into payments, which are then approved by payroll admins as part of running payroll.
You should call the Process Payable Items for Payout API endpoint AFTER all payable items for contractors have been sent to Everee, and BEFORE payroll admins start their review & approval process.
If you call it before you've finished sending us all the payable items, then some will be missed until the next pay cycle. If you call it after payroll admins approve payments, then contractors won't have their payable items paid out. The sweet spot is in between.
You're completely in control of when contractors get paid. Just call Process Payable Items for Payout to process payable items into payments, for admins to approve, at the right time for your business or workflow.
🔒 Making sure payable items are only paid once
Unlike timesheet hours, we can't guarantee that you won't be able to send us the same payable items more than once. This is obviously bad: a worker would get double-paid, or more.
This is an idempotency problem. We need to make sure we only accept one instance of a single payable item, even if you try to send it to us more than once for good reasons.
Payable items have a required parameter called externalId. You specify a value for this ID, and it must be globally unique within an Everee instance. It's an idempotency key. If you try to send us a payable item with an externalId we already know, we'll reject it.
Internet failures are a fact of lifeDespite everyone's best efforts, internet connectivity failures happen. A classic symptom is an HTTP request that starts but never finishes. That could mean that we receive a payable item from you successfully, and send you a confirmation, but you never receive it because of the connectivity failure. Your system could (and probably should!) retry the request, but we definitely shouldn't accept the same payable item a second time. This is why idempotency matters.
If your system has a similar concept of a "payable amount", and it has a unique primary key, you can use that! If you don't have that concept, but you can create a data table that assigns a primary key to a payable amount, then you'll use that primary key. A concrete primary key is recommended. 👍
Otherwise, you'll have to generate an ID at transmission time. If you do this, it's extremely important that the way you create this ID is deterministic. Don't use current timestamps, UUIDs, random numbers, or anything else with a random component! If you use a random or time-based value, it's different every time you generate it, and that defeats the idempotency protection.
Instead, generate a value that includes meaningful and immutable references to what's being paid. You could, for example, create a string like "client_123::employee_456::on_time_bonus_20250820". It's relatively easy to understand, references concrete data like "client" and "employee", and can be generated consistently again and again if needed, allowing the idempotency protection to do its job.