Sending a release

PUT /delivery/releases/{releaseId}

releaseId is your own ID for the release: 1 to 128 letters, digits, ., _, : or -. Use the ID your system already has (a catalog number works well). Sending the same ID again updates that release; see Updating a release.

Response	Meaning
`201 Created`	A new draft release was created.
`200 OK`	The existing release was updated. `changed: false` means the body was identical to the last one and nothing was touched.
`400 invalid_payload`	The body has errors. `details` lists each one with its path.

Example

{
  "title": "Night Drive",
  "version": "Deluxe",
  "type": "EP",
  "releaseDate": "2026-12-04",
  "catalogNumber": "NOVA-004",
  "language": "en",
  "genre": { "primary": "Electronic", "secondary": "Pop" },
  "cLine": "Nova Records",
  "pLine": "Nova Records",
  "copyrightYear": 2026,
  "artists": [
    { "name": "Nova", "spotifyId": "0OdUWJ0sBjDrqHygGUXeCF",
      "legalFirstName": "Nora", "legalLastName": "Vance" },
    { "name": "Guest", "role": "featuring", "legalFirstName": "Gil", "legalLastName": "Ruiz" }
  ],
  "artwork": { "url": "https://your-bucket.s3.amazonaws.com/nova/cover.jpg" },
  "tracks": [
    {
      "externalId": "NOVA-004-01",
      "title": "Night Drive",
      "explicit": false,
      "audio": { "url": "https://your-bucket.s3.amazonaws.com/nova/night-drive.wav" },
      "credits": [
        { "firstName": "Nora", "lastName": "Vance", "roles": ["Composer", "Producer", "Vocals"], "share": 60 },
        { "firstName": "Bo", "lastName": "Reyes", "roles": ["Lyricist"], "share": 40 }
      ]
    }
  ]
}

Release fields

string

required

The release title, without the version.

string

For example Deluxe or Remixes.

string

Single, EP, Album or Compilation. If left out, it’s set from the track count: 1–3 tracks Single, 4–6 EP, 7 or more Album.

date

required

The date the release goes live in stores, as YYYY-MM-DD.

string

12 or 13 digits with a valid check digit. Leave it out and one is assigned when the release is approved. Required for catalog transfers.

string

Your catalog number.

string

default:"en"

The language of the metadata, as a code such as en, es or pt-BR.

object

required

{ "primary": …, "secondary": … }. Each is a genre name or ID from GET /delivery/reference/genres. Secondary is optional.

string

The copyright holder for the release, without the year. Defaults to your account’s default, then to the first artist.

string

The sound recording copyright holder, without the year. Same defaults as cLine.

integer

Defaults to the year of releaseDate (or of originalReleaseDate for a transfer).

array

required

The release’s artists. At least one must be a primary artist. See Artists.

object

The cover. See Files.

array

required

1 to 100 tracks. See Tracks.

object

Marks the release as a catalog transfer. See Catalog transfers.

date

For transfers only: the date the release first came out.

string

Needed only when the key covers more than one account. See Accounts.

Payload errors

All problems in a body come back together, each with the path into your request:

{
  "error": "invalid_payload",
  "message": "The release has errors.",
  "details": [
    { "path": "upc", "message": "must be a 12 or 13 digit UPC/EAN with a valid check digit" },
    { "path": "tracks[1].credits[0].roles[1]", "message": "\"Wizard\" is not a known role (see GET /reference/credit-roles)" }
  ]
}

A body that passes these checks can still be incomplete for submission, for example a track without a production credit. Validate lists those.

Get started

Delivering releases

Catalog transfers

Release status

Ingestion check

Reference

Example

Release fields

Payload errors

​Example

​Release fields

​Payload errors

Example

Release fields

Payload errors