Playlist transfer reconciliation should answer one question: what happened to each occurrence in the source playlist? Give every occurrence its own record, separate matching from destination writes, and retain unknown outcomes until evidence resolves them. A matching percentage alone cannot explain whether your application added an item, found it already present, or never confirmed the write.
For backend engineers responsible for production imports, the useful deliverable is a reconciliation worksheet. The design below belongs to your application. Its columns, categories and hypothetical counts do not represent a MusicAPI response schema.
Define what playlist transfer reconciliation must account for
Start with the source selection your application actually read. Preserve playlist identity, occurrence position and the boundaries of that read. Finish enumeration before treating the observed count as the complete denominator. If reading stops early, report an incomplete source inventory rather than calculating success against a partial list.
Use these distinctions throughout the import:
| Layer | Question | Evidence to retain |
|---|---|---|
| Source occurrence | Which selected entry are we accounting for? | Playlist, position, original identity and read context |
| Recording match | Which destination recording did we choose? | Candidate identity and selection rationale |
| Destination write | What happened when we tried to add it? | Attempt outcome or evidence that no write was necessary |
| Verification | What destination state did we observe? | Observation time, scope and occurrence evidence |
| Disposition | What should happen next? | Explicit outcome, reason and responsible actor |
Define completeness as an accounting invariant: every captured source occurrence has exactly one current disposition. Keep unresolved occurrences in that accounting. Completeness does not mean every item arrived successfully.
Keep inventory completeness separate from outcome completeness. You can explain every occurrence you captured while still failing to capture the entire source playlist. Record both conditions before telling a listener that reconciliation has finished.
Use the playlist transfer accuracy scorecard when evaluating a vendor. Use this worksheet when explaining an individual production import.
Separate source occurrences, recording matches and destination writes
Suppose the same recording appears at positions 4 and 19. Your matching work may resolve both entries to one destination recording. Your reconciliation worksheet still needs two rows because the listener selected two occurrences.
Use an application-owned occurrence key that combines the import, playlist and captured position. Never use the recording identifier alone as the row key. That would collapse the exact duplicates you need to explain.
Choose a duplicate policy before writing. Your application might preserve repeated occurrences or intentionally collapse them. If you collapse them, retain the extra source row with an explicit policy reason and a reference to the retained occurrence. Do not count that row as a newly added item.
Also distinguish playlist membership from library membership. Finding a recording somewhere in the destination account does not establish that the intended playlist contains the required occurrence. Define the destination scope of each observation.
Capture a source version when the provider exposes one. Spotify documents playlist version history and the snapshot_id response field in its playlist documentation, checked September 22, 2026. For other sources, record the available read context without implying that a timestamp guarantees a consistent snapshot.
If the source changes during enumeration, record that uncertainty. A later comparison against the listener’s edited playlist cannot explain the original selection unless you preserve what your application saw.
Work through a hypothetical count mismatch
Consider a hypothetical import containing 120 source occurrences and 112 unique recordings. The eight repeated occurrences remain in scope because this application intends to preserve duplicates. These numbers illustrate the worksheet design, not product performance.
At the reporting cutoff, the worksheet contains:
| Current disposition | Occurrences | Explanation |
|---|---|---|
| Added and verified | 96 | Write evidence and destination inspection support the intended occurrence |
| Already present and verified | 8 | The pre-existing destination satisfies the required occurrence |
| No acceptable match | 7 | Matching produced no candidate the application accepted |
| Match needs review | 4 | A candidate exists, but the application needs a decision |
| Write failed | 3 | The application recorded an explicit unsuccessful write |
| Write outcome unknown | 2 | The application lacks enough evidence to decide whether the write succeeded |
| Total | 120 | Every captured source occurrence has a disposition |
Assume the final five occurrences had accepted matches before their write attempts. The application therefore accepted matches for 109 occurrences: 96 + 8 + 3 + 2. It verified destination coverage for 104: 96 + 8.
Those figures answer different questions. An accepted-match rate of 109/120 does not establish a verified destination coverage rate of 109/120. Nor should the application report 104 new additions, because eight occurrences already existed.
The 112 unique recordings provide a third denominator. Keep that number available for analysis, but never divide occurrence counts by it. Label every metric with its unit.
This example also assumes that verification supports duplicate multiplicity. If your evidence only establishes that a recording appears somewhere in the playlist, leave repeated-occurrence coverage unresolved. Do not assign the same destination occurrence to several source rows merely to balance the total.
Build an application-owned reconciliation worksheet
Store one current row per source occurrence and retain the history behind each decision. A database table can support operations; a worksheet export can support inspection. Neither format changes the accounting model.
Use this minimum column set:
| Column group | Record |
|---|---|
| Source context | Import reference, source playlist, captured version or read interval, position |
| Source identity | Original item identifier and available title, artist and recording identifiers |
| Match decision | Proposed destination identifier, decision rationale and review outcome |
| Write history | Attempt reference, destination playlist, attempt time and observed response |
| Verification | Evidence reference, observation time, scope and multiplicity assessment |
| Current disposition | One outcome category, exception reason, next action and owner |
These are proposed application fields, not endpoint parameters. Populate them only from evidence your integration actually exposes. When you cannot associate an aggregate result with a particular occurrence, preserve the aggregate separately and leave the row unresolved.
MusicAPI reports unmatched and low-confidence items per item. Its transfer service also provides hosted results with match rates, unmatched items and a CSV export. Use those results as reconciliation inputs while retaining your own occurrence-level accounting.
Before designing destination inspection, check the supported features by music service. Make verification conditional on the reads your chosen integration supports. Do not promise playlist order or duplicate verification from evidence that only identifies a recording.
Keep match decisions and write decisions separate even when one worker performs both. A new candidate should not overwrite the record of an earlier write. Preserve enough history to explain why the current destination identity differs from an earlier proposal.
Route unresolved items to review without replaying the whole transfer
Drive recovery from the disposition and its evidence. Avoid a single retry button that treats every exception as another write request.
For a missing match, request another candidate or a listener decision. For a low-confidence candidate, show the source and proposed destination metadata together. Neither case calls for repeating successful writes.
For an explicit write failure, establish whether the cause still applies before scheduling another attempt. For an unknown write outcome, inspect destination state first when your integration supports that inspection. Treat a timeout as uncertainty, not proof that the destination rejected the operation.
Select only the occurrences that need further work. If your integration cannot target those occurrences, route them to review instead of implying that selective replay exists. Any broader rerun needs a separate assessment of its duplicate and overwrite behavior.
Read the music API error-handling guide alongside this design. Recovery policy decides whether an operation should run again; reconciliation records what your application currently knows about its effects.
Append each recovery attempt to the occurrence history. Update the current disposition only when new evidence supports the transition. Make repeated processing of the same evidence leave counts unchanged, and prevent older evidence from replacing a later confirmed decision.
Use per-item results to explain the completed transfer
Generate the listener summary from the worksheet categories. For the hypothetical example, the message could say: “We verified 104 of your 120 selected entries in the destination playlist. Seven have no accepted match, four need review, three writes failed, and two write outcomes remain unconfirmed.”
Follow that summary with the affected entries and their next actions. Let the listener distinguish a matching decision from a connection problem or an unknown write outcome. Avoid presenting every exception as a missing song.
Keep the report’s observation time visible. Reconciliation describes the destination state your application observed during this import. A later listener edit requires a new observation, not a retroactive change to the original evidence.
Apply the presentation principles in music library import UX to the results screen. Give support staff access to occurrence references and evidence history, while giving listeners clear explanations and decisions they can act on.
FAQ
Should one playlist’s unresolved items block the whole library import?
Choose the policy explicitly. Prefer separate playlist summaries plus a library-level rollup when independent playlists can finish without each other. Preserve unresolved counts in the rollup, and reserve any all-or-nothing behavior for workflows that actually require it.
How should cancellation appear in the worksheet?
Keep confirmed outcomes intact. Give entries that never reached a write attempt an explicit cancellation disposition. Preserve uncertainty for in-flight attempts until evidence resolves them. Cancellation describes the user’s instruction; it does not prove what happened to an operation already underway.
Which tests best validate the accounting model?
Test invariants with small fixtures: repeated recordings, incomplete source enumeration, an unknown write outcome, repeated evidence delivery and a source edit during reading. Assert that each captured occurrence retains one current disposition and that category totals equal the captured inventory. Separately assert that the report exposes an incomplete inventory.
For a hosted import with progress and results, review the MusicAPI transfer service documentation. Use it to assess the transfer flow, then map the available evidence into your application’s reconciliation worksheet.