Submit Music Releases to Digital Stores via the UMW API

Once a release reaches ready status in the UMW catalog, you can submit it for delivery to one or more digital stores. The delivery workflow lets you choose target stores, specify territory availability, monitor ingestion progress per store, and respond to any content issues that arise during a retailer’s review process. This guide covers the full delivery lifecycle from store selection to confirmed availability.

Delivery Lifecycle

Every delivery moves through a defined sequence of statuses. Understanding these states helps you build reliable polling logic and know when human intervention is required.

draft → validating → ready → submitted → in_review → delivered
                                                  ↘ rejected
                                                  ↘ action_required

Status	Description
`draft`	Delivery order created but not yet sent to stores
`validating`	UMW is running pre-delivery checks against store requirements
`ready`	Pre-delivery checks passed; delivery is queued for transmission
`submitted`	Delivery package transmitted to target stores
`in_review`	Stores have received the package and are processing it
`delivered`	Release is confirmed live on all requested stores
`action_required`	One or more stores flagged metadata or asset issues requiring your attention
`rejected`	One or more stores have rejected the release; see `rejection_reason` for details
`taken_down`	A takedown was processed and the release is no longer available on stores

Subscribe to the delivery.completed webhook event to receive real-time notifications when a delivery reaches a terminal state (delivered, rejected, or action_required) instead of polling the status endpoint. See the Webhooks guide to set up your endpoint.

Step-by-Step: Delivering a Release

List Available Stores

Retrieve the current list of supported digital stores along with their supported territories and delivery capabilities. Use the store_id values returned here when constructing your delivery request.

GET /v1/stores

Query parameters:

Parameter	Type	Description
`territory`	string	Filter stores by ISO 3166-1 alpha-2 territory code
`supports_delivery`	boolean	Return only stores that currently accept new deliveries
`limit`	integer	Number of results per page (default: `50`, max: `100`)

Sample response:

{
  "data": [
    {
      "store_id": "str_spotify",
      "name": "Spotify",
      "territories": ["WORLDWIDE"],
      "delivery_supported": true,
      "asset_requirements": {
        "audio_formats": ["audio/wav", "audio/flac"],
        "min_artwork_size": 3000,
        "max_track_count": 500
      }
    },
    {
      "store_id": "str_apple_music",
      "name": "Apple Music",
      "territories": ["WORLDWIDE"],
      "delivery_supported": true,
      "asset_requirements": {
        "audio_formats": ["audio/wav", "audio/flac"],
        "min_artwork_size": 3000,
        "max_track_count": 500
      }
    },
    {
      "store_id": "str_amazon_music",
      "name": "Amazon Music",
      "territories": ["US", "CA", "GB", "DE", "FR", "AU", "JP", "IT", "ES"],
      "delivery_supported": true,
      "asset_requirements": {
        "audio_formats": ["audio/wav"],
        "min_artwork_size": 3000,
        "max_track_count": 250
      }
    },
    {
      "store_id": "str_tidal",
      "name": "TIDAL",
      "territories": ["WORLDWIDE"],
      "delivery_supported": true,
      "asset_requirements": {
        "audio_formats": ["audio/wav", "audio/flac"],
        "min_artwork_size": 3000,
        "max_track_count": 500
      }
    }
  ],
  "meta": {
    "total": 48,
    "limit": 50,
    "cursor": null
  }
}

Submit a Delivery

Create a delivery order by specifying the release, target stores, and the territories where the release should be available. You can deliver to all supported store territories by passing "WORLDWIDE" in the territory_codes array.

POST /v1/deliveries

Request body:

{
  "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "store_ids": [
    "str_spotify",
    "str_apple_music",
    "str_amazon_music",
    "str_tidal",
    "str_youtube_music",
    "str_deezer"
  ],
  "territory_codes": ["WORLDWIDE"],
  "pricing_tier": "standard",
  "pre_order": false,
  "notes": "Priority release for Q3 campaign. Ensure Spotify editorial pitch is submitted separately."
}

Response:

