Sending Pay to Everee

Choose the right API for each kind of earning, and follow it from submission to the worker being paid.

Everee pays workers for the earnings you send it. This guide helps you choose the right API for each kind of earning, shows what a typical submission looks like, and explains what happens between you sending an amount and the worker getting paid.

📘

Payroll Infrastructure

This guide is for hosted payroll. In Payroll Infrastructure, you add each worker's pay to a payroll run as items instead: see Running payroll. Creating payable items, shifts or classified hours for a Payroll Infrastructure company returns 400.

Before you start, workers need to exist and be onboarded. See Onboarding and managing workers. For the whole contractor flow in one place, see Onboarding and paying contractors.


Which API should I use?

It depends on who's being paid, and what you know about the amount.

You're paying...You have...UsePaid
An hourly employeePunch times for each shift, with breaks if you track themCreate a shift in the Timesheets APIOn the employee's regular payroll cycle
An hourly employeeHours already classified as regular, overtime, and double time for a pay periodUpdate classified hours in the Timesheets APIOn the employee's regular payroll cycle
An employeeA flat amount: bonus, commission, stipend, per diem, reimbursementCreate a payable item in the Payables APIOn the employee's regular payroll cycle, or as soon as possible
A contractorAny amount for services or reimbursementCreate a payable item in the Payables API, then request payoutAs soon as possible

Hourly wages always go through the Timesheets API, even when you've already classified the hours, because overtime and other hourly rules affect how wages are calculated and shown on the pay stub. Payables is for everything else.

The Timesheets API is covered in Time and attendance. The rest of this guide covers payable items, and what's common to both.


How pay flows through Everee

StepWhat happens
1. You sendShifts, classified hours, or payable items
2. Everee holdsThem until the pay period closes, or until you ask for payout
3. PaymentsEveree calculates gross-to-net and creates a payment per worker
4. ApprovalPayroll is approved by a payroll admin in the Everee admin portal, or automatically if the company uses auto-approval
5. FundingEveree funds the payments and pays the workers
6. You're toldThe payment.paid webhook arrives, and you can pull payment data for reconciliation
📘

No money moves until payroll is approved

Creating a shift or payable item, and even requesting payout, doesn't transact anything. Every payment pauses for a payroll admin's approval. Auto-approval is off by default, and Everee can turn it on when you ask. That means it's safe to send amounts early and often, and to build and test against a production-like setup.

How fast a worker gets the money after approval depends on how they're paid. Everee pays by direct deposit, or by the Everee Pay Card, which can be paid instantly.


Paying flat amounts with payable items

A payable item is one amount for one worker, under a pay code. You provide the amount, because payable amounts are often calculated by rules Everee doesn't manage.

POST https://api.everee.com/integration/v1/payables

{
  "externalId": "client_123::emp-1042::on_time_bonus_20261016",
  "externalWorkerId": "emp-1042",
  "label": "On-time bonus, October",
  "payableModel": "PRE_CALCULATED",
  "payCode": "BONUS",
  "type": "bonus",
  "amount": { "amount": 150.00, "currency": "USD" },
  "earningTimestamp": 1792000000,
  "workLocationId": 1234,
  "costCenters": [{ "type": "clientId", "value": "290" }]
}
  • externalId is an idempotency key. It must be unique within the company. Send the same one again and Everee updates the payable if its payment hasn't been approved yet, or rejects the request if it has. Build it from stable data, like a client, a worker, and a date, and never from a timestamp or random value. See Guide to the Payables API for why this matters.
  • earningTimestamp is when the amount was earned, as a Unix timestamp in seconds. The older timestamp field is deprecated. It takes a date and time without an offset, such as 2026-10-27T09:16:42, which Everee reads as UTC.
  • payCode is a default pay code like BONUS, COMMISSION, REIMBURSEMENT, or CONTRACTOR, or the apiKey of one of your own. List pay codes returns every pay code available to your company, including the pay codes of your leave types. Use those to pay out leave.
  • workLocationId decides the tax jurisdiction for an employee's wages. If you leave it out, the worker's default work location is used.
  • costCenters tag the amount so you can allocate costs later. See Reconciling payroll and posting to your GL.
  • To send many at once, use Create payables (bulk). Everee can report every failing payable in one response, and saves none unless all are valid. See Errors in bulk requests.

