Track Relinking | Spotify for Developers

https://developer.spotify.com/documentation/web-api/concepts/track-relinking • 270 KB fetched
Open original page
Track Relinking | Spotify for Developers Skip to content

* Documentation Documentation Products
* Web API

* Web Playback SDK

* Ads API

* iOS

* Android

* Embeds

* Commercial Hardware

* Open Access

* Spotify Soloist
Guidelines
* Design

* Accessibility

* Legal

* Community

0

* Documentation Documentation Products
* Web API

* Web Playback SDK

* Ads API

* iOS

* Android

* Embeds

* Commercial Hardware

* Open Access

* Spotify Soloist
Guidelines
* Design

* Accessibility

* Legal

* Community

Web API

* Overview

* Getting started

* Building with AI

* Concepts Concepts Concepts
* Access Token

* API calls

* Apps

* Authorization

* Redirect URIs

* Playlists

* Quota modes

* Rate limits

* Scopes

* Spotify URIs and IDs

* Track Relinking

* Tutorials Tutorials Tutorials
* Authorization code

* Authorization code PKCE

* Client credentials

* Implicit grant [Deprecated]

* Refreshing tokens

* Migration: Implicit grant to Authorization code

* Migration: Insecure redirect URI

* Migration: February 2026 Dev Mode Changes

* How-Tos How-Tos How-Tos
* Display your Spotify profile data in a web app

* Changelog Changelog Changelog
* July 2026

* May 2026

* March 2026

* February 2026

Reference
* Albums Albums Albums
* Get Album

* Get Several Albums

* Get Album Tracks

* Get User's Saved Albums

* Save Albums for Current User

* Remove Users' Saved Albums

* Check User's Saved Albums

* Get New Releases

* Artists Artists Artists
* Get Artist

* Get Several Artists

* Get Artist's Albums

* Get Artist's Top Tracks

* Get Artist's Related Artists

* Audiobooks Audiobooks Audiobooks
* Get an Audiobook

* Get Several Audiobooks

* Get Audiobook Chapters

* Get User's Saved Audiobooks

* Save Audiobooks for Current User

* Remove User's Saved Audiobooks

* Check User's Saved Audiobooks

* Categories Categories Categories
* Get Several Browse Categories

* Get Single Browse Category

* Chapters Chapters Chapters
* Get a Chapter

* Get Several Chapters

* Episodes Episodes Episodes
* Get Episode

* Get Several Episodes

* Get User's Saved Episodes

* Save Episodes for Current User

* Remove User's Saved Episodes

* Check User's Saved Episodes

* Genres Genres Genres
* Get Available Genre Seeds

* Library Library Library
* Save Items to Library

* Remove Items from Library

* Check User's Saved Items

* Markets Markets Markets
* Get Available Markets

* Player Player Player
* Get Playback State

* Transfer Playback

* Get Available Devices

* Get Currently Playing Track

* Start/Resume Playback

* Pause Playback

* Skip To Next

* Skip To Previous

* Seek To Position

* Set Repeat Mode

* Set Playback Volume

* Toggle Playback Shuffle

* Get Recently Played Tracks

* Get the User's Queue

* Add Item to Playback Queue

* Playlists Playlists Playlists
* Get Playlist

* Change Playlist Details

* Get Playlist Items [DEPRECATED]

* Update Playlist Items [DEPRECATED]

* Add Items to Playlist [DEPRECATED]

* Remove Playlist Items [DEPRECATED]

* Get Playlist Items

* Update Playlist Items

* Add Items to Playlist

* Remove Playlist Items

* Get Current User's Playlists

* Create Playlist

* Get User's Playlists

* Create Playlist for user

* Get Featured Playlists

* Get Category's Playlists

* Get Playlist Cover Image

* Add Custom Playlist Cover Image

* Search Search Search
* Search for Item

* Shows Shows Shows
* Get Show

* Get Several Shows

* Get Show Episodes

* Get User's Saved Shows

* Save Shows for Current User

* Remove User's Saved Shows

* Check User's Saved Shows

* Tracks Tracks Tracks
* Get Track

* Get Several Tracks

* Get User's Saved Tracks

* Save Tracks for Current User

* Remove User's Saved Tracks

* Check User's Saved Tracks

* Get Several Tracks' Audio Features

* Get Track's Audio Features

* Get Track's Audio Analysis

* Get Recommendations

