Retrieve a User's Aggregated Earnings

POST /v1/users/earnings/aggregated

Returns daily aggregated earnings for a user across all their connected gig platforms within a date range. Only accounts with a successful connection during the requested period are included.

Authentication

Private API key required (X-Api-Key header). This is the same key used for backend-to-backend calls — not the public widget key.

Request Body

Field	Type	Required	Description
`user_id`	`string (UUID)`	Conditional	Palenca user ID. Required if `external_id` is not provided.
`external_id`	`string`	Conditional	Your own user identifier. Required if `user_id` is not provided.
`start_date`	`string (YYYY-MM-DD)`	Yes	Start of the earnings window (inclusive).
`end_date`	`string (YYYY-MM-DD)`	Yes	End of the earnings window (inclusive).
`options.details`	`boolean`	No	Default `false`. When `true`, each day's earnings include a per-platform/per-account breakdown.

Note: Provide exactly one of user_id or external_id. Providing both or neither returns a 422 error.

Response

{
  "success": true,
  "data": {
    "platforms_count": 2,
    "platforms": [
      {
        "platform": "uber",
        "account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "last_successful_connection": "2024-03-15"
      },
      {
        "platform": "didi",
        "account_id": "7cb91a23-1234-4321-b3fc-1a2b3c4d5e6f",
        "last_successful_connection": "2024-03-14"
      }
    ],
    "earnings": [
      {
        "earning_date": "2024-03-10",
        "amount": 145.50,
        "currency": "mxn",
        "count_trips": 12,
        "details": null,
        "currency_note": null
      },
      {
        "earning_date": "2024-03-11",
        "amount": 98.75,
        "currency": "mxn",
        "count_trips": 8,
        "details": null,
        "currency_note": null
      }
    ]
  }
}

Response Fields

`data`

Field	Type	Description
`platforms_count`	`integer`	Number of accounts with a successful connection in the date range.
`platforms`	`array`	List of qualifying platform accounts.
`earnings`	`array`	Daily aggregated earnings, sorted ascending by date.

`platforms[*]`

Field	Type	Description
`platform`	`string`	Platform code (e.g. `uber`, `didi`, `rappi`, `ifood`).
`account_id`	`UUID`	Palenca account ID for this platform connection.
`last_successful_connection`	`string (YYYY-MM-DD)`	Most recent date the account synced successfully.

`earnings[*]`

Field	Type	Description
`earning_date`	`string (YYYY-MM-DD)`	The date these earnings were recorded.
`amount`	`float`	Total earnings for this day, rounded to 2 decimal places.
`currency`	`string`	Currency code in lowercase (e.g. `mxn`, `cop`, `brl`). If multi-currency, this will be `usd`.
`count_trips`	`integer \| null`	Total trips across all platforms for this day. `null` if no platform reports trip counts.
`details`	`array \| null`	Per-platform breakdown. Only present when `options.details = true`.
`currency_note`	`string \| null`	Set to `"converted_from_multiple"` when earnings from different currencies were converted to USD. `null` otherwise.

`earnings[].details[]` (when `options.details = true`)

Field	Type	Description
`platform`	`string`	Platform code for this breakdown entry.
`account_id`	`UUID`	Account ID for this breakdown entry.
`amount`	`float`	Earnings from this platform on this day, rounded to 2 decimal places.
`count_trips`	`integer \| null`	Trips from this platform on this day. `null` if the platform doesn't report trips.

Multi-Currency Behavior

When a user has accounts across platforms that report in different currencies (e.g. Uber in MXN and iFood in BRL), the endpoint:

Converts each earning to USD using the historical exchange rate for that day (via Frankfurter API).
Returns currency: "usd" and currency_note: "converted_from_multiple" on every daily entry.

If all earnings share the same currency, amounts are returned as-is in the original currency with no currency_note.

Example: With Details

Request:

{
  "external_id": "worker-abc-123",
  "start_date": "2024-03-01",
  "end_date": "2024-03-07",
  "options": {
    "details": true
  }
}

Response (excerpt):

{
  "success": true,
  "data": {
    "platforms_count": 2,
    "platforms": [...],
    "earnings": [
      {
        "earning_date": "2024-03-01",
        "amount": 210.00,
        "currency": "mxn",
        "count_trips": 18,
        "currency_note": null,
        "details": [
          {
            "platform": "uber",
            "account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "amount": 130.00,
            "count_trips": 11
          },
          {
            "platform": "didi",
            "account_id": "7cb91a23-1234-4321-b3fc-1a2b3c4d5e6f",
            "amount": 80.00,
            "count_trips": 7
          }
        ]
      }
    ]
  }
}

Error Responses

Status	Code	Description
`401`	—	Missing or invalid API key.
`404`	`USER_NOT_FOUND`	No user found for the given `user_id` or `external_id` within your company.
`422`	—	Validation error: both identifiers provided, neither provided, or missing required date fields.
`503`	—	FX rate service unavailable (only relevant for multi-currency responses).

Notes

The endpoint only includes accounts whose last_successful_connection falls within [start_date, end_date]. Accounts that never synced in that window are excluded from both platforms and earnings aggregation.
If no qualifying accounts exist, the response returns platforms_count: 0 with empty platforms and earnings arrays — not a 404.
Results are not paginated. All earnings within the date range are returned in a single response.