Earnings Stream combines information from our Shifts, Paystubs, Income, and Employment endpoints to derive actionable values. It is built around earnings which roll up into top-level payout entities.

Entities

{
  "data": [ /* A collection of payouts */
    { "earnings": [ /* A collection of earnings */ ] },
    { "earnings": [ /* ... */ ] },
    /* ... */
  ]
}

Payouts are discrete cash flow events. An estimated payout represents income that has been earned but not finalized in the payroll system. A processed payout represents income with a finalized paystub issued in the payroll system. Payouts are the top-level entities in the Earnings Stream, meaning everything rolls into a payout.

Earnings are synthetic cash flows that materialize as payouts. They are a summary of income that was earned on a given day. Earnings are broken out per day to support visualizing earnings in a calendar format for end users. All earnings roll up into specific payouts.

Earnings Stream is focused on net pay, which is gross pay minus any deductions, such as taxes and healthcare.

Estimated Payouts

Estimated payouts, status = estimatedrepresent income expected to have been earned but not finalized in the payroll system, i.e., no corresponding paystub has been issued yet.

{
  "data": [ /* A collection of payouts */
    {
      "status": "estimated",
      "pay_date": "...",
      "earnings": [ /* A collection of earnings */
        {
          "date": "...",
          "net_pay": { /* ... */ },
          "confidence_score": 0.88
        }
      ]
    },
    /* ... */
  ]
}

Estimated payouts include projected pay dates, pay_date, which is when the user's pay is expected to be disbursed to them. Pinwheel projects these from historical pay dates. For consistency, this matches the pay date reported in paystubs, which, by convention, is intended to be when the user sees funds in their account and, therefore, buffers for ACH settlement time. This projected value is best used for UI instead of pre-scheduling repayment via account debits due to the account settlement variances.

Estimated payouts include daily earnings, earnings, which specify net pay and confidence_score. Daily earnings use real-time shift data (i.e., hours worked) and historical paystubs pulled from payroll or T&A platforms to estimate pay details (e.g., gross pay, net pay, deduction rate). At least one historical paystub is required when shifts are available, and 60 days of paystubs are required otherwise. Earnings are aggregated daily, specified by date.

The confidence score, confidence_score is a decimal value from 0 to 1 that helps you make an informed decision about how to use the earnings data. It's generated using factors like the length of historical paystub data available, availability of real-time shifts data, and income stability.

Processed Payouts

Processed payouts, status = processed, represent guaranteed income, i.e., a paystub has been issued finalizing the net pay and other details.

{
  "data": [ /* A collection of payouts */
    {
      "status": "processed",
      "pay_date": "...",
      "net_pay": { /* ... */ },
      "earnings": [ /* A collection of earnings */
        {
          "date": "...",
          "net_pay": { /* ... */ }
        }
      ]
    },
    /* ... */
  ]
}

Processed payouts include pay date, pay_date, which is when the user's pay is disbursed. This date is retrieved from the paystub and, by convention, is when the user sees funds in their account at a standard financial institution and, therefore, buffers for ACH settlement time (e.g., two days).

• For most processed payouts, the pay date is in the past. However, for recent processed payouts the pay date can be in the future since the median time between paystub issuance and the pay date is six days.
• To know if you have received the funds from a processed payout, e.g., via direct deposit, you must reconcile incoming ACH credit transactions with processed payout records. Leverage the pay_date and net_pay amount to find matches.

Processed payouts include a top-level net pay attribute, net_pay, which is the final amount of funds that is disbursed to the user.

Each processed payout has a collection of daily earnings, earnings, which indicate net pay for a given day. Each day in the earnings period with a non-null net_pay will have a daily earnings record.

FAQ

• What happens when an estimated payout transitions to processed?
  The estimated payout entry will be removed, and a new processed payout entry will be added. The newly processed payout entry may have different pay date and earnings values based on new information from the finalized paystub.

• Can there be multiple payouts for a given pay date?
  Yes. There are several reasons: some employers run concurrent pay periods, some users work multiple jobs, some pay periods open and close on the same day, and some employers issue bonuses or other earnings as one-off payouts.

• Can there be multiple estimated payouts at once?
  Yes. The primary instance is you've connected multiple payroll accounts for one end user because they work multiple jobs (e.g., Uber and McDonald’s). We will surface estimated Payouts for each of the user’s jobs. In rare instances, we may surface multiple estimated Payouts because a new pay period has started, even though the previous pay period has not been processed (i.e., finalized).

• Does the Earnings Stream support all users?
  Earnings Stream only estimated payouts for users when we have enough information to make sufficiently accurate projections. To determine accuracy, we backtested our underlying model against real paystubs from all employers in our system. The Pinwheel model is designed to let you advance 30-50% of accrued earnings with minimal risk of loss due to overestimated net pay. Earnings Stream includes processed payouts for all users which Pinwheel can retrieve paystubs for.

• How quickly will the Earnings Stream include newly completed shifts?
  Most employers approve completed shifts in less than 24 hours. Therefore, expect to see updated Earnings within 1 day of a user completing their shift.

• On what schedule are most users paid?
  Most users we see are paid bi-weekly in arrears, i.e., every two weeks, they are paid for the work they completed in the preceding two-week period. The median time between a payout being processed and the pay date when a user receives their funds is 6 days (or 4 days if they use an early pay bank), though this ranges from 0 to 12 days and is controlled on a per-employer basis.

• What is the difference between missing_* and invalid_* unavailable reasons?
  We require data from the Income, Paystubs, and Shifts jobs data to create an Earnings Stream.

  • missing means that there is no data for the current pay period that Pinwheel is trying to create the Earnings Stream.
  • invalid means that there is data for the current pay period; however, it doesn’t meet our criteria of valid data. Here are some example criteria (not an exhaustive list):
    • Paystub net_pay_amount and gross_pay_amount > 0
    • Paystub gross_pay_amount ≥ net_pay_amount
    • Shift earning amount > 0 or hours & rate are > 0
    • Income compensation unit is hourly

Please contact [email protected] for access to our Dashboard.