When reordering items, the timestamp indicating when they were added and the user who added them will be kept untouched. In addition, the users following the playlists won’t be notified about changes in the playlists when the items are reordered.


PUT https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Request Parameters

Path Parameters

Path Parameter Value
playlist_id The Spotify ID for the playlist.

Header Fields

Header Field Value
Authorization 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 items in the current user’s public playlists requires authorization of the playlist-modify-public scope; reordering items in the current user’s private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.
Content-Type Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json

Body Parameters

Request Body Data Value Type Value
range_start integer Required. The position of the first item to be reordered.
range_length integer 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.
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.
insert_before integer Required. 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.
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.
snapshot_id string Optional. The playlist’s snapshot ID against which you want to make the changes.

Visualization of how reordering items works

visualization reordering items

Response Format

On success, 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 error, the header status code is an error code, the response body contains an error object, and the existing playlist is unmodified.

Example (moving the first item to the fifth position)

curl -i -X PUT "https://api.spotify.com/v1/playlists/0vXtvEeftmc2aVQD9QBWrQ/tracks" -H "Authorization: Bearer {your access token}" -H "Content-Type:application/json" --data "{ \"range_start\" : 0, \"insert_before\" : 4 }"
HTTP/1.1 200 OK
{ "snapshot_id" : "KsWY41k+zLqbx7goYX9zr+2IUZQtqbBNfk4ZOgEpIurvab4VSHhEL2L4za8HW6D0" }

Try it

Example (moving the second and third items to the fourth position)

curl -i -X PUT "https://api.spotify.com/v1/playlists/0vXtvEeftmc2aVQD9QBWrQ/tracks" -H "Authorization: Bearer {your access token}" -H "Content-Type:application/json" --data "{ \"range_start\" : 1, \"range_length\" : 2, \"insert_before\" : 3 }"
HTTP/1.1 200 OK
{ "snapshot_id" : "KsWY41k+zLqbx7goYX9zr+2IUZQtqbBNfk4ZOgEpIurvab4VSHhEL2L4za8HW6D0" }

Try it

NOTE: looking for PUT https://api.spotify.com/v1/users/{user_id}/playlists/{playlist_id}/tracks? Read the blog post.