* Users Users Users
* Get Current User's Profile

* Get User's Top Items

* Get User's Profile

* Follow Playlist

* Unfollow Playlist

* Get Followed Artists

* Follow Artists or Users

* Unfollow Artists or Users

* Check If User Follows Artists or Users

* Check if Current User Follows Playlist

Web API
* Overview

* Getting started

* Building with AI

* Concepts Concepts Concepts
* Access Token

* API calls

* Apps

* Authorization

* Redirect URIs

* Playlists

* Quota modes

* Rate limits

* Scopes

* Spotify URIs and IDs

* Track Relinking

* Tutorials Tutorials Tutorials
* Authorization code

* Authorization code PKCE

* Client credentials

* Implicit grant [Deprecated]

* Refreshing tokens

* Migration: Implicit grant to Authorization code

* Migration: Insecure redirect URI

* Migration: February 2026 Dev Mode Changes

* How-Tos How-Tos How-Tos
* Display your Spotify profile data in a web app

* Changelog Changelog Changelog
* July 2026

* May 2026

* March 2026

* February 2026

Reference
* Albums Albums Albums
* Get Album

* Get Several Albums

* Get Album Tracks

* Get User's Saved Albums

* Save Albums for Current User

* Remove Users' Saved Albums

* Check User's Saved Albums

* Get New Releases

* Artists Artists Artists
* Get Artist

* Get Several Artists

* Get Artist's Albums

* Get Artist's Top Tracks

* Get Artist's Related Artists

* Audiobooks Audiobooks Audiobooks
* Get an Audiobook

* Get Several Audiobooks

* Get Audiobook Chapters

* Get User's Saved Audiobooks

* Save Audiobooks for Current User

* Remove User's Saved Audiobooks

* Check User's Saved Audiobooks

* Categories Categories Categories
* Get Several Browse Categories

* Get Single Browse Category

* Chapters Chapters Chapters
* Get a Chapter

* Get Several Chapters

* Episodes Episodes Episodes
* Get Episode

* Get Several Episodes

* Get User's Saved Episodes

* Save Episodes for Current User

* Remove User's Saved Episodes

* Check User's Saved Episodes

* Genres Genres Genres
* Get Available Genre Seeds

* Library Library Library
* Save Items to Library

* Remove Items from Library

* Check User's Saved Items

* Markets Markets Markets
* Get Available Markets

* Player Player Player
* Get Playback State

* Transfer Playback

* Get Available Devices

* Get Currently Playing Track

* Start/Resume Playback

* Pause Playback

* Skip To Next

* Skip To Previous

* Seek To Position

* Set Repeat Mode

* Set Playback Volume

* Toggle Playback Shuffle

* Get Recently Played Tracks

* Get the User's Queue

* Add Item to Playback Queue

* Playlists Playlists Playlists
* Get Playlist

* Change Playlist Details

* Get Playlist Items [DEPRECATED]

* Update Playlist Items [DEPRECATED]

* Add Items to Playlist [DEPRECATED]

* Remove Playlist Items [DEPRECATED]

* Get Playlist Items

* Update Playlist Items

* Add Items to Playlist

* Remove Playlist Items

* Get Current User's Playlists

* Create Playlist

* Get User's Playlists

* Create Playlist for user

* Get Featured Playlists

* Get Category's Playlists

* Get Playlist Cover Image

* Add Custom Playlist Cover Image

* Search Search Search
* Search for Item

* Shows Shows Shows
* Get Show

* Get Several Shows

* Get Show Episodes

* Get User's Saved Shows

* Save Shows for Current User

* Remove User's Saved Shows

* Check User's Saved Shows

* Tracks Tracks Tracks
* Get Track

* Get Several Tracks

* Get User's Saved Tracks

* Save Tracks for Current User

* Remove User's Saved Tracks

* Check User's Saved Tracks

* Get Several Tracks' Audio Features

* Get Track's Audio Features

* Get Track's Audio Analysis

* Get Recommendations

* Users Users Users
* Get Current User's Profile

* Get User's Top Items

* Get User's Profile

* Follow Playlist

* Unfollow Playlist

* Get Followed Artists

* Follow Artists or Users

* Unfollow Artists or Users

* Check If User Follows Artists or Users

* Check if Current User Follows Playlist

Track Relinking

