Employee Wages

Overview

Employee wage history tracks hourly rates and scheduled weekly hours over time. Each wage record has an effective date range, allowing historical tracking and future planning of compensation changes.

The system uses hourly rates to calculate payroll, overtime, and time-off compensation. Weekly scheduled hours are used for full-time equivalency calculations.

List Employee Wages

Retrieve all wage history records for a specific employee, ordered by effective date (most recent first).

Endpoint

GET /api/v1/employees/{id}/wages

Authentication

Authorization

string

required

Bearer token from OAuth2 authentication

Path Parameters

string

required

Employee public identifier (ULID format)Example: "01JKXYZ1234567890ABCDEFGH"

Response

status

integer

HTTP status code (200)

data

array

Array of wage history objects, ordered by effective_from descending (most recent first)

Show Wage History Object

string

Wage history public identifier (ULID)

employee_id

integer

Internal employee ID (for reference)

hourly_rate

number

Hourly wage rate in local currency. Must be greater than zero.Format: Decimal with 2 decimal placesExample: 125.00 (MXN per hour)

weekly_scheduled_hours

number

Scheduled weekly hours. Must be greater than zero.Format: Decimal with 2 decimal placesExample: 48.00 (full-time in Mexico)

effective_from

string

Start date when this wage becomes effectiveFormat: YYYY-MM-DDExample: "2026-01-01"

effective_to

string

End date when this wage stops being effective. null indicates the current active wage.Format: YYYY-MM-DD or nullExample: "2026-12-31" or null

created_at

string

ISO 8601 timestamp when the record was created (UTC)

updated_at

string

ISO 8601 timestamp when the record was last updated (UTC)

deleted_at

string

ISO 8601 timestamp when the record was soft-deleted (UTC), or null if active

Example

curl -X GET "https://api.sushigo.local/api/v1/employees/01JKXYZ1234567890ABCDEFGH/wages" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
  "status": 200,
  "data": [
    {
      "id": "01JKXYZABC1234567890DEFGH",
      "employee_id": 5,
      "hourly_rate": "150.00",
      "weekly_scheduled_hours": "48.00",
      "effective_from": "2026-03-01",
      "effective_to": null,
      "created_at": "2026-02-15T10:00:00+00:00",
      "updated_at": "2026-02-15T10:00:00+00:00",
      "deleted_at": null
    },
    {
      "id": "01JKXYZDEF9876543210ZYXWV",
      "employee_id": 5,
      "hourly_rate": "125.00",
      "weekly_scheduled_hours": "48.00",
      "effective_from": "2026-01-01",
      "effective_to": "2026-02-28",
      "created_at": "2025-12-20T14:30:00+00:00",
      "updated_at": "2026-02-15T10:00:00+00:00",
      "deleted_at": null
    }
  ]
}

Create Wage Record

Add a new wage history record for an employee. The system automatically closes the previous wage record by setting its effective_to date.

Endpoint

POST /api/v1/employees/{id}/wages

Authentication

Authorization

string

required

Bearer token from OAuth2 authenticationPermission required: employees.update

Path Parameters

string

required

Employee public identifier (ULID format)Example: "01JKXYZ1234567890ABCDEFGH"

Body Parameters

hourly_rate

number

required

Hourly wage rate in local currency. Must be greater than zero.Format: Numeric (stored with 2 decimal places)Example: 150.00

Zero or negative rates are not allowed.

weekly_scheduled_hours

number

required

Scheduled weekly hours. Must be greater than zero.Format: Numeric (stored with 2 decimal places)Example: 48.00

In Mexico, the standard full-time workweek is 48 hours. Part-time employees may have fewer hours.

effective_from

string

required

Date when this wage becomes effective. Can be a past date (for corrections) or future date (for planned raises).Format: YYYY-MM-DDExample: "2026-03-01"

effective_to

string

Optional end date for this wage record. Typically left null for open-ended wages.Format: YYYY-MM-DD or omitValidation: Must be on or after effective_fromExample: "2026-12-31" or omit

When creating a new wage record, the system usually auto-closes the previous record. Manually setting effective_to is uncommon.

Behavior

When a new wage record is created:

The new record is saved with the specified effective_from and effective_to (if provided)
If a previous wage record exists that overlaps with the new record’s effective_from, its effective_to is automatically set to one day before the new record’s effective_from

Creating overlapping wage records may produce unexpected results. Always verify the effective date range before creating a new record.

Example

Create current wage
Create future wage
Create historical correction
Part-time employee

curl -X POST "https://api.sushigo.local/api/v1/employees/01JKXYZ1234567890ABCDEFGH/wages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hourly_rate": 150.00,
    "weekly_scheduled_hours": 48.00,
    "effective_from": "2026-03-01"
  }'

curl -X POST "https://api.sushigo.local/api/v1/employees/01JKXYZ1234567890ABCDEFGH/wages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hourly_rate": 175.00,
    "weekly_scheduled_hours": 48.00,
    "effective_from": "2027-01-01"
  }'

This creates a future raise scheduled for January 1, 2027.

