Read Payroll Period Data

The Payroll Period endpoints let you read the pay periods 7shifts has generated for a customer's company. Payroll periods define the start and end dates of each pay run, track when each location's period is closed for processing, and — when requested — surface whether the time punches inside a period have been reviewed and approved.

These endpoints are designed for payroll and Earned Wage Access (EWA) integrations that need to know when a pay period covers, whether it has been closed, and whether the underlying punch data is settled and safe to export.

Knowing when a period is ready to export

A payroll period has two layers of "doneness":

• Per-location state (states[]) — each location closes its own pay period independently when the manager finishes reviewing and approving punches for that location.
• Company-wide finalization (finalized) — true only when every location's state in the period is closed. This is the signal most payroll integrations poll on before exporting.

List Payroll Periods

Retrieve a paginated list of payroll periods for a company, ordered with the most recent period first. Use this when discovering existing pay periods, when syncing on a schedule, or when you want richer status fields than the Retrieve endpoint returns.

Pass include_punches_status=true when you also need to know whether the punches inside each period have been approved by managers and reviewed by employees.

Request URL

curl --request GET \
  --url 'https://api.7shifts.com/v2/time_clocking/payroll_periods?company_id=12345&include_punches_status=true' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

Query parameters

Response body

{
  "data": [
    {
      "id": 9876,
      "company_id": 12345,
      "start": "2024-01-15",
      "end": "2024-01-28",
      "closed": true,
      "finalized": true,
      "states": [
        {
          "id": 4567,
          "location_id": 222,
          "closed": true,
          "processed": "2024-01-30",
          "modified_by_user_id": 333,
          "closed_or_reopened_at": "2024-01-29T18:42:11+00:00"
        }
      ],
      "all_punches_approved": true,
      "employee_punch_approvals": "reviewed",
      "created": "2024-01-15T00:00:00+00:00",
      "modified": "2024-01-29T18:42:11+00:00"
    }
  ],
  "meta": {
    "cursor": {
      "next": "eyJpZCI6OTg3Nn0=",
      "prev": null
    }
  }
}

Here's an explanation of each field on a payroll period:

Each entry in states describes the close/process state for a single location:

Retrieve Payroll Period

Fetch a single payroll period by its ID. Use this when you already know the period you care about — for example, after receiving a payroll_period.closed webhook, or when refreshing a period your integration has previously synchronized.

Request URL

curl --request GET \
  --url 'https://api.7shifts.com/v2/company/12345/payroll_periods/9876' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

Path parameters

Response body

{
  "object": "payroll_period",
  "data": {
    "id": 9876,
    "company_id": 12345,
    "closed": true,
    "start": "2024-01-15",
    "end": "2024-01-28",
    "states": [
      {
        "id": 4567,
        "location_id": 222,
        "closed": true,
        "processed": "2024-01-30",
        "modified_by_user_id": 333,
        "closed_or_reopened_at": "2024-01-29T18:42:11+00:00"
      }
    ]
  }
}

Here's an explanation of each field:

A typical payroll export flow

1. On a schedule (or when you receive a payroll_period.closed webhook), call List Payroll Periods with include_punches_status=true.
2. Identify periods where finalized is true and all_punches_approved is true — these are safe to export.
3. For each such period, call List Time Punches filtered to the period's start and end dates to retrieve the actual hours and wages.
4. Record the period's id and modified timestamp so you can detect re-opens — a manager can reopen a closed period to correct punches, after which modified (and the relevant location states[].closed_or_reopened_at) will advance.