The availability of a track depends on the country registered in the user’s
Spotify profile settings. Often Spotify has several instances of a track in its
catalogue, each available in a different set of markets. This commonly happens
when the track the album is on has been released multiple times under different
licenses in different markets.

These tracks are linked together so that when a user tries to play a track that isn’t available in their own market, the Spotify mobile, desktop, and web players try to play another instance of the track that is available in the user’s market.

Track Relinking in the Web API

If your application supplies a market parameter in its call to the following track endpoints, the Web API will attempt to return information about alternative tracks that are available in the specified market:

* Get a Track

* Get Several Tracks

* Get an Album

* Get Several Albums

* Get an Album’s Tracks

* Get a Playlist's Items

* Get a User’s Saved Tracks

When using the market query parameter, the response will contain another
instance of the tracks only if the original track is unavailable and other
instances of the track are available.

For example, the track “Heaven and Hell” by William Onyeabor is not available
in the United States (market code US ), as shown by the request to retrieve
the track’s metadata:

_ 10 curl -X GET "https://api.spotify.com/v1/tracks/6kLCHFM39wkFjOuyPGLGeQ"`

_ 10 {

_ 10 ...

_ 10 available_markets: [ "AT", "AU", "BE", "DK", "ES", "FI",

_ 10 "FR", "HU", "IT", "PL", "PT", "SE",

_ 10 "SK", "TR", "TW" ],

_ 10 ...

_ 10 uri: "spotify:track:6kLCHFM39wkFjOuyPGLGeQ"

_ 10 }

If a market query parameter specifying the US market is appended to the call,
the Web API recognizes that the specified track is unplayable and instead
returns information about a track that is playable in the specified market. In
addition it returns information about the original track:

_ 10 curl -X GET "https://api.spotify.com/v1/tracks/6kLCHFM39wkFjOuyPGLGeQ?market=US"`

_ 15 {

_ 15 ...

_ 15 is_playable: true

_ 15 linked_from: {

_ 15 external_urls: {

_ 15 spotify: "https://open.spotify.com/track/6kLCHFM39wkFjOuyPGLGeQ"

_ 15 },

_ 15 href: "https://api.spotify.com/v1/tracks/6kLCHFM39wkFjOuyPGLGeQ",

_ 15 id: "6kLCHFM39wkFjOuyPGLGeQ",

_ 15 type: "track",

_ 15 uri: "spotify:track:6kLCHFM39wkFjOuyPGLGeQ"

_ 15 },

_ 15 ...

_ 15 uri: "spotify:track:6ozxplTAjWO0BlUxN8ia0A"

_ 15 }

There are a number of important differences between the response you get with
and without the market query parameter.

When the market parameter is supplied:

* The available_markets property in the Track object is replaced by the is_playable property. (Since the request contains the market query parameter, there’s no need for the available_markets property to determine if the user can play the track or not.)

* If the track has been relinked, the response contains a linked_from object containing information about the original track. In the example above, the track that was requested had the Spotify URI spotify:track:6kLCHFM39wkFjOuyPGLGeQ . Since it’s been relinked, this original track URI can be found in the linked_from object. The parent track object now contains metadata about the relinked track with URI spotify:track:6ozxplTAjWO0BlUxN8ia0A .

* If the is_playable property is false , the original track is not available in the given market, and Spotify did not have any tracks to relink it with. The track response will still contain metadata for the original track, and a restrictions object containing the reason why the track is not available: "restrictions" : {"reason" : "market"} .

* If the is_playable property is true , the linked_from object may or may not exist depending on whether the original track was available in the market. If the linked_from object exists, the original track has been relinked.

IMPORTANT: If you plan to do further operations on tracks (for example, removing the track from a playlist or saving it to “Your Music”), it is important that you operate on the original track id found in the linked_from object. Using the ID of the linked track returned at the root level will likely return an error or other unexpected result.

Valid market query parameter values are ISO 3166-1 alpha-2 codes , as well as from_token . If from_token is used, an access token tied to a user must be supplied; from_token is the same thing as setting the market parameter to the user’s country .

Footer
Documentation

* Web API

* Web Playback SDK

* Ads API

* iOS

* Android

* Embeds

* Commercial Hardware

Guidelines

* Design

* Accessibility

Community

* News

* Forum

Legal

* Developer Terms

* Developer Policy

* Compliance Tips

* Third Party Licenses

Legal Cookies © 2026 Spotify AB
Track Relinking | Spotify for Developers

Links found on this page
