Time Entry API labor.timeEntry

Retrieve employee time-clock entries (punch records), including the break records belonging to each entry.

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/timeEntry/v1

The version segment is optional — POST https://{base-url}/orderpin/oapi/labor/timeEntry 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.timeEntry",
  "version": "v1",
  "filter": { "modifiedStartAt": 1767225600000, "modifiedEndAt": 1769817600000 }
}

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 — it keeps the API name in your logs and lets you pin the version in one place.

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/timeEntry/v1 HTTP/1.1
Host: {base-url}
X-Client-ID: US00000001
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "filter": {
    "modifiedStartAt": 1767225600000,
    "modifiedEndAt":   1769817600000,
    "status": ["open", "closed"]
  },
  "skip": 0,
  "limit": 100,
  "sort": [{ "field": "inAt", "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).

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 (greater than 0 and at least 15 minutes old).

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, uid 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:

{
  "attendance": [
    {
      "uid": "P202601010001",
      "employeeId": "E10086",
      "employeeName": "Alice",
      "roleId": "R2001",
      "roleName": "Cashier",
      "inAt": 1767225600000,
      "outAt": 1767254400000,
      "status": "closed",
      "modifiedAt": 1767254400000,
      "createAt": 1767225600000,
      "breaks": [
        {
          "uid": "B900001",
          "name": "Lunch",
          "breakTypeId": "BR3001",
          "expectedDuration": 1800,
          "inAt": 1767236400000,
          "outAt": 1767238200000,
          "paidBreak": 0,
          "unpaidBreak": 1800
        }
      ]
    }
  ],
  "recordCount": 1234
}

4.1 Time entry fields (attendance[])#

status values#

4.2 Break fields (attendance[].breaks[])#

5. Sorting and pagination#

5.1 Sorting#

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

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

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

Sortable fields: uid, inAt, outAt, createAt, modifiedAt.

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

• A valid response field that does not support sorting (e.g. employeeId, roleId, status, employeeName, roleName) → 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.timeEntry.v1] filter modifiedAt: less than 0 [0]"
}

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 a date range and limit: 200 costs one unit of quota and returns up to 200 records, so paging through a range is far cheaper than one request per record.
• 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; it is the most efficient way to retrieve only what changed since your last run.
• 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.
• Handle open entries. They have no outAt yet and will change later; re-read them via the modifiedAt range on subsequent runs.
• Treat voided entries as excluded from worked-time calculations.
• 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/timeEntry/v1' \
  -H 'X-Client-ID: US00000001' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
        "filter": {
          "modifiedStartAt": 1767225600000,
          "modifiedEndAt":   1769817600000
        },
        "skip": 0,
        "limit": 200,
        "sort": [{ "field": "inAt", "type": "desc" }],
        "with_record_count": true
      }'