curl -X POST "https://api.sushigo.local/api/v1/employees/01JKXYZ1234567890ABCDEFGH/wages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hourly_rate": 120.00,
    "weekly_scheduled_hours": 40.00,
    "effective_from": "2025-06-01",
    "effective_to": "2025-12-31"
  }'

This corrects a past wage record with explicit start and end dates.

curl -X POST "https://api.sushigo.local/api/v1/employees/01JKXYZ1234567890ABCDEFGH/wages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hourly_rate": 130.00,
    "weekly_scheduled_hours": 24.00,
    "effective_from": "2026-03-01"
  }'

This creates a wage record for a part-time employee working 24 hours per week.

Response

status

integer

HTTP status code (201 for created)

data

object

The created wage history object (same structure as in List Wages)

Response Example

{
  "status": 201,
  "data": {
    "id": "01JKXYZABC1234567890DEFGH",
    "employee_id": 5,
    "hourly_rate": "150.00",
    "weekly_scheduled_hours": "48.00",
    "effective_from": "2026-03-01",
    "effective_to": null,
    "created_at": "2026-02-15T10:00:00+00:00",
    "updated_at": "2026-02-15T10:00:00+00:00",
    "deleted_at": null
  }
}

Errors

401

object

Unauthorized - Missing or invalid authentication token

403

object

Forbidden - User lacks employees.update permission

404

object

Employee not found

422

object

Validation errorCommon validation errors:

hourly_rate must be greater than 0
weekly_scheduled_hours must be greater than 0
effective_to must be on or after effective_from
Required fields missing

Wage Calculations

The wage history records are used throughout the system for various calculations:

Per-Minute Rate

The per-minute rate is calculated as:

minute_rate = hourly_rate / 60

Example: An hourly rate of 150.00 MXN/hr equals 2.50 MXN/min This is used for:

Calculating pay for partial hours worked
Overtime compensation
Time-off accruals

Full-Time Equivalency (FTE)

FTE is calculated as:

FTE = weekly_scheduled_hours / 48

Where 48 is the standard full-time workweek in Mexico. Examples:

48 hours/week = 1.0 FTE (full-time)
24 hours/week = 0.5 FTE (half-time)
40 hours/week = 0.833 FTE (83.3% time)

This is used for:

Benefits eligibility
Time-off accrual rates
Headcount reporting

Best Practices

When to create a new wage record

Create a new wage record when:

Employee receives a raise or rate adjustment
Employee’s scheduled hours change (e.g., part-time to full-time)
Correcting historical wage data
Planning future wage increases

Do NOT create a wage record for:

One-time bonuses (use separate bonus records)
Overtime pay (calculated automatically from hourly rate)
Temporary rate changes (use effective_to date instead)

Setting effective dates

Use the date the wage change takes effect (not when it was approved)
For raises, typically set to the first day of a pay period
Future-dated wages are allowed for planned increases
Past-dated wages are allowed for corrections (use with caution)
Leave effective_to as null for current wages
The system auto-closes previous wages when you create a new one

Handling wage corrections

If you need to correct a wage error:

For current wages: Create a new wage with the correct rate and current effective_from
For historical wages: Create a new record with both effective_from and effective_to covering the correction period
Never delete wage records - they may be referenced by payroll calculations
Use soft-delete only if absolutely necessary (requires database access)

Part-time vs. full-time

Always set weekly_scheduled_hours to reflect the employee’s actual schedule:

Full-time: 48 hours (Mexico standard)
Part-time: Actual hours (e.g., 24, 30, 40)
Variable hours: Use average expected hours

The hourly rate should be the same regardless of full-time or part-time status. The system uses weekly_scheduled_hours to calculate FTE for benefits.

List Employees - Retrieve all employees
Create Employee - Create a new employee
Update Employee - Update employee details
Employee Attendance - Track employee attendance

Authentication

Inventory

Cash Operations

Employees

Operating Units

Overview

List Employee Wages

Endpoint

Authentication

Path Parameters

Response

Example

Response Example

Create Wage Record

Endpoint

Authentication

Path Parameters

Body Parameters

Behavior

Example

Response

Response Example

Errors

Wage Calculations

Per-Minute Rate

Full-Time Equivalency (FTE)

Best Practices

Build docs developers (and LLMs) love

Authentication

Inventory

Cash Operations

Employees

Operating Units

​Overview

​List Employee Wages

​Endpoint

​Authentication

​Path Parameters

​Response

​Example

​Response Example

​Create Wage Record

​Endpoint

​Authentication

​Path Parameters

​Body Parameters

​Behavior

​Example

​Response

​Response Example

​Errors

​Wage Calculations

​Per-Minute Rate

​Full-Time Equivalency (FTE)

​Best Practices

​Related Endpoints

Build docs developers (and LLMs) love

Overview

List Employee Wages

Endpoint

Authentication

Path Parameters

Response

Example

Response Example

Create Wage Record

Endpoint

Authentication

Path Parameters

Body Parameters

Behavior

Example

Response

Response Example

Errors

Wage Calculations

Per-Minute Rate

Full-Time Equivalency (FTE)

Best Practices

Related Endpoints