Download service
1. Store the ‘Purchase ID’
When you make a request to the user/deliveritem endpoint the response will return a ‘Purchase ID’, also known as a ‘Basket ID’. Aside from your own Transaction ID value that you place in requests you must also store the Purchase ID in the API response as this will be the primary reference point when looking at a transaction and also used for any Refund API requests.
2. Logging a Transaction
The user/deliveritem endpoint must only be used once per transaction. If you use any form of ‘auto retry’ functionality on this endpoint for a given item it will log multiple transactions on our side for that item which has consequences with reporting, so it’s important to only make 1 request to the endpoint per item (eg: a track or album) per transaction. See the next point for how to handle any suspected failed requests. Please note that a purchase should be logged at the point of transaction.
3. Handling Failed Requests
If you believe an API request to user/deliveritem has failed and you didn’t receive a Purchase ID then you must contact your Client Success Manager for assistance.
4. Handling Failed Transactions
If any failed transactions occur on your side, for whatever reason, and a request to the user/deliveritem endpoint has been made, you must log these failed transactions using the refund API to ensure they are excluded from being reported as legitimate sales. Note the Refund API consists of 2 endpoints: Release refunds (ie: for full product refunds), and Track Refunds.
Any failed transactions that are not logged on the Refund API are billable and will be included in any content invoices.
5. Handling Refunds
a) Log Refunds by 00:00 UTC on the 4th day of the month
To ensure that refunds are processed on time and excluded from our label reports you must make sure that any refunds are logged before midnight UTC on the 4th day of the month. For example, for any refunds relating to July, you would log them before midnight UTC on 4th August. If not logged with us by that time resulting in the transactions being reported to the labels then they will be billable in any content invoices.
b) Log The Correct Item - product(s) or track(s)
If a product has been purchased by your end user and you have subsequently refunded them you must ensure that the very same item is logged via the applicable Refund API endpoint.
For example, if the item purchased and refunded is a release (eg: album or EP) then the release must be logged on the Release refund endpoint. If the item purchased and refunded is a track then the track must be logged on the Track refund endpoint.
c) Refunding ‘Smart Bundles’
If you need to log a refund for a Smart Bundle then the behaviour is slightly different to logging a refund for a Release; instead you must use the Track refund endpoint and log a refund individually for each track.
6. Users Accessing Their Content (when MassiveMusic provides the user lockers)
a) The user/deliveritem endpoint must only be used once to deposit content to the end user’s locker when the transaction has taken place. Once the initial transaction has taken place then you must use other endpoints for the user to access their content, the main options are;
- user/download/purchase - User can download all the items within a transacted purchase.
- user/download/release - User can download a specific purchased release.
- user/downloadtrack - User can download a specific purchased track.
- user/locker - User can access their whole locker.
b) User re-downloads from their lockers are restricted to a total of 10 downloads per locker item.
7. Non-purchased Content / Zero-pricing
In scenarios whereby there is no financial transaction taking place, such as providing free content to users (eg: promotions), or points-based loyalty schemes as some examples, (all of which would require approval from the label that there is no payment due to them for the free content) you must state a zero value (0) in the ‘retailPrice’ parameter of the API request.
Also, in all such cases please do not use the word ‘free’ in your Transaction Ref parameter value as this can cause ambiguity in the associated reporting.
8. Creating Reports and Testing Data/ DDEX Partner Identifier
a) When setting up your internal reporting you must consult with your Client Success Manager to ensure that the data is aligned correctly without any errors.
We have a suggested header template to use for reporting and can provide this to you upon request. Whilst this template is not mandatory we recommend using this format so that our data and reports can be fully aligned.
b) Prior to launching we must carry out a data validation test to ensure that both the logged data on the API and the related report output is correct on both sides. Consult your Client Success Manager when you’re ready to conduct this test activity, further information is provided in the next section.
c) MassiveMusic uses DDEX Reporting, so we require a DPID (DDEX Party Identifier) for all of our partners. When getting started with discussing reporting requirements with MassiveMusic, you will need to visit http://dpid.ddex.net/reg.php and enter the service details, you will then get a code which MassiveMusic will then associate with your partnerID in the Data Warehouse.
9. API Implementation Security For External User Accounts
When using non-MassiveMusic external user accounts your API credentials must never be stored or passed on to end user devices or client apps. They must always be kept within a trusted environment, such as a secure server. Any generated signed URLs can be sent to the end user device.
Additional API keys with restricted permissions can be provided for making non-user related API calls directly from clients.
10. Application Testing and Approval
We must test and approve your application prior to launch to ensure it is fully compliant with the agreed licenses, this is a measure that ensures you are safe to launch the application without breaching any terms. The details of the testing and approval process is twofold as follows:
a) Informal Review - you must provide us with a beta / test version Android version (apk) and an iOS version that we can test, at least 4 weeks prior to your planned launch date. This allows us enough time to conduct an initial informal check of the application to see if we can spot any compliance issues at an early stage and allow you plenty of time to address any failure points.
b) Formal Approval - you must also provide us with your final application build at least 10 days prior to your launch date so that we can conduct a formal approval process. If approval is declined we will notify you of the failure point(s) which should then be rectified before re-submitting again for the approval process.
The application(s) must be fully approved before a launch can take place.
Note it is not permitted to make available publicly any sort of application version prior to our approval process. This includes no non-private Beta testing and no submittals to Google Play / the App store.
11. Use of Content in your Application
Due to the strict requirements from the labels concerning use of their content it is not permitted to use any label content within your application, for testing or otherwise, until the labels have provided specific approval for use of their content.
12. Indicating ‘Explicit’ Content
Where content is marked with an ‘Explicit’ flag you must reflect the same within the product title and the track title. This is usually expressed at the end of the name in brackets. eg: (Explicit)
13. Processing takedowns
Where a label has initiated a content ‘takedown’ MassiveMusic shall remove that content from our API and communicate the takedown via an event message to your webhook. You must observe the takedown immediately and remove the content from your service within 24 hours.
14. Processing Metadata Updates
Metadata updates are communicated via real-time event messages to a webhook you set up. Please refer to this page here.
16. Partner-side Payments / Verifying User Location
If you are using your own transaction mechanism to take payments from end users then you must use the customer billing address to verify the location of the end user.
17. Provide us with a Launch Plan and Integration Updates
To ensure your launch proceeds as smoothly as possible, please provide us with full details of your launch plans at the earliest opportunity, including any key development and launch dates.
Please allow a 4 week period prior to the launch date, which we can reserve for application and report testing.
Specifically, inform your Client Success Manager with:
- Planned Launch Date.
- Planned Final Testing Date (at least 4 weeks prior to launch date).
- Any other notable information, beta testing plans and key dates.
- Updates on notable developments during your integration stage.
Updated 5 months ago