Get top merchants | Modulate API

{
  "data": [
    {
      "merchant_id": "925700000233734",
      "dba_name": "Sunrise Coffee Co",
      "profit": "1200.00",
      "volume": "180000.00",
      "agent_payout": "600.00"
    },
    {
      "merchant_id": "925700000198472",
      "dba_name": "The Barber Lounge",
      "profit": "950.00",
      "volume": "120000.00",
      "agent_payout": "475.00"
    },
    {
      "merchant_id": "925700000345678",
      "dba_name": "Metro Auto Wash",
      "profit": "800.00",
      "volume": "95000.00",
      "agent_payout": "400.00"
    }
  ],
  "meta": {
    "request_id": "req_res07",
    "api_version": "v1",
    "source": "bigquery",
    "as_of": "2025-01-15T10:30:00+00:00",
    "report_run_id": "rpt_2025_01_a1b2c3d4e5f6",
    "report_status": "final",
    "data_cutoff_at": "2025-02-05T00:00:00+00:00",
    "generated_at": "2025-01-15T10:30:00+00:00"
  },
  "errors": []
}

Returns the top merchants ranked by profit for a residual report period.

Authentication

X-Partner-API-Keystring

API Key authentication via header

Path parameters

yearintegerRequired2000-2100

Report year

monthintegerRequired1-12

Report month

Query parameters

limitintegerOptional1-50Defaults to 10

Number of top merchants to return

Response

Successful Response

datalist of objectsOptional

metaobjectOptional

errorslist of objectsOptional

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error

$	curl -G https://getmodulate.dev/api/partner/residuals/reports/2025/1/top-merchants \
>	-H "X-Partner-API-Key: <apiKey>" \
>	-d limit=3