VL Group

Rhymba v3.6 Documentation

Verifying Items

Before you report a purchase to us, wouldn't it be nice to know if it's going to be successful? In other words, wouldn't it be great to know what, if any, items in the attempted purchase might not be available for sale for various reasons (not whitelisted, not release yet, content was taken down by the labels, etc.)?

Yeah, well, sometimes life is pretty great. Enter GetInvalidItems.

Get Down With GetInvalidItems

The GetInvalidItems method in the Purchases API validates a list of content against your system/application's whitelist rules, the content's delivery rules & current status, and confirms that the information you're going to pass to us is all up to snuff. Here's how it works.

  1. You generate your hashed request access token for the method GetInvalidItems.
  2. Generate a POST to the URL https://purchases.mcnemanager.com/Purchases.svc/GetInvalidItems?$format=json&countryCode=US and POST data in a field called purchasedItems, as described below.
    • https://purchases.mcnemanager.com/Purchases.svc/GetInvalidItems? is the base method URL.
    • Next up you can choose to receive the response in JSON or XML format with the query string parameter $format=json or $format=atom. If you omit this, it'll default to XML/Atom.
    • Finally, you must tell us the two-letter country code for the country of purchase, such as &countryCode=US. You can find a complete list of valid country codes on the Country & Currency Codes page.
  3. If any of the supplied items are invalid a response will be returned in the format requested by the $format argument. See below for an example of the return in JSON.
  4. ... Profit. (Hopefully.)

The purchasedItems Collection

As a part of your POST, you should pass an array of the content you're attempting to validate as well as the purchase details. It's in the following JSON structure:

     "contenttype": 1,
     "productid": 2307961,
     "retail": 9.99,
     "tax": 0,
     "discountamount": 0,
     "saletype": 0,
     "deliverytype": 2,
     "promotiondescription": null,
     "servicetype": 0,
     "quantity": 1
     "contenttype": 0,
     "productid": 2307959,
     "retail": 0.99,
     "tax": 0,
     "discountamount": 0.10,
     "saletype": 0,
     "deliverytype": 2,
     "promotiondescription": "Winter Sale",
     "servicetype": 0,
     "quantity": 1

The table below walks you through all of the fields for entries in the purchasedItems collection.

Field Name Type Description Example
contenttype integer The type of this content item being purchased:
  1. Media / track
  2. Album
"contenttype": 1
productid integer VL Group's content ID, either a media ID or album ID, for this track or album; it can be found as the "id" field in an Album or Media object returned from the Search API. "productid": 2307961
retail decimal The price of sale for this specific item, excluding any taxes. "retail": 0.99
tax decimal Amount of taxes to be charged to the end user for this single item. "tax": 0
discountamount decimal What, if any, discount the user received vs. our suggested retail price. If this is non-zero, you must provide a promotiondescription. "discountamount": 0.10
saletype integer The type of the sale; this will be 0 for all digital download sales, which is the most common, but other values include:
  1. Digital Download
  2. Playlist
  3. Ringtone
  4. Promotional giveaway (differs from a free digital download!)
  5. Non-compulsory stream
  6. Compulsory license-based stream
"saletype": 0
deliverytype integer How the content is to be/was delivered. Most implementations will use 2, but the options are:
  1. Mobile
  2. Kiosk
  3. Web
  4. Stream (non-web)
"deliverytype": 2
promotiondescription string If discountamount is not 0.00, a textual description of why the content was discounted, such as a discount code used. Otherwise, this should be null. "promotiondescription": "discount code aabbccdd"
servicetype integer The store/service sale type. Almost all implementations are 0, Pay Per Use.
  1. Pay Per Use (PPU)
  2. Subscription
"servicetype": 0
quantity integer Quantity of this single item sold. Usually 1. "quantity": 1

JSON Returned For Invalid Items

If one or more items in your purchasedItems collection are invalid for any reason, you'll receive something like the following (if you specified JSON as the $format above).

   "odata.metadata": "https://purchases.mcnemanager.com/Purchases.svc/$metadata#Collection(PurchaseDataProvider.ItemCheck)",
         "saletype": "digitaldownload",
         "contenttype": "album",
         "allowed": false,
         "message": "Album not allowed for sale type in region"

You should remove the invalid item(s) from your application's cart, or display messaging to your end user to do so, before proceeding to ReportPurchase.

Use the Exampler.js widget below to see an example of an invalid request. Note: we're ignoring our own recommendations about not doing this client-side in the interest of a demo. You should not expose this sort of functionality to JavaScript in production.


A List Of All Messages & Their Meaning

As of this writing, the following is an inclusive list of the various error messages that will be returned if one or more items in your request fail purchase validation.

Album/track not allowed for sale type in region

You'll receive this error message if an album or track is whitelisted for your system in one or more countries, but not in the specific country you're attempting to purchase it in.

Duplicate purchase

If your system/application is configured to use the Rhymba User Inventory service, you'll receive this error message if you're attempting to report a purchase using an external purchase ID (one from your system/application) for which we already have a purchase on file.

XYZ is not a registered user for system id

If your system/application is configured to use the Rhymba User Inventory service, you'll receive this error message if you're attempting to report a purchase for a user that we're unaware of in the User service.

No tracks from album are whitelisted for this system.

This error message means that you're attempting to report a purchase for an album that has no tracks available for your system/application due to whitelisting rules. The album itself may be visible to you, but no tracks would be delivered.

Promotion description must be supplied for Retail = 0

If you specify an item was "bought" for free (price = 0), you must specify a promotiondescription for the item.

System not whitelisted for content

The album or track you're attempting to purchase is not whitelisted for your system/application.

System not whitelisted for saletype

Your system/application is not whitelisted for the type of sale you specified.

System not whitelisted for track status

You're attempting to report a purchase for track(s) in a status your system/application is not permitted to purchase, such as prerelease content or tracks that have been taken down.

Track is over length limit or album has no tracks below length limit

This is an implementation-specific check; some of our streaming clients have asked us to limit the length of tracks their users are permitted to purchase in an interest to cut down on bandwidth costs.

JSON Returned If It's All Good

If all the items pass validation an empty collection will be returned.

   "odata.metadata": "https://purchases.mcnemanager.com/Purchases.svc/$metadata#Collection(PurchaseDataProvider.ItemCheck)",

This means that the purchasedItems collection you POSTed to this GetInvalidItems call is ready for ReportPurchase. It's time to move on!