Employees and contractors are paid differently

EmployeesContractors
Included in regular payroll automaticallyYesNo
Paid as soon as possibleIf you askWhen you ask, or as each payable is created if your company processes them automatically

Employees. Do nothing more. Payable items are included in the employee's next regular payroll payment.

Contractors. Contractors don't have a regular payroll cycle, so nothing is paid until their payables are processed. Either you call Request ASAP payout, or Everee processes each payable as you create it, if your company has automatic processing turned on. See Onboarding and paying contractors.

If you request payout, call it after you've sent all of a contractor's payable items and before payments are approved. If you call it too early, items you send afterward wait for the next payout request. If you call it after approval, the items miss that run.

POST https://api.everee.com/integration/v1/payables/payment-request

{}

With no parameters, the request processes every unpaid payable item of your contractors, and leaves employees' items for their regular payroll. That's what most integrations want. To limit it, send externalIds, workerIds, or externalWorkerIds.

Paying as soon as possible

To pay an employee's payable item without waiting for payroll, use the same payout request, with includeWorkersOnRegularPayCycle set to true. The items are processed into payments separate from regular payroll. They're approved separately, and once approved they're locked and won't be paid again in the next regular payroll.

This suits items like expense reimbursements and advances. Whether it's right for you depends on your workflow, your workers' expectations, and cash flow, so limit the request to specific payables with externalIds, or to specific workers, rather than turning it on for everyone.


Following a payment to the end

Know when someone is paid

Subscribe to these webhook events instead of polling:

EventMeaning
payment.paidA worker's payment has been submitted for deposit. It lists the shifts and payables included, and gross and net amounts
payment-payables.status-changedThe payables in a payment are now PAID, or are blocked in ERROR
payment.deposit-returnedThe worker's bank returned the deposit, usually because of an incorrect account or routing number

A returned deposit isn't the end of the story. The worker is asked to fix their bank details, and Everee retries the deposit under the same paymentId. A payable stays PAID throughout, so use the events to follow the outcome. See Returned deposits and retries.

Check where a payable is

Reconcile

Once a pay date has finished processing, retrieve its payments to tie out wages, taxes, and net pay to your own records. See Reconciling payroll and posting to your GL.


Changing or removing an amount

You can change or remove a payable until the payment that includes it is approved. A payment is approved by a payroll admin in the admin portal, or automatically if the company uses auto-approval. Requesting a payout doesn't lock a payable.

After approval, and at every later stage, changing or deleting the payable without authorization is rejected with a 400: "A payment has already been processed for the payable with 'externalId' value '...'. It cannot be updated or deleted."

To...Do this
Change a payable that isn't approved yetSend it again with the same externalId, or update it
Remove a payable that isn't approved yetDelete it, or delete many
Change a payable whose payment has been approvedSend it again with correction-authorized=true. Without that, the request is rejected
Remove a payable whose payment has been approvedDelete it with correction-authorized=true. Without that, the request is rejected
Change timesheet hours that have been paidUse the Timesheets endpoints with correction-authorized=true. See Time and attendance

Corrections adjust a worker's pay after the fact, which is why you have to opt into them each time. An unintended correction can't be sent by accident. How quickly a correction pays out depends on whether the ACH deadline, 11 a.m. Mountain Time, has been reached when its payment is approved. A correction approved before the deadline goes out sooner than one approved after it. Corrections have no specific fee of their own. Any additional payment a correction produces, such as one that pays an underpayment, may be billed at a per-payment fee.


Loading payables from a file

Everee supports drag and drop upload of payables, and of hours, in the Everee admin portal. A payroll admin can use it to load amounts from a file when they can't come through the API.


Common mistakes

  • Paying hourly employees with payables. Send hours to the Timesheets API, so overtime and pay stub rules apply.
  • A random externalId. A retry then creates a duplicate and the worker is paid twice.
  • Forgetting the payout request for contractors. Unless your company processes payables automatically, their payables sit unpaid.
  • Not setting workLocationId. The amount is taxed using the worker's default location, which may not be where they worked.
  • Polling for payment status. Use payment.paid.

When a call fails and you can't see why, see Diagnosing a failed request.


Next steps


Did this page help you?