Payroll submission β user-friendly error messages
When payroll submission fails, Zenoti displays a plain-language error message on the payroll submission failure screen so you can identify the problem and take corrective action without interpreting raw system codes.
Audience: Payroll administrators and center managers who submit and monitor payroll.
On this page
Before you begin
You need the following permissions to submit payroll and view payroll reports:
Permission: View (under General Settings) β Required to view the employee list and search employees. The employee list also opens for roles that have Add General Settings or Delete on the Employee row, Edit on the General Settings row, or View All or Edit on the Commission Settings row. If the role has View Self on the Commission Settings row but neither View All nor Edit, the list shows only the signed-in employee. Grant it on the General Settings row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Attendance (under View Employee Reports) β Required to view attendance report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Payroll (under View Employee Reports) β Required to view payroll report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Commission (under View Employee Reports) β Required to view commission report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Performance (under View Employee Reports) β Required to view performance report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Sales (under View Employee Reports) β Required to view sales report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Tasks (under View Employee Reports) β Required to view task report data. Grant it on the View Employee Reports row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: View (under Payroll Plan) β Required to see the commission plans listing page and view plan details. Grant it on the Payroll Plan row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Permission: Schedule (under Other Settings) β Required to view and print employee schedules for the center. Grant it on the Other Settings row in the Employee Manager section of the security role (Configuration > Security > Security roles > the role > Permissions).
Before submitting payroll, confirm that:
- Pay periods are configured for the center.
- Employee attendance records are complete and reconciled for the pay period.
- Commission calculations have been run for the pay period.
How error messages work
When a payroll submission fails, Zenoti evaluates the error condition and displays a message on the payroll submission failure screen. The message is chosen as follows:
- If the error matches a known error type, Zenoti displays the specific user-facing message mapped to that error.
- If the error does not match a known type but a raw message is available from the payroll provider, Zenoti displays that raw message directly.
- If neither a mapped message nor a raw provider message is available, Zenoti displays the generic fallback message: "Payroll submission failed. Please review and resubmit."
This hierarchy ensures you always see the most actionable information available.
Error types and what they mean
The following table describes the distinct error conditions that Zenoti maps to specific user-facing messages on the payroll submission failure screen.
| Error condition | What it means | Recommended action |
|---|---|---|
| Billing or compliance issue with the organization account | The organization's account has an unresolved billing or compliance issue that is preventing payroll from being processed. This appears as a distinct, actionable failure state. | Contact your account administrator to resolve the outstanding billing or compliance issue before resubmitting payroll. |
| Other mapped error types | Zenoti maps additional known error conditions to specific messages. | Review the message displayed on the failure screen and follow the instructions provided. |
| Unmapped error with provider message | The error is not one of the recognized types, but the payroll provider returned a message. | Review the provider message for details. Address the issue described, then resubmit. |
| No message available | The error is unrecognized and no provider message is available. | Review payroll data for completeness and accuracy, then resubmit. If the problem persists, contact your administrator. |
Important: The billing or compliance error condition β sometimes described as an account not being in good standing β is surfaced as a distinct failure state on the payroll submission screen. It requires resolution at the account level before payroll can proceed. Do not attempt to resubmit payroll until the underlying account issue is resolved.
Steps
Review a payroll submission failure
- Navigate to Employee > Payroll.
- Initiate or locate the payroll submission for the relevant pay period.
- If submission fails, the payroll submission failure screen appears automatically.
- Read the error message displayed on the screen:
- If the message describes a specific issue (such as a billing or compliance problem), follow the instructions in the message before resubmitting.
- If the message is the generic fallback β "Payroll submission failed. Please review and resubmit." β review the steps in the Troubleshooting section below.
- After resolving the identified issue, return to the payroll submission screen and resubmit.
Resolve a billing or compliance error
- On the payroll submission failure screen, confirm that the error message indicates a billing or compliance issue with the organization account.
- Do not resubmit payroll until the account issue is resolved β resubmission will fail again.
- Contact your organization administrator or account representative to identify and resolve the outstanding billing or compliance issue.
- Once the account is confirmed to be in good standing, return to Employee > Payroll and resubmit the payroll for the affected pay period.
Worked example: Your organization submits payroll for the bi-weekly period ending June 14. The submission fails and the failure screen displays a message indicating an unresolved billing issue. You contact your administrator, who confirms that a payment method on file expired on June 1. After the administrator updates the payment method and the account is restored to good standing, you return to Employee > Payroll, select the June 14 pay period, and resubmit successfully.
Tips
- Check the failure screen message before resubmitting. Resubmitting without addressing the root cause will result in the same failure. Read the full message and act on it first.
- Billing and compliance errors require account-level resolution. These cannot be resolved by editing payroll data. Escalate to your organization administrator immediately.
- Raw provider messages contain actionable details. If Zenoti displays a message from the payroll provider rather than a generic fallback, the provider message typically identifies the specific data or configuration issue. Use it as your starting point for investigation.
- Use the generic fallback as a signal to audit payroll data. If you see "Payroll submission failed. Please review and resubmit," verify that attendance records, commission calculations, and pay period configuration are complete and accurate before resubmitting.
- Confirm pay period configuration before submission. Missing or misconfigured pay periods are a common cause of submission failures. Verify pay period settings at Configuration > Employee > Payroll and commissions > Payroll controls before submitting.
Troubleshooting
The failure screen shows the generic fallback message and I cannot identify the cause.
The generic message appears when no specific error type or provider message is available. Check the following in order:
- Confirm that the pay period is correctly configured for the center.
- Verify that commission calculations have been completed for the pay period.
- Confirm that all employee attendance records for the pay period are saved and reconciled.
- Check that no payroll lock is active for the period you are trying to submit.
After addressing each item, resubmit payroll.
The failure screen shows a billing or compliance error, but I resolved the account issue and the error persists.
Account status changes may take a short time to propagate. Wait a few minutes after the account issue is confirmed resolved, then attempt resubmission. If the error continues, contact your organization administrator to confirm the account is fully restored before resubmitting.
The failure screen shows a raw provider message I do not recognize.
Raw provider messages are passed through directly from the payroll provider when the error does not match a known type. Copy the exact message text and share it with your organization administrator or payroll provider contact for interpretation. Do not modify payroll data based on an uninterpreted message.