Snapbooks logo Snapbooks Developer

Default Payroll Lines

Default payroll lines define recurring salary components for employees. When a new payroll run is created, these default lines are automatically included for the relevant employees. This eliminates the need to manually enter the same salary components each pay period.

Endpoints

Method Endpoint Description
GET /payroll/default-lines List default payroll lines
GET /payroll/default-lines/{id} Get a default payroll line
POST /payroll/default-lines Create a default payroll line
PUT /payroll/default-lines/{id} Update a default payroll line
DELETE /payroll/default-lines/{id} Deactivate a default payroll line

List Default Payroll Lines

GET /api/v2/payroll/default-lines

Retrieves a paginated list of default payroll lines. Results are ordered by sort_order and then by id. The item_type relation is included by default.

Query Parameters

Parameter Type Required Description
client_account_id integer Yes ID of the client account
business_partner_id integer No Filter by employee (business partner) ID
is_active boolean No Filter by active status

Response

{
  "data": [
    {
      "id": 1,
      "created_by_id": 7,
      "created_at": "2024-03-15T10:00:00Z",
      "client_account_id": 7,
      "business_partner_id": 56,
      "item_type_id": 1,
      "description": "Monthly salary",
      "quantity": null,
      "rate": null,
      "amount": "45000.000000",
      "sort_order": 10,
      "is_active": true,
      "item_type": {
        "id": 1,
        "code": "FAST_LONN",
        "name_nob": "Fastloenn",
        "name_eng": "Fixed salary",
        "category": "EARNING"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "per_page": 25,
    "records": 1
  }
}

Get a Default Payroll Line

GET /api/v2/payroll/default-lines/{id}

Retrieves a single default payroll line by its ID. The item_type relation is included by default.

Path Parameters

Parameter Type Description
id integer The default payroll line ID

Create a Default Payroll Line

POST /api/v2/payroll/default-lines

Creates a new default payroll line for an employee.

Request Body

Field Type Required Description
client_account_id integer Yes The client account ID
business_partner_id integer Yes The employee (business partner) ID
item_type_id integer Yes The payroll item type ID
description string No Line description
quantity decimal No Quantity (e.g. hours per period)
rate decimal No Rate (e.g. hourly rate)
amount decimal Yes Amount per pay period
sort_order integer No Display order (defaults to 0)
is_active boolean No Whether the line is active (defaults to true)

Example Request

{
  "client_account_id": 7,
  "business_partner_id": 56,
  "item_type_id": 1,
  "description": "Monthly salary",
  "amount": "45000.00",
  "sort_order": 10
}

Response

Returns the created default payroll line with status 201 Created.

Validation Rules

  • The business_partner_id must belong to the specified client_account_id.
  • The item_type_id must reference a valid payroll item type.
  • The item type must not have is_auto_calculated set to true. Auto-calculated item types (e.g. tax withholding, employer contributions) cannot be used as default lines.

Update a Default Payroll Line

PUT /api/v2/payroll/default-lines/{id}

Updates an existing default payroll line.

Updatable Fields

Field Type Description
item_type_id integer The payroll item type ID
description string Line description
quantity decimal Quantity
rate decimal Rate
amount decimal Amount per pay period
sort_order integer Display order
is_active boolean Whether the line is active

Note: client_account_id and business_partner_id cannot be changed after creation.

Response

Returns the updated default payroll line.

Deactivate a Default Payroll Line

DELETE /api/v2/payroll/default-lines/{id}

Soft-deletes a default payroll line by setting is_active to false. The record is not permanently deleted.

Response

Returns the deactivated default payroll line with is_active set to false.

Attributes

Attribute Type Description
id integer Unique identifier (read-only)
created_by_id integer ID of the creating user (read-only)
created_at datetime Creation timestamp (read-only)
client_account_id integer Client account ID (set on creation, read-only after)
business_partner_id integer Employee (business partner) ID (set on creation, read-only after)
item_type_id integer Payroll item type ID
description string Line description
quantity decimal Quantity (e.g. hours per period)
rate decimal Rate (e.g. hourly rate)
amount decimal Amount per pay period
sort_order integer Display order
is_active boolean Whether the line is active

Relationships

The following related objects can be included using the with parameter:

  • item_type - The payroll item type definition (included by default)
  • business_partner - The employee

Error Responses

Status Code Description
400 Invalid request (business partner not in client account, invalid item type, or auto-calculated item type)
403 Forbidden (no access to client account)
404 Default payroll line not found