VL Group

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
  },
  etc...
]

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

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)",
   "value":
   [
      {
         "id":2307961,
         "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.

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)",
   "value":[]
}

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