Skip to main content
POST
/
product
Create Product
curl --request POST \
  --url https://api.royalti.io/product/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'title=Summer Vibes' \
  --form id=PROD-001 \
  --form upc=123456789012 \
  --form catalogNumber=CAT-2024-001 \
  --form 'catalog=<string>' \
  --form externalId=EXT-12345 \
  --form 'displayArtist=John Doe feat. Jane Smith' \
  --form type=Audio \
  --form 'version=Deluxe Edition' \
  --form explicit=clean \
  --form releaseDate=2024-06-15 \
  --form takedownDate=2024-12-31 \
  --form mainGenre=Pop \
  --form 'subGenre=Dance Pop' \
  --form status=Pending \
  --form 'distribution={}' \
  --form 'contributors={
  "name": "<string>",
  "role": "<string>",
  "share": 50
}' \
  --form 'metadata={}' \
  --form 'chartHistory={
  "chart": "Billboard Hot 100",
  "position": 10,
  "date": "2024-01-15"
}' \
  --form totalTracks=12 \
  --form totalDiscs=1 \
  --form 'packageType=Digital Album' \
  --form 'edition=Deluxe Edition' \
  --form reissue=false \
  --form originalReleaseDate=2020-06-15 \
  --form 'recordingLocation=Abbey Road Studios, London' \
  --form 'masteringLocation=Sterling Sound, New York' \
  --form 'producer[0]=Max Martin' \
  --form 'producer[1]=Shellback' \
  --form 'engineer[0]=John Smith' \
  --form 'engineer[1]=Jane Doe' \
  --form sequenceNumber=5 \
  --form parentReleaseId=550e8400-e29b-41d4-a716-446655440000 \
  --form language=en \
  --form c_line_year=2024 \
  --form p_line_year=2024 \
  --form 'artists[0]={
  "id": "artist-123",
  "type": "primary"
}' \
  --form 'artists[1]={
  "id": "artist-456",
  "type": "featuring"
}' \
  --form 'assets[0]={
  "asset": "asset-789",
  "number": 1
}' \
  --form 'assets[1]={
  "asset": "asset-790",
  "number": 2
}'
{
"id": "prod_123456",
"title": "Summer Vibes",
"displayArtist": "John Doe feat. Jane Smith",
"upc": "123456789012",
"catalogNumber": "CAT-2024-001",
"type": "Audio",
"format": "Single",
"explicit": "clean",
"releaseDate": "2024-06-15",
"takedownDate": null,
"mainGenre": "Pop",
"subGenre": "Dance Pop",
"status": "active",
"version": "Deluxe Edition",
"label": "Indie Records",
"copyright": "2024 John Doe",
"publisher": "Music Publishing Co.",
"media": [
{
"id": "<string>",
"url": "<string>",
"type": "<string>",
"mimetype": "<string>"
}
],
"artists": [
{
"id": "<string>",
"name": "<string>",
"type": "primary"
}
],
"assets": [
{
"id": "<string>",
"title": "<string>",
"isrc": "<string>",
"number": 123
}
],
"distribution": {},
"contributors": [
{}
],
"metadata": {},
"chartHistory": [
{
"chart": "<string>",
"position": 123,
"date": "2023-12-25"
}
],
"totalTracks": 12,
"totalDiscs": 1,
"packageType": "Digital Album",
"edition": "Deluxe Edition",
"reissue": true,
"originalReleaseDate": "2023-12-25",
"recordingLocation": "<string>",
"masteringLocation": "<string>",
"producer": [
"<string>"
],
"engineer": [
"<string>"
],
"sequenceNumber": 123,
"parentReleaseId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"language": "en",
"c_line_year": 2024,
"p_line_year": 2024,
"createdAt": "2024-08-25T10:30:00Z",
"updatedAt": "2024-08-25T10:30:00Z"
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

This endpoint allows the creation of a new product. Important Notes:
  • All products are created as production-ready (no draft mode)
  • UPC codes are automatically generated if not provided and auto-UPC is enabled
  • Artist associations and revenue splits are automatically created
  • Assets can be provided or auto-matched based on title and artist
Deprecated Fields:
  • catalog: Use catalogNumber instead
  • Legacy fields will trigger deprecation warnings in response headers
Method: POST Request Payload:
FieldTypeDescription
upcstringThe UPC of the product
catalog (or catalogNumber)stringThe catalog of the product
titlestringThe title of the product
displayArtiststringThe display artist of the product
typestringThe type of the product
externalIdstringThe external ID of the product
releaseDatestringThe release date of the product
takedownDatestringThe takedown date of the product
mainGenrearray of stringsThe main genre of the product
subGenrearray of stringsThe sub-genre of the product
statusstringThe status of the product
distributionstringThe distribution of the product
contributorsstringThe contributors of the product
metadataobjectAdditional metadata for the product
versionstringThe version of the product
explicitbooleanThe explicit content of the product
idstringThe unique identifier of the product
artistsarray of stringsThe artists associated with the product
assetsarray of objectsThe assets associated with the product

Code Examples

const response = await fetch('https://api.royalti.io/product/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "ref": "#/components/schemas/CreateProductRequest"
  })
});

const data = await response.json();
console.log(data);

Authorizations

Authorization
string
header
required

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

Body

title
string
required

Product title

Required string length: 1 - 255
Example:

"Summer Vibes"

id
string

Custom product identifier

Maximum string length: 100
Example:

"PROD-001"

upc
string

Universal Product Code (auto-generated if not provided)

Example:

"123456789012"

catalogNumber
string

Catalog number for the product

Maximum string length: 100
Example:

"CAT-2024-001"

catalog
string
deprecated

DEPRECATED Use catalogNumber instead

