> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# July 20, 2026 Release

# Async Payroll Imports and Pay Schedule Webhooks

This release makes payroll imports more scalable and gives integrators more visibility into pay schedule changes. Teams running larger payroll imports and partners building event-driven integrations benefit most.

# Highlights

* **Asynchronous payroll import:** `importRegularPayrollData` and `importDifferentialPayrollData` now validate immediately and process accepted imports in the background.
* **Pay schedule webhooks:** New events notify your systems when pay schedules are created or their status changes.
* **`$0` wage rate support:** Payroll import and wage workflows now support employee wage rates of `$0` where applicable.

# New Features

### 🔹 Asynchronous payroll imports

`importRegularPayrollData` and `importDifferentialPayrollData` both support an asynchronous completion flow.

* After request validation succeeds, the API returns a `Pending` response and continues applying payroll changes in the background instead of holding the request open until every payroll mutation finishes.

* During that import window, [getPayPeriodDetails](/api-reference/reports/getPayPeriodDetails) returns a `400` response so clients do not display stale payroll data while the import is still being applied.

* When the import finishes, Rollfi sends the `payperiod.payperiodstatus.update` webhook. That update does not introduce a new    completion status. Instead, it restores the pay period to the same status you observed before the import began, while signaling that background import processing has completed.

  * For example, if the pay period was `new` before the import started, the completion webhook will surface that pay period as `new` again. If it was `cancelled` before the import started, the completion webhook will surface `cancelled` again. In other words, the return to the prior visible pay period status is the signal that the async import window has closed and it is safe to re-fetch payroll details.

* When some employee-level mutations fail during async processing, the same `payperiod.payperiodstatus.update` webhook can include a top-level `error` object summarizing those failures.

Example completion webhook with partial failures:

```json theme={null}
{
    "trigger": {
        "eventId": "f1d8f4a9-8b6a-4de4-a07d-0f7c4f17b0e2",
        "eventType": "payperiod.payperiodstatus.update",
        "eventTimeStamp": "07/20/2026 14:37:11"
    },
    "payload": [
        // ... [PayPeriod payload omitted] ...
    ],
    "error": {
        "code": 400,
        "message": "Payroll changes not processed for 2 user(s) due to negative net pay",
        "userIds": [
            "A9275709-E4E0-476F-AE77-BD85F7BDEECD",
            "96069AD6-C3EB-476B-BD3E-E334270EEFA4"
        ]
    }
}
```

### 🔹 Pay schedule webhook events

* Your systems can now react automatically when pay schedules change. Two new webhook events are available:

  * `payschedule.paysheduleisactive.insert` — sent when a pay schedule is created.
  * `payschedule.paysheduleisactive.update` — sent when a pay schedule's status changes.

📝 Review the [PaySchedule webhook overview](/api-reference/webhooks/PaySchedule/overview) for payload details and delivery behavior.

### 🔹 Support for `$0` wage rates

Rollfi now supports employee wage rates of `$0`. This allows clients to onboard employees with commission only wage structures who do not require differential pay.

## ⚠️ Notes for Integrators

| Area           | Change                                                    | Action                                                                                                                                         |
| -------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Payroll import | `importRegularPayrollData` now completes asynchronously   | Update clients to handle `Pending` responses and re-fetch data after webhook notification                                                      |
| Wage handling  | `$0` wage rate is now supported in applicable flows       | Remove client-side constraints that block valid zero wage values                                                                               |
| Payroll reads  | `getPayPeriodDetails` returns `400` during active imports | Handle temporary read blocking and retry after import completion                                                                               |
| Webhooks       | New `PaySchedule` events                                  | Optional: subscribe and update webhook processing. Please reach out to support if you think your system will benefit from these webhook events |

If you consume webhooks with retries enabled, remember that events may be delivered more than once. Continue to use idempotent processing.

## Recommended Next Steps

1. Update any `importRegularPayrollData` client flow to handle `Pending` responses.
2. Avoid rendering payroll details until `getPayPeriodDetails` succeeds after import completion.
3. Review the [PaySchedule webhook overview](/api-reference/webhooks/PaySchedule/overview) if you build event-driven integrations that could benefit.