Query Royalty Records and Earnings Data via the UMW API

The UMW Recordings API delivers normalized royalty data aggregated from dozens of digital stores, streaming platforms, and licensing bodies worldwide. Rather than working with raw store statements — each in a different format, currency, and reporting cadence — you receive a unified record set with consistent field names, converted amounts, and standardized period identifiers. This guide explains the royalty data model, how to query and filter records, and how royalty data flows into consolidated statements and payouts.

Royalty data for a given reporting period typically appears in the API 45–60 days after that period closes. For example, data for streams occurring in January will generally be available by mid-March. This lag reflects the time stores and collecting societies take to compile and transmit their reports to UMW.

Royalty Data Model

Each royalty record represents a discrete earnings line item from a single source for a single reporting period.

Field	Type	Description
`id`	string	Unique identifier for the royalty record
`statement_id`	string	The consolidated statement this record belongs to
`period`	string	Reporting period in `YYYY-MM` format (e.g., `"2024-03"`)
`source`	string	The store or platform that generated the earnings (e.g., `"spotify"`, `"apple_music"`)
`territory`	string	ISO 3166-1 alpha-2 country code where the consumption occurred
`release_id`	string	The release this record is attributed to
`track_id`	string	The specific track this record is attributed to (if applicable)
`currency`	string	ISO 4217 currency code of the original report (e.g., `"USD"`, `"EUR"`)
`gross_amount`	number	Earnings before UMW distribution fees, in `currency`
`net_amount`	number	Earnings after UMW distribution fees, in `currency`
`units`	integer	Number of streams, downloads, or other consumption units reported
`rate_type`	string	Consumption type: `stream`, `download`, `sync`, `mechanical`, `performance`
`upc`	string	UPC of the associated release
`isrc`	string	ISRC of the associated track (if applicable)
`reported_at`	string	ISO 8601 timestamp when the record was ingested from the source

Querying Royalties

Use the /v1/royalties endpoint to retrieve royalty records. All query parameters are optional and can be combined to narrow results precisely.

GET /v1/royalties

Query parameters:

Parameter	Type	Description
`period`	string	Filter by reporting period (`YYYY-MM`). Supports ranges: `period[gte]=2024-01&period[lte]=2024-06`
`territory`	string	ISO 3166-1 alpha-2 country code
`source`	string	Platform identifier (e.g., `spotify`, `apple_music`, `amazon_music`)
`release_id`	string	Filter records attributed to a specific release
`track_id`	string	Filter records attributed to a specific track
`rate_type`	string	Filter by consumption type (`stream`, `download`, `sync`, etc.)
`limit`	integer	Records per page (default: `100`, max: `1000`)
`cursor`	string	Pagination cursor from a previous response’s `meta.next_cursor`

Example — fetch all streaming royalties for a single release in Q1 2024:

curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "release_id=rel_01HXK3AB7NMCPQ2XYZ9WD4EF5" \
  -d "rate_type=stream" \
  -d "period[gte]=2024-01" \
  -d "period[lte]=2024-03" \
  -d "limit=100"

Paginated response:

{
  "data": [
    {
      "id": "roy_01HXKB2MN3OPQR4STUVWX5YZ6",
      "statement_id": "stm_01HXKC3NO4PQRS5TUVWXY6ZA7",
      "period": "2024-01",
      "source": "spotify",
      "territory": "US",
      "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
      "track_id": "trk_01HXK5CD2PQRS3UVWX7YZ0AB1",
      "currency": "USD",
      "gross_amount": 142.87,
      "net_amount": 121.44,
      "units": 48329,
      "rate_type": "stream",
      "upc": "850123456789",
      "isrc": "USPAR2400101",
      "reported_at": "2024-03-12T09:00:00Z"
    },
    {
      "id": "roy_01HXKD4OP5QRST6UVWXYZ7AB8",
      "statement_id": "stm_01HXKC3NO4PQRS5TUVWXY6ZA7",
      "period": "2024-01",
      "source": "apple_music",
      "territory": "GB",
      "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
      "track_id": "trk_01HXK5CD2PQRS3UVWX7YZ0AB1",
      "currency": "GBP",
      "gross_amount": 38.52,
      "net_amount": 32.74,
      "units": 11204,
      "rate_type": "stream",
      "upc": "850123456789",
      "isrc": "USPAR2400101",
      "reported_at": "2024-03-14T11:30:00Z"
    }
  ],
  "meta": {
    "total": 847,
    "limit": 100,
    "next_cursor": "cur_01HXKE5PQ6RSTU7VWXYZ8ABC9",
    "has_more": true
  }
}

To retrieve the next page, pass the next_cursor value as the cursor query parameter in your next request.

Filtering Examples

# All royalties earned in Germany across all sources and periods
curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "territory=DE" \
  -d "limit=500"

# All Spotify royalties for March 2024
curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "source=spotify" \
  -d "period=2024-03"

# All royalties for a specific track across all stores and periods
curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "track_id=trk_01HXK5CD2PQRS3UVWX7YZ0AB1" \
  -d "period[gte]=2024-01"

# Sync licensing income only (all releases, all periods)
curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "rate_type=sync"

# Page through all royalties for H1 2024
curl -G https://api.umwrecordingsinc.com/v1/royalties \
  -H "Authorization: Bearer $UMW_API_KEY" \
  -d "period[gte]=2024-01" \
  -d "period[lte]=2024-06" \
  -d "limit=1000" \
  -d "cursor=cur_01HXKE5PQ6RSTU7VWXYZ8ABC9"

Statements and Payouts

Individual royalty records are the most granular unit of earnings data, but UMW also exposes higher-level aggregates that drive your payout cycle. Statements consolidate all royalty records for a given period into a single summary object. A statement includes total gross earnings, total net earnings, any applicable adjustments or withholdings, and the final payable amount. Statements are generated automatically at the close of each reporting cycle. Payouts are triggered when a statement’s payable balance meets your account’s payout threshold. A payout record tracks the transfer amount, destination account, processing status, and expected settlement date.

Statements API

View and download consolidated earnings statements by period, including itemized adjustments and withholding details.

Payouts API

Monitor payout status, view transfer history, and configure your preferred payout method and threshold.

Get Started

Platform Guides

Platform Reference

Query Royalty Records and Earnings Data via the UMW API

Royalty Data Model

Querying Royalties

Filtering Examples

Statements and Payouts

Statements API

Payouts API

​Royalty Data Model

​Querying Royalties

​Filtering Examples

​Statements and Payouts

Statements API

Payouts API

Royalty Data Model

Querying Royalties

Filtering Examples

Statements and Payouts