Maximum string length: 100
externalId
string

External system identifier

Maximum string length: 100
Example:

"EXT-12345"

displayArtist
string

Display name for the artist(s)

Maximum string length: 255
Example:

"John Doe feat. Jane Smith"

type
enum<string>
default:Audio

Product type

Available options:
Audio,
Video,
Ringtone
Example:

"Audio"

version
string

Product version or variant

Maximum string length: 100
Example:

"Deluxe Edition"

explicit
enum<string>

Whether the product contains explicit content

Available options:
explicit,
clean
Example:

"clean"

releaseDate
string<date>

Product release date

Example:

"2024-06-15"

takedownDate
string<date>

Date when product should be taken down

Example:

"2024-12-31"

mainGenre
string

Primary genre

Maximum string length: 100
Example:

"Pop"

subGenre
string

Secondary genre

Maximum string length: 100
Example:

"Dance Pop"

status
enum<string>
default:Pending

Product status

Available options:
Live,
Taken Down,
Scheduled,
Pending,
Error
distribution
object

Distribution settings and preferences

contributors
object[]

List of contributors and their roles

metadata
object

Additional product metadata

chartHistory
object[]

Historical chart positions for the product

Example:
[
{
"chart": "Billboard Hot 100",
"position": 10,
"date": "2024-01-15"
}
]
totalTracks
integer

Total number of tracks on the product

Required range: x >= 1
Example:

12

totalDiscs
integer

Total number of discs in the product

Required range: x >= 1
Example:

1

packageType
string

Physical/digital package type

Example:

"Digital Album"

edition
string

Edition designation (e.g., Deluxe, Remastered, Anniversary)

Example:

"Deluxe Edition"

reissue
boolean
default:false

Whether this product is a reissue of a previous release

Example:

false

originalReleaseDate
string<date>

Original release date (for reissues)

Example:

"2020-06-15"

recordingLocation
string

Recording studio/location

Maximum string length: 255
Example:

"Abbey Road Studios, London"

masteringLocation
string

Mastering studio/location

Maximum string length: 255
Example:

"Sterling Sound, New York"

producer
string[]

Producer name(s)

Example:
["Max Martin", "Shellback"]
engineer
string[]

Engineer name(s)

Example:
["John Smith", "Jane Doe"]
sequenceNumber
integer

Sequence number in a series or discography

Example:

5

parentReleaseId
string<uuid>

Parent release ID for variants or deluxe editions

Example:

"550e8400-e29b-41d4-a716-446655440000"

language
string

Primary language code (ISO 639-1)

Maximum string length: 10
Example:

"en"

c_line_year
integer

Copyright line year (©)

Required range: 1900 <= x <= 2100
Example:

2024

p_line_year
integer

Phonogram line year (℗)

Required range: 1900 <= x <= 2100
Example:

2024

artists
(string | object)[]

Associated artists with their roles

Artist ID (defaults to primary)

Example:
[
{ "id": "artist-123", "type": "primary" },
{ "id": "artist-456", "type": "featuring" }
]
assets
(string | object)[]

Associated media assets (tracks, videos)

JSON string representation of asset

Example:
[
{ "asset": "asset-789", "number": 1 },
{ "asset": "asset-790", "number": 2 }
]

Response

Product created successfully

id
string

Unique product identifier

Example:

"prod_123456"

title
string

Product title

Example:

"Summer Vibes"

displayArtist
string

Display artist name

Example:

"John Doe feat. Jane Smith"

upc
string

Universal Product Code

Example:

"123456789012"

catalogNumber
string

Catalog number

Example:

"CAT-2024-001"

type
enum<string>
Available options:
Audio,
Video,
Ringtone
Example:

"Audio"

format
enum<string>

Product format (auto-determined by asset count)

Available options:
Single,
EP,
Album,
LP
Example:

"Single"

explicit
enum<string>
Available options:
explicit,
clean
Example:

"clean"

releaseDate
string<date>
Example:

"2024-06-15"

takedownDate
string<date> | null
Example:

null

mainGenre
string
Example:

"Pop"

subGenre
string
Example:

"Dance Pop"

status
string
Example:

"active"

version
string
Example:

"Deluxe Edition"

label
string

Record label (from artist defaults)

Example:

"Indie Records"

Copyright information (from artist defaults)

Example:

"2024 John Doe"

publisher
string

Publisher information (from artist defaults)

Example:

"Music Publishing Co."

media
object[]

Associated media files (artwork, etc.)

artists
object[]

Associated artists

assets
object[]

Associated media assets

distribution
object

Distribution settings

contributors
object[]

Contributors list

metadata
object

Additional metadata

chartHistory
object[]

Historical chart positions

totalTracks
integer

Total number of tracks on the product

Example:

12

totalDiscs
integer

Total number of discs in the product

Example:

1

packageType
string

Physical/digital package type

Example:

"Digital Album"

edition
string

Edition designation

Example:

"Deluxe Edition"

reissue
boolean

Whether this product is a reissue

originalReleaseDate
string<date>

Original release date (for reissues)

recordingLocation
string

Recording studio/location

masteringLocation
string

Mastering studio/location

producer
string[]

Producer name(s)

engineer
string[]

Engineer name(s)

sequenceNumber
integer

Sequence number in a series

parentReleaseId
string<uuid>

Parent release ID for variants

language
string

Primary language code (ISO 639-1)

Example:

"en"

c_line_year
integer

Copyright line year (©)

Example:

2024

p_line_year
integer

Phonogram line year (℗)

Example:

2024

createdAt
string<date-time>

Creation timestamp

Example:

"2024-08-25T10:30:00Z"

updatedAt
string<date-time>

Last update timestamp

Example:

"2024-08-25T10:30:00Z"