{
  "id": "dlv_01HXK9P2ZQMB4NVYJR3T5C8WD",
  "status": "validating",
  "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "store_ids": [
    "str_spotify",
    "str_apple_music",
    "str_amazon_music",
    "str_tidal",
    "str_youtube_music",
    "str_deezer"
  ],
  "territory_codes": ["WORLDWIDE"],
  "created_at": "2024-06-15T12:00:00Z",
  "updated_at": "2024-06-15T12:00:00Z"
}

Store the id value as your delivery_id for status polling.

Monitor Delivery Status

Poll the delivery endpoint to track progress. Each entry in the stores array reflects the per-store ingestion state independently, so some stores may confirm delivery before others.

GET /v1/deliveries/{delivery_id}

Sample response (in progress):

{
  "id": "dlv_01HXK9P2ZQMB4NVYJR3T5C8WD",
  "status": "in_review",
  "release_id": "rel_01HXK3AB7NMCPQ2XYZ9WD4EF5",
  "territory_codes": ["WORLDWIDE"],
  "stores": [
    {
      "store_id": "str_spotify",
      "name": "Spotify",
      "status": "delivered",
      "store_url": "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy",
      "delivered_at": "2024-06-16T08:30:00Z"
    },
    {
      "store_id": "str_apple_music",
      "name": "Apple Music",
      "status": "in_review",
      "store_url": null,
      "delivered_at": null
    },
    {
      "store_id": "str_amazon_music",
      "name": "Amazon Music",
      "status": "in_review",
      "store_url": null,
      "delivered_at": null
    },
    {
      "store_id": "str_tidal",
      "name": "TIDAL",
      "status": "delivered",
      "store_url": "https://tidal.com/browse/album/298456712",
      "delivered_at": "2024-06-16T09:15:00Z"
    }
  ],
  "created_at": "2024-06-15T12:00:00Z",
  "updated_at": "2024-06-16T09:15:00Z"
}

The top-level status field reflects the aggregate state across all stores. It will not advance to delivered until every store in the delivery order has confirmed availability.

Handle Rejections and Action-Required States

If a store rejects a delivery or flags an issue, the delivery status will change to rejected or action_required. Inspect the per-store rejection_reason field to understand what needs to be corrected.Sample rejection response:

{
  "id": "dlv_01HXK9P2ZQMB4NVYJR3T5C8WD",
  "status": "action_required",
  "stores": [
    {
      "store_id": "str_apple_music",
      "name": "Apple Music",
      "status": "action_required",
      "rejection_reason": "ISRC conflict detected on track 3. The ISRC USPAR2400103 is already registered to a different recording in the Apple Music catalog.",
      "rejection_code": "ISRC_CONFLICT",
      "flagged_at": "2024-06-17T11:00:00Z"
    }
  ]
}

Resolution workflow:

Review the rejection_reason and rejection_code for each affected store.
Update the relevant release or track metadata using PATCH /v1/releases/{release_id} or PATCH /v1/tracks/{track_id}.
Resubmit the delivery to the affected stores only:

POST /v1/deliveries/{delivery_id}/resubmit

{
  "store_ids": ["str_apple_music"]
}

Do not create a new delivery order to fix a rejection on an existing delivery. Use the resubmit endpoint to avoid duplicate delivery records and potential duplicate-content flags at the store level.

Managing Takedowns

To remove a release from stores, issue a takedown request against an existing delivery:

POST /v1/deliveries/{delivery_id}/takedown

{
  "store_ids": ["str_spotify", "str_apple_music"],
  "reason": "rights_dispute",
  "notes": "Pending licensing resolution with co-publisher."
}

Takedowns typically propagate within 24–72 hours depending on individual store processing times. The delivery status will update to taken_down once all requested stores confirm removal.

Get Started

Platform Guides

Platform Reference

Submit Music Releases to Digital Stores via the UMW API

Delivery Lifecycle

Step-by-Step: Delivering a Release

Managing Takedowns

​Delivery Lifecycle

​Step-by-Step: Delivering a Release

​Managing Takedowns

Delivery Lifecycle

Step-by-Step: Delivering a Release

Managing Takedowns