This is a staging build of the docs. Do not share the link externally.
Skip to main content

Record payroll

Sync payruns with your customers accounting software

Generate payroll object​

Before you can record the payroll in the accounting platform, you'll need to generate a line item object for each employee for each corresponding payroll component. That means you'll likely have multiple line items for each employee.

Each line item object should have the following information:

  • description - a title such as the month of the payroll or payrun
  • accountRef - The corresponding account
  • netAmount - Net amount paid to employee
  • currency - The currency corresponding to the amount
  • tracking - A list of references to records for tracking

Record payroll​

Steps:

In order to record payroll entries in the accounting platform, you can use the create journal entries endpoint to push payroll to the mapped accounts on the SMB's general ledger.

The journal entry can then be reconciled against the debit entry in the companies bankfeeds.

Get Journal push model​

Before creating a journalEntry - you should first check the datamodel, This helps you ensure all required properties are included in your request.

Checking the model may be a one-time activity (for integrations with static properties) or be required more frequently (for ERP integrations with higher customization options).

Let's use our Get create journalEntries model endpoint to view integration-specific requirements for creating the journalEntries data type in Xero.

GET https://api.codat.io/companies/{companyId}/connections/{connectionId}/options/journalEntries

The response indicates that the following properties must be populated (requried: true) when you create a journalEntry to represent payroll in Xero:

  • postedOn
  • journalLines which also require the following sub properties
    • description
    • netAmount
    • accountRef
    • tracking

Creating a payroll entry​

Properties not in the Get model response

If you attempt to create or update a record using properties not documented in the Get journalEntries model response, you may receive validation errors in response to your request.

When creating the payroll Journal Entry, you should create a line item for each payroll component, and the sum of the amounts on the payroll component should be equal to the sum of the debit on the mapped bank account that the payment is being made from.

in the example below, there are five journalEntry line's:

  1. The first line credits(increases the balance) of the "Payroll Wage Expenses" by $7,291.67
  2. The second line credits the "Payroll Tax Payable" account by $452.08
  3. The third line credits the "Payroll Expenses 401k" account by $1166.67
  4. The fourth line debits(reduces the balance) the "Checking" account by $8,910.42, the debit against the bank account should equal the sum of the payroll components.
Create journal entries
POST https://api.codat.io/companies/{companyId}/connections/{connectionId}/push/journalEntries

When you make the request, you will receive a pushOperation response, this will include the following information:

  • pushOperationKey: a unique idempotent identifier generated by Codat to represent this single pushOperation that can be used to track its status
  • dataType: the type of data being created, in this case, journalEntry
  • status: the status of the create operation, which can be Pending, Failed, Success or TimedOut
  • requestedOnUtc: the datetime (in UTC) when the operation was requested
  • completedOnUtc: the datetime (in UTC) when the operaion was completed, null if Pending
  • validation: a human-readable object that contains validation details, including errors, encountered during the operation.
  • changes: an array that communicates which record has changed (recordRef property) and the manner in which it changed (type property that can be Unknown, Created, Modified, or Deleted)

Monitoring the status of the request​

After your request has been accepted, it will have a status of Pending. You should use the PushOperationStatusChanged event type to track when the status of your pushOperation changes to Success or Failed.

If you want to see a history of all pushOperations for your company, you can retrieve these from the list-push-operations endpoint.

Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits