Developer API

User Payouts Metrics API

The /v2/users/{user_id}/metrics/payouts endpoint returns payout volume metrics for an individual user over different time periods. Use this endpoint to track how much a specific user has received through your Dots app.

GET /v2/users/{user_id}/metrics/payouts

Retrieves payout volume metrics for a single user within your API app.

Authentication

This endpoint requires:

  • A valid Bearer token in the Authorization header

  • API authentication level 2

For authentication setup, see App Management API.

Ownership Enforcement

You can only retrieve metrics for users within your own API app. Requests for users outside your app will be rejected.

Path Parameters

Parameter

Type

Description

user_id

string (UUID)

The ID of the user to retrieve metrics for

Query Parameters

Parameter

Type

Default

Description

timeframe

string (enum)

all_time

The time period for metrics calculation

Allowed Timeframe Values

  • 1d — Last 1 day

  • 3d — Last 3 days

  • 1w — Last 1 week

  • 1m — Last 1 month

  • 3m — Last 3 months

  • 1y — Last 1 year

  • all_time — All time (default)

The all_time timeframe is unique to this payouts metrics endpoint. Other metrics routes in the Dots API do not support all_time.

Response Fields

Field

Type

Description

user_id

string

The user's external ID within your app

timeframe

string

The timeframe used for the calculation

payouts_volume

number

Total payout volume for the user in the specified timeframe

currency

string

The currency of the payout volume (currently usd)

Example Request

curl -X GET "https://api.dots.dev/v2/users/user_abc123/metrics/payouts?timeframe=1m" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "user_id": "user_abc123",
  "timeframe": "1m",
  "payouts_volume": 2500.00,
  "currency": "usd"
}

Error Responses

Status

Condition

400

Invalid timeframe value (must be one of the allowed enum values)

401

Missing or invalid authentication

403

User not found within your API app (ownership violation)

404

User not found

When to Use This Endpoint

  • Dashboard displays: Show users their cumulative payout history.

  • Reporting: Build per-user payout reports for accounting or analytics.

  • User insights: Track individual payout volumes to identify high-volume recipients.

For app-level metrics (wallet balance, total payouts, connected users), see App Management API. The app metrics endpoint returns aggregate data across your entire app, while this endpoint returns metrics for a single user.

Was this helpful?
Was this helpful?