Store API V2 Follow


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 / 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

  • Requiresapi_user, api_key, artist_id, tag_name
  • Optionalpage_number, offset, limit
  • api_user: in the form of - your API user information can be found at in the "API Information" section next to "API User"
  • api_key: in the form of a alphanumeric string - can be found at in the "API Information" section next to "API Key".
  • artist_id: Number found in "Artist Profile" next to "Artist ID" at
  • 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: 

curl -u ''

General Form

curl -u 'api_user:api_key'

Offset/Limit form Sample call: 10 items from artist ID 991, "tag ts_all_products", starting at offset 0, would be: 

curl -u ''

General Form

curl -u 'api_user:api_key'

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

    /* The offers array is the list of offers returned for the current page of the query. This is a JSON array */
    "offers": [{
        /* The embed code is the block of HTML to be embedded in the page to render the purchase flow for the button */
        "embed_code": "<div class=\"topspin-widget topspin-widget-buy-button\"><script type=\"text/javascript\" src=\"\"></script><a class=\"ts_buttonlink\" href=\"\">PURCHASE</a>\n</div>",
        /* The json_params are for topspin internal use only. */
        "json_params": "{\"aId\":991,\"cId\":10087868,\"highlightColor\":\"#c9c9c9\",\"theme\":\"black\"}",
        /* The URL to the thumbnail (150x150) image associated with the offer. This is a 12 hour expiring URL to the image */
        "thumbnail_image_url": "",
        /* The URL to the small (300x300) image associated with the offer. This is a 12 hour expiring URL to the image */        
        "small_image_url": "",
        /* The display price for the item */
        "price": "$3.00",
        /* The fan-facing name for the item */
        "name": "Opening Ceremony in HD Video and MP3",
        /* The id (widget id) of the offer */
        "id": 46853,
        /* The currency for the item */
        "currency": "USD"
        /* This offer block has been omitted for clarity */
    /* The stylesheet used for a default topspin store L&F. Used to pass 
       a user-configured stylesheet */
    "stylesheet": "",
    /* The user configured store setup and preferences from the Topspin console */
    "store_configuration": {
        /* The navigation element is an array of elements that describe the configured tab layout for the store.
           Real store configurations will typically have multiple configured categories.  */
        "navigation": [{
            /* The fan facing label for the tag (category) */
            "public_name": "Home",
            /* The internal name of the tag, as it should be passed to the API */
            "internal_name": "ts_all_products"
        /* The internal selected theme for the store. Theme names are not for external use. */
        "theme_name": "theme_5",
        /* The user configured color values (as hex) */
        "primary_color": "373737",
        "highlight_color": "222222",
        "link_button_color": "000000",
        "background_color": "F8F8F8",
        "button_color": "CC3333",
        /* The user uploaded header image. This is not guaranteed to be a fixed size header. */
        "header_image": "",
        /* The user configured layout. These names are not for external use. */
        "layout": "placeholder",
        /* This indicates if the user has chosen to show their facebook activity stream */
        "display_facebook": true,
        /* The sort order of offers on the store page */
        "offer_order": "created_at",
        /* This indicates the user has chosen to display their twitter feed */
        "display_twitter": true,
        /* The name field is for internal use */
        "name": "",
        /* The description field for internal use */
        "description": "",
        /* The ID of the user-selected featured offer, displayed
           promenantly in the topspin-constructed stores 
       -1 denotes no offer featured */
        "featured_offer_id": 46747,
        /* The user configured number of items to show in the twitter feed */
        "twitter_feed_length": 5
    /* The total number of pages of configured offers */
    "total_pages": 1,
    /* The current page number */
    "current_page": 1,
    /* The total number of offers available in the store */
    "total_entries": 2,
    /* The user-configured number of offers per page */
    "per_page": 25

Method 2: Detail Query

  • Requires: api_user, api_key, offer_id

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

Have more questions? Submit a request and our team will be able to help get you sorted.
Powered by Zendesk