Skip to main content
The UMW API changelog documents every change to the public API surface — including new endpoints, modified response schemas, deprecations, and bug fixes. Reviewing this page regularly ensures your integration remains compatible with the latest platform capabilities and gives you advance notice of any upcoming breaking changes.

​
Versioning Policy

UMW uses date-based versioning for the changelog. The current API version is v1, reflected in all endpoint paths (e.g., https://api.umwrecordingsinc.com/v1/). Within v1, backwards-compatible additions — such as new optional request fields, new response fields, or new endpoints — are released continuously and do not require a version bump or any changes to your integration. Breaking changes are defined as any modification that would cause a correctly implemented v1 integration to fail or behave incorrectly. These include removing fields, changing field types, altering required field semantics, or removing endpoints. All breaking changes are announced at least 90 days in advance via this changelog, email notification to registered technical contacts, and in-platform banner notices. Deprecated features display a sunset date and are not removed before that date.

​
2024-06-01

Added
  • POST /v1/releases/{release_id}/submit — A new dedicated submit endpoint that provides an explicit, auditable submission step for releases. This replaces the previous pattern of transitioning a release to submitted status by setting status: submitted in a PATCH request. The new endpoint returns a submission object with a unique submission_id, timestamp, and initial review status.
  • Idempotency-Key support on all mutating endpoints (POST and PATCH). Include an Idempotency-Key header with a UUID v4 value to safely retry failed requests without risking duplicate resource creation. Keys are stored for 24 hours. See the Idempotency reference for full details.
  • delivery.completed webhook event — fired when a delivery has been successfully distributed to all requested territories and stores. Subscribe via POST /v1/webhooks with event_type: delivery.completed.
Changed
  • GET /v1/royalties now supports cursor-based pagination using limit and cursor query parameters. The previous offset-based page and per_page parameters continue to function but are deprecated (see the 2024-04-15 entry below). Cursor-based pagination is significantly more efficient for large royalty datasets and is the recommended approach for all new integrations.
  • Royalty record responses now include a net_amount field alongside the existing gross_amount field. The net_amount reflects gross earnings minus applicable distribution fees and withholding taxes for the statement period. Both fields are denominated in the currency specified by the currency field on the same record.
Fixed
  • Fixed an issue where the territory field on track creation (POST /v1/tracks) incorrectly rejected valid ISO 3166-1 alpha-2 codes for certain newly supported markets. All codes listed in GET /v1/stores/territories are now accepted consistently.

​
2024-04-15

Added
  • GET /v1/statements/{statement_id}/line-items — a new endpoint for retrieving the individual line items that make up a royalty statement. Each line item includes the track ISRC, store, territory, play count, per-unit rate, and calculated earnings for the statement period. Supports limit and cursor pagination.
  • Sandbox pre-seeded store catalog — the sandbox environment now includes a representative catalog of fictional stores and territories, allowing you to test delivery and royalty workflows end-to-end without configuring store relationships manually. See the Sandbox guide for the full list of pre-seeded resources.
Changed
  • payout status enum extended with the on_hold value. A payout enters on_hold status when it is pending additional identity verification or when a compliance review has been initiated. Payouts in this status cannot be released until the hold is resolved. Update any status-based logic in your integration to handle this value gracefully.
Deprecated
  • POST /v1/releases — status field for submission. Setting status: submitted via a PATCH /v1/releases/{release_id} request to trigger release submission is deprecated and will stop functioning on 2024-09-01. Migrate to the new POST /v1/releases/{release_id}/submit endpoint, which provides richer submission confirmation and supports idempotency. The status field will remain writable for all other valid status transitions until the sunset date.

​
2024-02-01

Added
  • Initial v1 API release. The UMW Developer Platform REST API is now available to approved partners. The initial release includes full support for catalog management (/v1/releases, /v1/tracks, /v1/assets), digital delivery (/v1/deliveries), royalty reporting (/v1/royalties, /v1/statements), and payout workflows (/v1/payouts).
  • OAuth 2.0 client credentials flow for enterprise clients. Enterprise-tier organizations can authenticate using the client credentials grant type for server-to-server integrations, in addition to the standard API key authentication available to all partners.
  • DDEX ERN 4.x sandbox support. Enterprise partners with existing DDEX pipelines can now deliver NewReleaseMessage and PurgeReleaseMessage payloads to the sandbox environment for integration testing. Contact your UMW account manager to enable DDEX mode. See the DDEX reference for details.
Subscribe to changelog updates via webhook by registering for the api.changelog.published event using POST /v1/webhooks. Each time a new changelog entry is published, UMW will deliver a webhook payload summarizing the changes to your registered endpoint. The api.changelog.published event is available on the Enterprise tier only.