Get merchant residuals | Modulate Partner API

curl -G https://getmodulate.dev/api/partner/residuals/reports/2025/1/merchants \
     -H "X-Partner-API-Key: <apiKey>" \
     -d page=1 \
     -d page_size=2 \
     -d sort_by=agent_payout \
     -d sort_order=desc

{
  "data": [
    {
      "merchant_id": "925700000233734",
      "dba_name": "Sunrise Coffee Co",
      "volume": "85000.00",
      "transaction_count": 620,
      "revenue": "1200.00",
      "expenses": "800.00",
      "profit": "400.00",
      "split_pct": 50,
      "agent_payout": "200.00"
    },
    {
      "merchant_id": "925700000198472",
      "dba_name": "The Barber Lounge",
      "volume": "42000.00",
      "transaction_count": 310,
      "revenue": "600.00",
      "expenses": "350.00",
      "profit": "250.00",
      "split_pct": 50,
      "agent_payout": "125.00"
    }
  ],
  "meta": {
    "request_id": "req_res03",
    "api_version": "v1",
    "page": 1,
    "page_size": 2,
    "total_count": 142,
    "total_pages": 71,
    "has_next": true,
    "has_prev": false,
    "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": []
}

Paginated merchant-level residual details with search, sort, and incremental sync support.

Authentication

X-Partner-API-Keystring

API Key authentication via header

Path parameters

yearintegerRequired2000-2100

Report year

monthintegerRequired1-12

Report month

Query parameters

pageintegerOptional>=1Defaults to 1

Page number

page_sizeintegerOptional1-100Defaults to 25

Items per page

sort_bystringOptionalDefaults to agent_payout

Sort field: volume, profit, agent_payout, dba_name

sort_orderstringOptionalformat: "^(asc|desc)$"Defaults to desc

Sort direction

searchstringOptional<=100 characters

Search by merchant name or ID

updated_sincedatetime or nullOptional

ISO-8601 timestamp for incremental sync

Response

Successful Response

datalist of objects

metaobject

errorslist of objects

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error