Reorder or Replace a Playlist's Items

Developing

PUT

/playlists/{playlist_id}/tracks

category-playlists

Either reorder or replace items in a playlist depending on the request's parameters.
To reorder items, include range_start, insert_before, range_length and snapshot_id in the request's body.
To replace items, include uris as either a query parameter or in the request's body.
Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.

Note: Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters.
These operations can't be applied together in a single request.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PUT 'https://api.spotify.com/v1/playlists//tracks' \
--header 'Authorization;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "insert_before": 0,
    "range_length": 0,
    "range_start": 0,
    "snapshot_id": "string",
    "uris": [
        "string"
    ]
}'

Response Example

200 - Example 1

{
  "snapshot_id": "string"
}

Request

Path Params

playlist_id

string

required

The Spotify ID for the playlist.

Query Params

uris

string

optional

A comma-separated list of Spotify URIs to set, can be track or episode URIs. For example: uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ
A maximum of 100 items can be set in one request.

Header Params

Authorization

string

required

A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
Reordering or replacing items in the current user's public playlists requires authorization of the playlist-modify-public scope; reordering or replacing items in the current user's private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.

Content-Type

string

optional

Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json

Body Params application/json

insert_before

integer <int32>

optional

The position where the items should be inserted.
To reorder the items to the end of the playlist, simply set insert_before to the position after the last item.
Examples:
To reorder the first item to the last position in a playlist with 10 items, set range_start to 0, and insert_before to 10.
To reorder the last item in a playlist with 10 items to the start of the playlist, set range_start to 9, and insert_before to 0.

range_length

integer <int32>

optional

The amount of items to be reordered. Defaults to 1 if not set.
The range of items to be reordered begins from the range_start position, and includes the range_length subsequent items.
Example:
To move the items at index 9-10 to the start of the playlist, range_start is set to 9, and range_length is set to 2.

range_start

integer <int32>

optional

The position of the first item to be reordered.

snapshot_id

string

optional

The playlist's snapshot ID against which you want to make the changes.

uris

array[string]

optional

Examples

Responses

🟢200On a successful **reorder** operation, the response body contains a `snapshot_id` in JSON format and the HTTP status code in the response header is `200` OK. The `snapshot_id` can be used to identify your playlist version in future requests. On a success

application/json

Body

snapshot_id

string

optional

The snapshot_id can be used to identify your playlist version in future requests.

🟢201On a successful **reorder** operation, the response body contains a `snapshot_id` in JSON format and the HTTP status code in the response header is `200` OK. The `snapshot_id` can be used to identify your playlist version in future requests. On a success

🔴500500

Modified at 2022-09-12 10:04:50

Add Items to a Playlist

Get a List of a User's Playlists