Previewing a payroll can be accomplished in two ways: synchronously (default) or asynchronously. Asynchronous preview is required if the payroll has more than 500 payroll items and contractor payments.

To preview asynchronously, set the async query parameter to true.

Note for Python clients: The async query parameter name is a reserved keyword in Python. When using a typed Python client, you may need to pass this parameter using dictionary unpacking or an alternative syntax supported by your HTTP library (e.g., params={"async": "true"}).

When the preview is initiated, the preview property on the Payroll object will be created with a status of calculating. After the preview is completed, it will move into succeeded.

{
  ...,
  "preview": {
    "status": "calculating",
    "started_at": "2019-06-29T18:26:56.848920Z"
  },
  ...
}

Previewing a payroll is required before the payroll can be approved. If the payroll or any associated Payroll Items or Contractor Payments are modified, then the preview calculation will no longer be valid, and the preview object on the payroll will be reset to null.