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=false \
  --form releaseDate=2024-06-15 \
  --form takedownDate=2024-12-31 \
  --form mainGenre=Pop \
  --form 'subGenre=Dance Pop' \
  --form status=active \
  --form 'distribution={}' \
  --form 'contributors={
  "name": "<string>",
  "role": "<string>",
  "share": 50
}' \
  --form 'metadata={}' \
  --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": false,
  "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": {},
  "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
Example:

"Audio"

​
version
string

Product version or variant

Maximum string length: 100
Example:

"Deluxe Edition"

​
explicit
boolean
default:false

Whether the product contains explicit content

​
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:active

Product status

Available options:
active,
inactive,
pending
​
distribution
object

Distribution settings and preferences

​
contributors
object[]

List of contributors and their roles

​
metadata
object

Additional product metadata

​
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
Example:

"Audio"

​
format
enum<string>

Product format (auto-determined by asset count)

Available options:
Single,
EP,
Album
Example:

"Single"

​
explicit
boolean
Example:

false

​
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
string

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

​
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"