Payroll Items

Payroll items are the earnings and deductions catalog used when configuring Payroll — every allowance, benefit, or deduction that can be applied to an employee's pay is defined here as a reusable item, along with its limit rules and ledger treatment. Access to this module is restricted to the Super Admin or Payroll Admin role.

The payroll item model

The payroll item model contains the name, category, code, and limit configuration for each earning or deduction, along with its linked account code and ledger/tax treatment flags.

Properties

Name
id
Type
string
Description
Unique UUID identifier for the payroll item.
Name
name
Type
string
Description
The payroll item's display name.
Name
category
Type
string
Description
The payroll item category. e.g. earning or deduction.
Name
code
Type
string
Description
Unique code identifying the payroll item.
Name
description
Type
string | null
Description
Description of the payroll item. Optional.
Name
account_code_id
Type
string | null
Description
UUID of the linked account code. Optional.
Name
account_code
Type
object | null
Description
The linked account code object, present when the accountCode relation is loaded. Contains id, name, expense_class, old_account_code, new_account_code, created_at, and updated_at.
Name
order_column
Type
integer
Description
Sort order used to order payroll items within the catalog.
Name
has_limit
Type
boolean
Description
Whether this payroll item is subject to a limit.
Name
limit_type
Type
string | null
Description
The type of limit applied. e.g. fixed_amount or percentage. Optional.
Name
limit_amount
Type
float | null
Description
The fixed limit amount, present when limit_type is fixed_amount. Optional.
Name
limit_percentage
Type
number | null
Description
The limit percentage, present when limit_type is percentage. Optional.
Name
limit_frequency
Type
string | null
Description
How often the limit resets. e.g. monthly or annually. Optional.
Name
limit_basis_payroll_item_id
Type
string | null
Description
UUID of the payroll item that the percentage limit is based on. Optional.
Name
limit_basis_payroll_item
Type
object | null
Description
The payroll item the percentage limit is based on, present when loaded. Contains id, name, and code.
Name
is_de_minimis
Type
boolean
Description
Whether the payroll item is treated as a de minimis benefit.
Name
is_taxable
Type
boolean
Description
Whether the payroll item is subject to tax.
Name
is_ledger_excluded
Type
boolean
Description
Whether the payroll item is excluded from the ledger.
Name
created_at
Type
timestamp
Description
Timestamp when the payroll item was created.
Name
updated_at
Type
timestamp
Description
Timestamp when the payroll item was last updated.

GET/payroll/payroll_items

List all payroll items

This endpoint allows you to retrieve a paginated list of all payroll items. By default, a maximum of 50 payroll items are shown per page, ordered by name.

Optional attributes

Name
filter[account_code_id]
Type
string
Description
Filter payroll items by an exact match on account code UUID.
Name
filter[category]
Type
string
Description
Filter payroll items by an exact match on category, e.g. earning or deduction.
Name
filter[payroll_type_id]
Type
string
Description
Filter payroll items linked to a given payroll type UUID.
Name
filter[search]
Type
string
Description
Search payroll items by name or code.

Request

GET

/payroll/payroll_items

curl https://your-domain.com/api/payroll/payroll_items \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie"

Response

{
  "data": [
    {
      "id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901",
      "name": "13th Month Pay",
      "category": "earning",
      "code": "13TH-MONTH",
      "description": "Statutory 13th month pay benefit.",
      "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
      "account_code": {
        "id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
        "name": "13th Month Pay Expense",
        "expense_class": "Personnel Services",
        "old_account_code": "5-01-02-030",
        "new_account_code": "50102030",
        "created_at": "2025-11-02T08:00:00+00:00",
        "updated_at": "2025-11-02T08:00:00+00:00"
      },
      "order_column": 1,
      "has_limit": true,
      "limit_type": "fixed_amount",
      "limit_amount": 90000.00,
      "limit_percentage": null,
      "limit_frequency": "annually",
      "limit_basis_payroll_item_id": null,
      "limit_basis_payroll_item": null,
      "is_de_minimis": false,
      "is_taxable": false,
      "is_ledger_excluded": false,
      "created_at": "2025-11-02T08:00:00+00:00",
      "updated_at": "2025-11-02T08:00:00+00:00"
    },
    {
      "id": "3d4e5f60-7182-93a4-b5c6-d7e8f9011223",
      "name": "SSS Contribution",
      "category": "deduction",
      "code": "SSS-EE",
      "description": "Employee share of monthly SSS contribution.",
      "account_code_id": null,
      "account_code": null,
      "order_column": 2,
      "has_limit": true,
      "limit_type": "percentage",
      "limit_amount": null,
      "limit_percentage": 4.5,
      "limit_frequency": "monthly",
      "limit_basis_payroll_item_id": "4e5f6071-8293-a4b5-c6d7-e8f901122334",
      "limit_basis_payroll_item": {
        "id": "4e5f6071-8293-a4b5-c6d7-e8f901122334",
        "name": "Basic Pay",
        "code": "BASIC"
      },
      "is_de_minimis": false,
      "is_taxable": false,
      "is_ledger_excluded": true,
      "created_at": "2025-11-02T08:05:00+00:00",
      "updated_at": "2025-11-02T08:05:00+00:00"
    }
  ],
  "links": {
    "first": "https://your-domain.com/api/payroll/payroll_items?page=1",
    "last": "https://your-domain.com/api/payroll/payroll_items?page=3",
    "prev": null,
    "next": "https://your-domain.com/api/payroll/payroll_items?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 50,
    "to": 50,
    "total": 124
  }
}

