Skip to main content
GET
Get Royalty Source by ID (Admin)
This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

Required Permissions

  • sources:admin:read

Code Examples

Authorizations

Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Path Parameters

id
string
required

Royalty source ID

Example:

"src-1"

Response

Royalty source details

id
string
Example:

"src-1"

name
string

Source name (automatically normalized to lowercase)

Example:

"spotify"

label
string

Display label for the source

Example:

"Spotify"

type
string

Source type (e.g., DSP, Publisher, Label)

Example:

"DSP"

format
string

File format (csv, excel, json, etc.)

Example:

"csv"

public
boolean

Whether this source is publicly available to all tenants

Example:

true

isActive
boolean
default:true

Whether this source is currently active

Example:

true

startDate
string<date> | null

Start date for source availability

Example:

"2020-01-01"

endDate
string<date> | null

End date for source availability

Example:

"2025-01-01"

dataQuery
object | null
deprecated

Deprecated. Legacy JSONB object containing query configurations. Use dedicated columns instead: salesDataQuery, royaltySumQuery, countSumQuery, metadataQuery.

Example:
fileNameFormat
string | null

Template for expected file name format with period placeholders. Placeholders: {SALPER-FORMAT} (sale period), {ACCPER-FORMAT} (accounting period) Formats: YYYYMM, YYYY-MM, YYYY-MM-DD, MMM-YYYY, etc.

Example:

"{ORG}_Snap_{SALPER-YYYYMM}_Monthly-Sales.csv"

schema
string | null

Text representation of the file schema/structure

Example:

"artist_name,track_name,streams,revenue"

delimiter
string | null

Field delimiter for CSV files

Example:

","

tableNameFormat
string | null

Template for BigQuery table name with period placeholders (SALPER, ACCPER)

Example:

"merlin_snap_SALPER_ACCPER"

columnFormat
string | null

DSL for column semantic mappings. Defines how columns map to period types and formats. Format: ColumnName:TYPE-FORMAT;ColumnName2:TYPE-FORMAT;... Types: SALPER (sale period), ACCPER (accounting period), ISRC, UPC, CATNO, etc. Formats: YYYY-MM-DD, YYYYMM, YYYY-MM, etc.

Example:

"Start_Date:SALPER-YYYY-MM-DD;ISRC:ISRC"

headerRows
integer | null

Number of header rows to skip

Example:

1

fileInfo
object | null

Additional file metadata and configuration

salesDataQuery
string | null

Dedicated SQL query for BigQuery sales data view (extracted from dataQuery JSONB)

royaltySumQuery
string | null

SQL query for calculating royalty sum after file processing

countSumQuery
string | null

SQL query for calculating row count after file processing

metadataQuery
string | null

SQL query for extracting metadata from processed data

assetExtractionQuery
string | null

SQL query for extracting asset catalog items (by ISRC) from raw royalty data. Derived from source schema column mapping

productExtractionQuery
string | null

SQL query for extracting product catalog items (by UPC) from raw royalty data. Derived from source schema column mapping

defaultCurrency
string | null

Default currency code (e.g., USD, GBP). Overridable per-tenant via TenantRoyaltySource settings

Maximum string length: 3
Example:

"USD"

defaultFeeRate
number | null

Default fee rate as decimal (e.g., 0.015 = 1.5%). Overridable per-tenant

Example:

0.015

feeType
enum<string> | null

Fee calculation type

Available options:
percentage,
fixed
Example:

"percentage"

feeDescription
string | null

Human-readable fee description

Example:

"Merlin distribution fee"

exchangeRateStrategy
enum<string> | null

Foreign exchange conversion strategy used in SQL queries

Available options:
cte,
inline,
external_table
feeEmbeddedInQuery
boolean
default:false

Whether the fee multiplier is embedded in the SQL query (true) or applied externally (false)

parentSourceId
string<uuid> | null

Parent source ID for versioned sources (e.g., merlin_vevo variants)

sourceCategory
enum<string> | null

Source category for classification

Available options:
aggregator,
dsp,
publisher,
label,
other
Example:

"dsp"