Payroll Processing Request

The processing_request object is returned by our Get a Single Payroll API endpoint and Prepare API endpoint to provide better visibility into whether a payroll is currently being calculated or submitted.

While payroll is being calculated or submitted, it is important that no additional payroll API calls are made to modify the payroll (This includes the prepare, update, calculate, and submit APIs). The processing_request object is returned by our GET companies/{company_id}/payrolls/{payroll_id} endpoint and the PUT companies/{company_uuid}/payrolls/{payroll_uuid}/prepare endpoint. This object provides better visibility into the status of the calculation or submission process. It also returns relevant error information if there is a failure.

1. processing_request Attribute

The processing_request attribute is included in the response for the GET companies/{company_id}/payrolls/{payroll_id} endpoint and the PUT companies/{company_uuid}/payrolls/{payroll_uuid}/prepare endpoint:

"processing_request": {  
	"status": "calculate_success",  
	"errors": []
}

Status values can be:

• calculating
• calculate_success
• submitting
• submit_success
• processing_failed

You will receive "processing_request": null if:

• You have not attempted to calculate or submit the payroll
  The calculate/submit process has not started yet. The calculation/submission is done asynchronously and generally starts within a couple seconds of a successful calculate/submit API request. This could take longer when many payrolls are being processed
• The calculation has been cleared out by a request to the PUT companies/{company_uuid}/payrolls/{payroll_uuid}/prepare endpoint.

2. Processing Failures

When processing fails we will return errors in the same format as our other API response errors. Here are the most common error responses you will see when processing fails

Employee net pay less than zero

"processing_request": {  
        "status": "processing_failed",  
        "errors": [  
            {  
                "error_key": "employee_compensations",  
                "category": "nested_errors",  
                "metadata": {  
                    "employee_uuid": "4f8d4b3c-dab0-4ede-b52c-857c34404629"  
                },  
                "errors": [  
                    {  
                        "error_key": "net_pay",  
                        "category": "invalid_attribute_value",  
                        "message": "Net pay must be greater than or equal to 0. This is likely occurring due to deductions, tax withholding for benefits, or additional tax withholding exceeding employee pay. Can modify these, add pay, or exclude employee from this payroll."  
                    }  
                ]  
            }  
	]  
}

Debit date no longer valid

"processing_request": {  
        "status": "processing_failed",  
        "errors": [  
            {  
                "error_key": "base",  
                "category": "invalid_attribute_value",  
                "message": "Payroll was not processed before deadline. Please recalculate payroll to get updated dates."  
            }  
	]  
}

Fallback error - If we are unable to map the error correctly we will return this error.

"processing_request": {  
        "status": "processing_failed",  
        "errors": [  
            {  
                "error_key": "base",  
                "category": "internal_error",  
                "message": "Something went wrong. Please try reprocessing and contact support if the issue persists."  
            }  
	]  
}