POST/payroll/payroll_items

Create a payroll item

This endpoint allows you to create a new payroll item.

Required attributes

Name
name
Type
string
Description
The payroll item's name. Must be between 1 and 100 characters.
Name
category
Type
string
Description
The payroll item category. Must be one of the payroll item category enum values, e.g. earning or deduction.
Name
code
Type
string
Description
Unique code identifying the payroll item.
Name
limit_type
Type
string
Description
The type of limit applied. Must be one of the limit type enum values, e.g. fixed_amount or percentage.
Name
limit_frequency
Type
string
Description
How often the limit resets. Must be one of the limit frequency enum values, e.g. monthly or annually.

Optional attributes

Name
description
Type
string
Description
Description of the payroll item.
Name
account_code_id
Type
string
Description
UUID of an existing account code to link to this payroll item.
Name
has_limit
Type
boolean
Description
Whether this payroll item is subject to a limit.
Name
limit_amount
Type
number
Description
The fixed limit amount. Required when limit_type is fixed_amount.
Name
limit_percentage
Type
number
Description
The limit percentage, between 0 and 100. Required when limit_type is percentage.
Name
limit_basis_payroll_item_id
Type
string
Description
UUID of another payroll item that the percentage limit is based on. Required when limit_type is percentage.
Name
is_de_minimis
Type
boolean
Description
Whether the payroll item is treated as a de minimis benefit.
Name
is_taxable
Type
boolean
Description
Whether the payroll item is subject to tax.
Name
is_ledger_excluded
Type
boolean
Description
Whether the payroll item is excluded from the ledger.

Request

POST

/payroll/payroll_items

curl -X POST https://your-domain.com/api/payroll/payroll_items \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "name": "Rice Subsidy",
    "category": "earning",
    "code": "RICE-SUB",
    "description": "Monthly rice subsidy allowance.",
    "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
    "has_limit": true,
    "limit_type": "fixed_amount",
    "limit_amount": 2000.00,
    "limit_frequency": "monthly",
    "is_de_minimis": true,
    "is_taxable": false,
    "is_ledger_excluded": false
  }'

Response

{
  "data": {
    "id": "5f607182-93a4-b5c6-d7e8-f90112233445",
    "name": "Rice Subsidy",
    "category": "earning",
    "code": "RICE-SUB",
    "description": "Monthly rice subsidy allowance.",
    "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
    "account_code": {
      "id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
      "name": "13th Month Pay Expense",
      "expense_class": "Personnel Services",
      "old_account_code": "5-01-02-030",
      "new_account_code": "50102030",
      "created_at": "2025-11-02T08:00:00+00:00",
      "updated_at": "2025-11-02T08:00:00+00:00"
    },
    "order_column": 125,
    "has_limit": true,
    "limit_type": "fixed_amount",
    "limit_amount": 2000.00,
    "limit_percentage": null,
    "limit_frequency": "monthly",
    "limit_basis_payroll_item_id": null,
    "limit_basis_payroll_item": null,
    "is_de_minimis": true,
    "is_taxable": false,
    "is_ledger_excluded": false,
    "created_at": "2026-07-24T09:15:00+00:00",
    "updated_at": "2026-07-24T09:15:00+00:00"
  }
}

GET/payroll/payroll_items/{id}

Get a payroll item

This endpoint allows you to retrieve a single payroll item by its UUID, including its linked account code.

Path parameters

Name
payroll_item
Type
string
Description
The UUID of the payroll item to retrieve.

Request

GET

/payroll/payroll_items/{id}

