---
title: "List Paystubs"
method: GET
path: "/accounts/{account_id}/paystubs"
tags: ["Income and Employment"]
---

# List Paystubs

`GET /accounts/{account_id}/paystubs`

The paystubs endpoint allows you to query for payouts to an end user. Each paystub contains broken out and aggregated earnings information, as well as relevant dates. Paystubs are returned in reverse chronological order by `pay_date`. This is a paginated endpoint; see how Pinwheel implements pagination <a href='https://docs.pinwheelapi.com/docs/pagination-1' target='_blank'>here</a>.

## Path parameters

- `account_id` string, uuid, required — UUID of the payroll account.

## Query parameters

- `from_pay_date` string, date — Filter for paystubs with pay dates after this date.
- `to_pay_date` string, date — Filter for paystubs with pay dates before this date.
- `cursor` string — Cursor for the page you want to retrieve.
- `limit` integer — The maximum number of results to return.

## Headers

- `Pinwheel-Version` '2025-07-08' | '2023-11-22' | '2023-07-18' | '2023-04-18' | '2022-09-09' | '2022-06-22' | '2022-03-02', required

## Response `200`

OK

- object
  - `meta` RefreshablePaginationListMeta, required
    - `refreshed_at` string, date-time — ISO 8601 timestamp of the most recent refresh of this data.
    - `count` integer — Number of objects returned.
    - `next_cursor` string — Pointer to the next page of results.
  - `data` PaystubObjResponseV20220302[], required
    - `id` string, uuid, required — Unique identifier for the object.
    - `created_at` string, date-time, required — ISO 8601 timestamp of created time.
    - `account_id` string, uuid, required — UUID of the payroll account.
    - `pay_date` string, date, required — The date when the check amount is paid to the employee.
    - `pay_period_start` string, date — The date when the pay period begins. Some platforms, like unemployment portals, do not have fixed pay periods.
    - `pay_period_end` string, date — The date when the pay period ends. Some platforms, like unemployment portals, do not have fixed pay periods.
    - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'USS' | 'UYI' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XTS' | 'XXX' | 'YER' | 'ZAR' | 'ZMW', required — Three-letter ISO 4217 currency code, uppercase. For example, the code for US dollars is USD.
    - `gross_pay_amount` integer, required — The total earnings before any deductions are made, in cents.
    - `net_pay_amount` integer, required — The total earnings after all taxes and deductions are removed, in cents.
    - `check_amount` integer, required — The amount paid to the employee in this payout, in cents.
    - `gross_pay_ytd` integer — The cumulative year to date total earnings before any taxes or deductions are removed, in cents.
    - `net_pay_ytd` integer — The cumulative year to date total earnings after all taxes and deductions are removed, in cents.
    - `total_taxes` integer, required — The total taxes for this pay period, in cents.
    - `total_deductions` integer, required — The total deductions for this pay period, in cents.
    - `total_reimbursements` integer, required — The total reimbursements for this pay period, in cents.
    - `external_paystub_id` string — The external id of a single paystub from the payroll provider.
    - `employer_name` string — The name of the employer that issued the paystub.
    - `taxes` TaxObjPublicResponseItem[], required — The taxes for this pay period, in cents.
      - `name` string, required — The name of the tax.
      - `category` 'federal_income' | 'social_security' | 'medicare' | 'state_income' | 'local_income' | 'other', required — The category of tax.
      - `amount` integer, required — The amount of tax, in cents.
    - `deductions` DeductionObjPublicResponseItem[], required — The deductions for this pay period, in cents.
      - `name` string, required — The name of the deduction.
      - `category` 'retirement' | 'medical_insurance' | 'hsa' | 'fsa' | 'dental' | 'vision' | 'life_insurance' | 'disability' | 'child_support' | 'commuter' | 'union_dues' | 'stock' | 'charity' | 'savings' | 'tips' | 'wage_garnishment' | 'lending' | 'company_perk' | 'tax' | 'loan' | 'job_expense' | 'other' | 'fees' | 'reallocation' | 'retro_pay', required — The category of deduction.
      - `amount` integer, required — The amount of deduction, in cents.
      - `type` 'pre_tax' | 'post_tax' | 'unknown', required — The type of deduction.
    - `earnings` EarningObjPublicResponseItem[], required — The earnings for this pay period, in cents.
      - `name` string, required — The name of the earning.
      - `category` 'salary' | 'hourly' | 'overtime' | 'double_overtime' | 'premium' | 'bonus' | 'commission' | 'tips' | 'vacation' | 'holiday' | 'pto' | 'sick' | 'employer_contribution' | 'other' | 'fare' | 'unpaid' | 'parental' | 'shift_differential' | 'bereavement' | 'life_insurance' | 'stock' | 'retirement' | 'medical' | 'meal_comp' | 'disability' | 'retro_pay', required — The category of earning.
      - `amount` integer, required — The amount of earning, in cents.
      - `rate` integer — The amount earned per hour, in cents.
      - `hours` number — The hours worked.
    - `time_off` TimeOffObjPublicResponseItem[], required — The user's time off balances for this pay period. To enable time off balances, please contact Pinwheel support.
      - `name` string, required — The name of the time off.
      - `category` 'pto' | 'sick' | 'other', required — The category of the time off.
      - `available_hours` number — The total hours of time off available, as of the pay period end date. In the event available_hours is not on the paystub, this value reflects the current available_hours at the time the paystub was retrieved.
      - `earned_hours` number — The hours of time off earned during the pay period.
      - `used_hours` number — The hours of time off used during the pay period.
    - `document` DocumentObjPublicResponseItem
      - `id` string, uuid, required — Unique identifier of the document object.
      - `download_url` string — URL from which the document may be downloaded.
      - `download_url_expiration` string, date-time — ISO 8601 timestamp of when the download URL will no longer be valid.

---

[API](https://skmtc.net/getpinwheel/apis/pinwheel.md) · [All operations](https://skmtc.net/getpinwheel/apis/pinwheel/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getpinwheel/pinwheel/revisions/8ef86dd4902e/schema)