Employee Wage API labor.employee.wage

Retrieve employee wage records — the hourly rate of each employee, per role.

1. Getting started#

1.1 Credentials#

To call this API you need two values, issued by OrderPin:

Every request must include both. Requests are automatically scoped to the data of the store associated with your credentials; you cannot read another store's data, and you do not need to specify it.

Getting credentials: email api@orderpin.us with your Store ID — that is all OrderPin needs to issue your Client ID and API key. Credentials are issued per store: if your company has several stores, request a separate set for each Store ID.

1.2 Endpoint#

There are two equivalent ways to call the API.

Path form (recommended) — the API name is part of the URL:

POST https://{base-url}/orderpin/oapi/labor/employee/wage/v1

The version segment is optional — POST https://{base-url}/orderpin/oapi/labor/employee/wage uses the current default version (v1). Pinning the version explicitly is recommended so that your integration is not affected by future default-version changes.

Generic form — call the base endpoint and declare the API in the request body:

POST https://{base-url}/orderpin/oapi

{
  "subject": "labor.employee.wage",
  "version": "v1",
  "filter": { "employeeId": "E10086" }
}

With this form, subject is required (an unknown or missing subject/version is reported with code 1020); version is optional and defaults to v1. All other parameters (§3) are the same. The path form is preferred.

1.3 Request headers#

A JSON request body is always required, even when you have no filters to send — use {}. A request with an empty body is rejected.

2. Request format#

{
  "filter": {
    "<parameter>": "<value or array of values>"
  },
  "skip": 0,
  "limit": 100,
  "sort": [
    { "field": "<field name>", "type": "desc" }
  ],
  "with_record_count": true
}

Example#

POST /orderpin/oapi/labor/employee/wage/v1 HTTP/1.1
Host: {base-url}
X-Client-ID: US00000001
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "filter": { "employeeId": ["E10086", "E10087"] },
  "sort": [{ "field": "createAt", "type": "desc" }],
  "with_record_count": true
}

3. Request parameters#

Unrecognized parameters are rejected. Only the parameters listed below are accepted.

3.1 Query parameters#

3.2 Filter parameters#

All timestamps are Unix epoch time in milliseconds (UTC).

Note: createAt reflects the wage's effective start time, not the moment the record was written. An employee may have several wage records over time — sort by createAt to find the latest.

Data freshness#

Reporting data becomes queryable approximately 15 minutes after it is recorded. A timestamp filter value that is less than 15 minutes (900000 ms) old — or in the future — is rejected with data from the last 15 minutes is not yet available for query. When polling for new data, end your query range at now - 15 minutes.

Using date ranges#

createStartAt / createEndAt and modifiedStartAt / modifiedEndAt are paired range filters:

• Both halves must be sent together. Sending only one is rejected with missing pair filter.
• The range is half-open: start <= value < end.
• start must be earlier than end.
• The span must be less than 31 days (2678400000 ms). Wider ranges are rejected.
• Each half must also satisfy the data freshness rule above.

This makes range filters ideal for incremental synchronization: poll with modifiedStartAt / modifiedEndAt to pick up records that changed since your last run.

Value types#

Values are type-checked. Sending a number where a string is expected (or vice versa) is rejected — for example, employeeId must be a string, and modifiedAt must be a number.

When a filter accepts an array, it behaves as "matches any of these values".

4. Response format#

A successful request returns HTTP 200 with a JSON object:

{
  "employeeWage": [
    {
      "uid": "W3001",
      "employeeId": "E10086",
      "employeeName": "Alice",
      "roleId": "R2001",
      "roleName": "Cashier",
      "currency": "USD",
      "hourlyWage": 1800,
      "modifiedAt": 1767254400000,
      "createAt": 1735689600000
    }
  ],
  "recordCount": 12
}

4.1 Wage fields (employeeWage[])#

5. Sorting and pagination#

5.1 Sorting#

sort accepts a single object or an array of objects (applied in order):

"sort": [
  { "field": "createAt", "type": "desc" },
  { "field": "uid",      "type": "asc" }
]

type must be asc or desc, and both field and type are required.

Sortable fields: uid, employeeId, createAt, modifiedAt.

Sorting is supported only on these fields. Using any other name is rejected:

• A valid response field that does not support sorting (e.g. roleId, hourlyWage) → field <name> not sortable
• A name that is not a response field (including filter names such as modifiedStartAt) → unknown sort field <name>

5.2 Pagination#

Results are limited to 200 records per request. To page through a larger result set:

1. Send the first request with "with_record_count": true, "skip": 0, "limit": 200.
2. Read recordCount from the response to determine the number of pages.
3. Repeat, increasing skip by limit each time, until all records are retrieved.

Always use a sort when paginating so that the ordering is stable across pages.

6. Errors#

Successful requests return HTTP 200. Errors return the HTTP status that matches the error category, with a JSON body:

{
  "code": 1004,
  "msg": "Error: [labor.employee.wage.v1] filter employeeId: employeeId is empty [\"\"]"
}

Read the code field for the precise reason. The HTTP status groups errors by category: 4xx for request and credential problems, 429 for rate limiting, 5xx for server-side failures.

6.1 Common 1004 validation messages#

7. Rate limits#

Requests are limited per client ID, and the quota is shared across the whole service — running several workers in parallel does not give you extra capacity.

The exact values are configured per environment. Read them from the response headers rather than hard-coding them:

When you exceed the quota the response is:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{ "code": 2012, "msg": "[2012] Error: rate limit exceeded, retry after 37 second(s)" }

The window slides continuously rather than resetting at a fixed boundary, so quota comes back gradually. Waiting the full Retry-After is always sufficient.

How to stay within the limit#

• Retry on 429 using Retry-After, not a fixed sleep. Add jitter if you run multiple workers.
• Watch X-RateLimit-Remaining and slow down before you hit zero.
• Prefer wide queries over many narrow ones. A single request with employeeId as an array and limit: 200 costs one unit of quota and returns up to 200 records.
• Do not retry 5xx in a tight loop — those attempts also consume quota.

Rate limiting is applied only after your credentials have been verified, so a request that fails authentication does not consume your quota.

8. Recommendations#

• Filter by modifiedStartAt / modifiedEndAt for incremental synchronization.
• Keep ranges under 31 days. Split longer periods into multiple requests.
• Always send a sort when paginating so pages do not overlap or skip records.
• Request with_record_count once (on the first page) rather than on every page.
• Wage history: an employee can have multiple wage records; the one with the latest createAt (effective start) not in the future is the current rate.
• Protect your API key. Send it only over HTTPS, never embed it in client-side code, and email api@orderpin.us immediately if you suspect it has been exposed.
• Retry transient failures (1003, 1012) with exponential backoff, and honor Retry-After on 429.

9. Full example#

curl -X POST 'https://{base-url}/orderpin/oapi/labor/employee/wage/v1' \
  -H 'X-Client-ID: US00000001' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
        "filter": { "employeeId": "E10086" },
        "skip": 0,
        "limit": 200,
        "sort": [{ "field": "createAt", "type": "desc" }],
        "with_record_count": true
      }'