curl https://your-domain.com/api/payroll/payroll_items/1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901 \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie"

Response

{
  "data": {
    "id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901",
    "name": "13th Month Pay",
    "category": "earning",
    "code": "13TH-MONTH",
    "description": "Statutory 13th month pay benefit.",
    "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
    "account_code": {
      "id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
      "name": "13th Month Pay Expense",
      "expense_class": "Personnel Services",
      "old_account_code": "5-01-02-030",
      "new_account_code": "50102030",
      "created_at": "2025-11-02T08:00:00+00:00",
      "updated_at": "2025-11-02T08:00:00+00:00"
    },
    "order_column": 1,
    "has_limit": true,
    "limit_type": "fixed_amount",
    "limit_amount": 90000.00,
    "limit_percentage": null,
    "limit_frequency": "annually",
    "limit_basis_payroll_item_id": null,
    "limit_basis_payroll_item": null,
    "is_de_minimis": false,
    "is_taxable": false,
    "is_ledger_excluded": false,
    "created_at": "2025-11-02T08:00:00+00:00",
    "updated_at": "2025-11-02T08:00:00+00:00"
  }
}

PUT/payroll/payroll_items/{id}

Update a payroll item

This endpoint allows you to update an existing payroll item. It accepts the same body as the create endpoint. The code uniqueness check ignores the current record.

Path parameters

Name
payroll_item
Type
string
Description
The UUID of the payroll item to update.

Required attributes

Name
name
Type
string
Description
The payroll item's name. Must be between 1 and 100 characters.
Name
category
Type
string
Description
The payroll item category. Must be one of the payroll item category enum values, e.g. earning or deduction.
Name
code
Type
string
Description
Unique code identifying the payroll item (uniqueness check ignores this record).
Name
limit_type
Type
string
Description
The type of limit applied. Must be one of the limit type enum values, e.g. fixed_amount or percentage.
Name
limit_frequency
Type
string
Description
How often the limit resets. Must be one of the limit frequency enum values, e.g. monthly or annually.

Optional attributes

All optional attributes from the create endpoint are also accepted here: description, account_code_id, has_limit, limit_amount, limit_percentage, limit_basis_payroll_item_id, is_de_minimis, is_taxable, and is_ledger_excluded.

Request

PUT

/payroll/payroll_items/{id}

curl -X PUT https://your-domain.com/api/payroll/payroll_items/1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie" \
  -d '{
    "name": "13th Month Pay",
    "category": "earning",
    "code": "13TH-MONTH",
    "description": "Statutory 13th month pay benefit, tax-exempt up to the ceiling.",
    "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
    "has_limit": true,
    "limit_type": "fixed_amount",
    "limit_amount": 90000.00,
    "limit_frequency": "annually",
    "is_de_minimis": false,
    "is_taxable": false,
    "is_ledger_excluded": false
  }'

Response

{
  "data": {
    "id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901",
    "name": "13th Month Pay",
    "category": "earning",
    "code": "13TH-MONTH",
    "description": "Statutory 13th month pay benefit, tax-exempt up to the ceiling.",
    "account_code_id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
    "account_code": {
      "id": "2c3d4e5f-6071-8293-a4b5-c6d7e8f90112",
      "name": "13th Month Pay Expense",
      "expense_class": "Personnel Services",
      "old_account_code": "5-01-02-030",
      "new_account_code": "50102030",
      "created_at": "2025-11-02T08:00:00+00:00",
      "updated_at": "2025-11-02T08:00:00+00:00"
    },
    "order_column": 1,
    "has_limit": true,
    "limit_type": "fixed_amount",
    "limit_amount": 90000.00,
    "limit_percentage": null,
    "limit_frequency": "annually",
    "limit_basis_payroll_item_id": null,
    "limit_basis_payroll_item": null,
    "is_de_minimis": false,
    "is_taxable": false,
    "is_ledger_excluded": false,
    "created_at": "2025-11-02T08:00:00+00:00",
    "updated_at": "2026-07-24T09:30:00+00:00"
  }
}

DELETE/payroll/payroll_items/{id}

Delete a payroll item

This endpoint allows you to delete a payroll item.

Path parameters

Name
payroll_item
Type
string
Description
The UUID of the payroll item to delete.

Request

DELETE

/payroll/payroll_items/{id}

curl -X DELETE https://your-domain.com/api/payroll/payroll_items/1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901 \
  -H "Accept: application/json" \
  -H "X-XSRF-TOKEN: {xsrf_token}" \
  --cookie "mainframe_session=your-session-cookie"

Response

HTTP/1.1 204 No Content