Support Center/Developer Knowledge Base/Topspin APIs
Store API V2
David Widaman
posted this on July 20, 2011 10:49 pm
Introduction
The Topspin V2 Store API is a specialized subset of the V1 Store API designed to build store fronts. The V2 Store API is the backing API behind the current Topspin Store / Spinshop.com sites as well as the V2 Facebook store.
The store is designed around 2 simple operations: Fetch a page of purchase buttons (scoped by tag and page number), and detail a single offer. The store always returns a result for a single artist, and unlike the V1 Store API, it returns only purchase buttons and the associated streaming widget for that purchase button.
The V2 API will not include promotional widgets (streaming players, etc) like the V1 API. In the near future, we will be providing a V2 Promotion API that is designed to return the promotional widget content in the backend.
As a result, the V2 Store API has two methods.
Method 1: Page Query
- Requires: api_user, api_key, artist_id, tag_name
- Optional: page_number, offset, limit
- api_user: in the form of user@example.com - your API user information can be found athttp://app.topspin.net/account/profile/
in the "API Information" section next to "API User" - api_key: in the form of a alphanumeric string - can be found at http://app.topspin.net/account/profile/ in the "API Information" section next to "API Key".
- artist_id: Number found in "Artist Profile" next to "Artist ID" at http://app.topspin.net/account/settings/
- tag_name: Tag names created in the Sell section of the app. There is a single reserved name - "ts_all_products" which returns all products in the catalog. If you have tags with special characters (e.g. spaces), use URL encoding - 'Back Catalog' would be 'Back%20Catalog'
- page_number: Integer defining which page to retrieve from the tag. Use with page form.
- offset: for a query, how many results to offset from 0. Use in offset/limit form.
- limit - maximum number of results to return. Use in offset/limit form.
Page form Sample call: Tag "ts_all_products", artist ID 991, page 1:
General Form:
Offset/Limit form Sample call: 10 items from artist ID 991, "tag ts_all_products", starting at offset 0, would be:
General Form:
This call is designed to create a "page" of offers, listing multiple offers. This call returns total pages, current page, total entries, and entries per page as part of its response. Store configuration information is included, as well as top-level order information that can be retrieved via the detail query.
Page Query Response
Method 2: Detail Query
- Requires: api_user, api_key, offer_id
- api_user: in the form of user@example.com - your API user information can be found athttp://app.topspin.net/account/profile/ in the "API Information" section next to "API User"
- api_key: in the form of a alphanumeric string - can be found at http://app.topspin.net/account/profile/ in the "API Information" section next to "API Key".
- offer_id: The widget ID of the offer - referred to as "id" within the offers object array in the Page Query.
Detail Query Sample call: Offer ID 59899
General Form:
This call is designed to retrieve all public information about an individual offer. This call returns offer-level attributes, store configuration information, and offer contents.
Detail Query Response
Product Response Formats
Per-product-type responses have also been documented. These are in the context of the above detail response but are presented at the product level (when digital media preferences are not requested) and the campaign level (when digital media preferences are requested).
Audio Track Product Response
Video Product Response
Image Product Response
File Product Response
Ticket Product Response
Merch Product Response
Membership Product Response
Package Product Response
Digital Package Product Response
Fanpack Product Response