# Get Customer Earnings

This endpoint returns current-period earnings for the customer's pockets in a single call: one entry per pocket plus their exact aggregate.
The `aggregate` is the field-wise sum of the per-pocket entries (sum of `earnings`, sum of `appreciation_per_second`, earliest `pricing_timestamp`), so it always matches the total of the individual rows. It is `null` only when no pockets match the request.
- Pre-defined ranges are defined as such:
  - ytd (Year-to-date) From January 1st of the current year
  - mtd (Month-to-date) From the 1st calendar day of the current month, or start of business that month
  - wtd (Week-to-date) From the most recent Monday, or start of business that week.
  - all-time (default) From Account start
  - All through to the current day if business day, or last business day.

Custom date ranges are not supported here; use the single-pocket earnings endpoint with `period=range` instead.
By default every pocket that is not closed is included, up to at most 30 per request — requests covering more pockets are rejected with a `400`. Use the `pocket_id[]` filter to restrict the earnings to specific pockets; a closed pocket's earnings are included only when it is listed there explicitly.

Endpoint: GET /api/v2/earnings/
Version: Version: d28453d9
Security: CodeBearer

## Query parameters:

  - `period` (string)
    The period to fetch earnings for. Can be one of

 * ytd (Year-to-date)
 * mtd (Month-to-date)
 * wtd (Week-to-date)
 * all-time

Custom date ranges are not supported at the customer level; use the
single-pocket earnings endpoint with 'range' instead.

  - `pocket_id[]` (any)
    Restricts the earnings to the given pockets. Defaults to all of the customer's pockets except closed ones; a closed pocket's earnings are included only when it is listed here explicitly.

## Response 200 fields (application/json):

  - `aggregate` (any, required)

  - `aggregate.earnings` (object, required)

  - `aggregate.earnings.value` (integer, required)
    USD values are always in cents.

  - `aggregate.earnings.currency` (string, required)

  - `aggregate.earnings.formatted` (string)

  - `aggregate.date_from` (any, required)

  - `aggregate.date_to` (string, required)

  - `aggregate.pricing_timestamp` (any)

  - `aggregate.appreciation_per_second` (any)

  - `pockets` (array, required)

  - `pockets.date_from` (any, required)

  - `pockets.date_to` (string, required)

  - `pockets.pricing_timestamp` (any)

  - `pockets.appreciation_per_second` (any)

  - `pockets.pocket_id` (string, required)

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

  - `detail.input` (any)

  - `detail.ctx` (object)