Skip to main content

​
Introduction

Business Presets are a Nmbr feature that allow you to
  • define a reusable set of properties for entities including allowances, deductions, earnings, employee and employer benefits, reimbursements, pay rates, overtime rates, and line items
  • apply those properties to many entities
  • ensure the values of those properties can only be changed through the preset and not through the entity
  • group line items consistently for reporting purposes

​
Supported Properties

Business Presets currently support the following properties:
  • name: The name of the preset. The preset name is displayed in the component when listing or selecting presets. The name may also be displayed on pay stubs or reports when line items are grouped by preset, as the line items may have different title values.
  • type: The type of entity the preset can be applied to.
    type must be one of
    • earning (for earnings, pay rates, overtime rates, and earning line items)
    • allowance
    • employee_benefit
    • employer_benefit
    • deduction
    • reimbursement
  • subtype: The sub-type of entity the preset can be applied to.
    If not set, the preset can be applied to any recurrence or line item of the specified type. If set, subtype must be one of the type values for the specified type. For example:
    • If type is earning, subtype must be an earning type (salary, wage, etc)
    • If type is allowance, subtype must be an allowance type (taxable_cash_allowance, automobile_and_motor_vehicle, etc).
    • etc
    ⚠️ Pay rates and earning line items have different type values for hourly wages. Pay rates use the value hourly while earning line items use wage. Presets use the earning line item type, i.e. wage. ⚠️ Overtime rates don’t have their own type. An overtime rate’s preset must be of the same type as the overtime rate’s pay rate.
  • label: The label to apply to the entity.
  • remittance_account_id: The remittance account to sync to the entity.
    ⚠️ Only benefit and deduction types have remittance accounts. Other types will ignore this property.
  • expense_accounting_code_id and liability_accounting_code_id: The accounting codes to sync to the entity.

​
Usage

​
Creating Business Presets

Business Presets are created as follows: 
POST /services/payroll/business_presets

{
  "type": "allowance",
  "subtype": "automobile_and_motor_vehicle",
  "name": "Car Allowance (2025 mid-year)",
  "label": "Car Allowance",
  ...other Business Preset properties...
}

​
Creating entities with Business Presets

A new entity can be created with a Business Preset by including the business_preset_id property in the create request. For example, when creating an allowance: 
POST /services/payroll/allowances

{
  "business_preset_id": "<id>",
  ...other allowance properties...
}
Any property values set on the Business Preset will be copied to the newly-created entity.

​
Adding a Business Preset to an existing entity

An existing entity can have a Business Preset added to it by including the business_preset_id property in an update request. For example, when updating an allowance: 
PUT /services/payroll/allowances/alw_01K2Q0T546RAHGJHV9WNWNE4GW

{
  "business_preset_id": "<id>",
}
Any property values set on the Business Preset will be copied to the updated entity, overwriting the existing values for those properties on the entity.

​
Removing a Business Preset from an existing entity

An existing entity can have a Business Preset removed from it by including the business_preset_id property in an update request with the value null. For example, when updating an allowance: 
PUT /services/payroll/allowances/alw_01K2Q0T546RAHGJHV9WNWNE4GW

{
  "business_preset_id": null,
}
Any properties values previously copied from the Business Preset will remain on the updated entity, but will become editable and will no longer be synced from the Business Preset.

​
Updating Business Presets

Business Presets are updated as follows: 
PUT /services/payroll/business_presets/<id>

{
  "label": "Vehicle Allowance",
  ...other Business Preset properties...
}
ℹ️ The type and subtype properties can’t be updated as they could change the types of entities that can be associated with the preset, invalidating entities already associated with the Business Preset. The updated values will cascade down from the Business Preset to the entities associated with it automatically. ℹ️ Line items on non-draft payrolls will not be updated as this would change historical pay stubs and remittances. All updated values will cascade down from the Business Preset to associated entities, keeping the entities in-sync with the Business Preset.

​
Deleting Business Presets

Business Presets are deleted as follows: 
DELETE /services/payroll/business_presets/<id>
By default, deleting a Business Preset will keep any values synced from the Business Preset to associated entities. An optional keep_existing_values query string parameter can be supplied to control this behavior.
keep_existing_valuesBehavior
all (default)Keep all existing values on associated entities. Don’t clear any values.
noneDon’t keep any existing values on associated entities. Clear all values.
After the Business Preset is deleted, previously associated entities will be fully editable.