Orders API Follow

Overview

The Topspin Order API is a way to read and write order data to and from the Topspin platform. This allows you to customize order fulfillment, reading and writing order data to and from the Topspin platform. For example, as an artist you might want to mark orders shipped and notify fans from a custom fulfillment application without having to login to the Topspin Manager.

If you are implementing this yourself, read the documentation below. If you need to hire a developer to integrate the Topspin API, please refer to our Topspin partners pages.

For Developers

The Topspin Orders API is a REST web-service that consists of a set of callable methods. Using the API, you can view and update order and SKU data. Specifically, you can perform the following actions:

  • View orders
  • Update orders, and optionally send an email notification to fans
  • View SKU(s)
  • Update SKU(s)

Integration Process

Typical Offers API integrations follow the following steps:

  1. Create a test artist account to create test orders
  2. Setup a test merchandise product in that account, and create a $0 purchase button that offers the product.
  3. Follow the purchase process several times for the $0 product to create test orders
  4. Contact topspin artist support to get an API key to access the account

The way the integration typically works is as follows:

  1. The implementor of the API specifies a schedule on which they will check the Topspin system for orders (often around a 5 minute polling period, but sometimes daily)
  2. Orders are fetched with a filter that pulls down orders that are ready to ship but have not yet gotten marked as shipped, and integrates them into the database of the warehouse's inventory system.
  3. When the shipping label is created to attach to the physical box, tracking information is pushed back into the Topspin system, and the order is flagged as shipped.

The major gotchas and things to know in this process are:

  1. Most physical fulfillers will send order shipment emails themselves, which means that they will not send the flag to topspin to send the order shipment email. This is necessary when the fulfiller is doing the support for the physical shipment to put the fulfiller's customer service information in the mail.
  2. Topspin SKUs are built to carry a 3rd party "Warehouse SKU", which, if keyed into the topspin system, makes it so the physical fulfiller does not have to maintain a mapping of their sku ids to the topspin sku ids. This field is an arbitrary text field configurable in the UI by the artist, and is optional.
  3. When orders are fetched from the topspin system, all sku attributes for the order come down with the order itself. This includes things like color and size for a t-shirt, and the optional "Warehouse SKU" that can carry the warehouse's sku data.
  4. The SKU modification API exists to allow inventory adjustment for inventory changes that happen OUTSIDE the Topspin system. That is, for things like reshipments or new stock being created. Any order that is processed by topspin will be automatically decremented from the available inventory.

Several code samples can be downloaded at the very bottom of this :

  • Orders API Client (Ruby)
  • Orders API Data Structures (C#)
  • Orders API Client (C#)
  • Orders API Form (HTML)

Authentication

You will need to use HTTP authentication to access the API. To get an API key please make a request here:https://app.topspin.net/account/artisthelp

Use your Topspin email login as your username and the API key as your password.

Creating a REST Request

The API is a REST service. This allows you to create a request URL string that will work in your web browser, the command line, and in your code using such tools as cURL, WGET or any HTTP library that will support HTTP authentication.

The base URL for the request will look like: 

https://app.topspin.net/api/v1/

Followed by the method call: 

https://app.topspin.net/api/v1/order

Each method will use either a POST or GET method. Please set Content Type to: application/x-www-form-urlencoded.

Query parameters are passed to the method either in a URL string for GET or in a data block for POST. Multiple parameters are separated by an ampersand (&). URL strings should be properly URL encoded.

Example Request

argument=value&foo=bar

Example Response

Responses are returned as JSON strings. For more information on JSON, see http://www.json.org.

{
  "status"  : "ok"
}

 Empty Response

{
  "response":[],
  "status":"ok"
}

Error Response

{
  "reason":"invalid ID",
  "status":"error"
}

 

API Methods

Summary

Method
URL
HTTP Method
Function
View Orders/api/v1/orderPOSTreturns list of order details
Update Orders/api/v1/order/updatePOSTupdate individual orders
View SKUs/api/v1/skuPOSTreturns all SKUs created by the artist
Update SKUs/api/v1/sku/updatePOSTupdate SKUs


View Orders

POST /api/v1/order

Returns a list of order details.

Parameters

Search - JSON Object to be passed with a "filter" key/value pair AND/OR a "term" key/value pair.

  • Filter: returns orders of the passed type
  • Terms: an array of key/value pairs to search on.

Required: None. If no parameters are passed, search will default to: 

search={"filter":"contains_merch","page":1,"page_size":25}

Filter Options:

  • contains_merch - (default) returns orders that contain merchandise
  • shipped - returns orders that contain merchandise and have shipped
  • not_shipped - returns orders that contain merchandise and have not shipped
  • past_due - returns orders that are past due (shipping date set and before today & the order hasn't shipped)
  • acknowledged - returns orders that have been acknowledged by a fulfiller but are not shipped.
  • pending - returns orders that have not been acknowledged or shipped.
  • all - returns all orders

Pagination Options:

  • page - page to return (default 1)
  • page_size - number of orders on each page (default 250)

Term Keys:

  • bundle_sku_id - the id of the exact combination of items that were purchased from the spin. An offer is a set of products, which then correspond to a unique bundle sku once configured.
  • spin_id - id of the spin
  • spin_name - name of the spin associated with the order
  • country - shipping country
  • order_id - The id of the order being searched for
  • order_date - date of the order (YYYY-MM-DD)
  • order_ship_date - date the order is marked shipped (YYYY-MM-DD)
  • order_ship_date_before - the order is marked shipped before date (YYYY-MM-DD)
  • order_ship_date_after - the order is marked shipped after date (YYYY-MM-DD)
  • order_date - date the order was created (YYYY-MM-DD)
  • order_date_before - the order was created before date (YYYY-MM-DD)
  • order_date_after - the order was created after date (YYYY-MM-DD)
  • order_subtotal - subtotal of order
  • factory_sku - The configured factory sku for the sku. This is used to carry a 3rd party (warehouse) sku that is configurable by the user to help people integrating with the api to not have to carry sku mappings.
  • fan_email - fan email address, this will be used to rese
  • fan_first_name - fan first name
  • fan_last_name - fan last name
  • product_description - description of product
  • product_id - id of product
  • shipping_first_name - shipping address first name
  • shipping_last_name - shipping address last name
  • shipping_postal_code - shipping address postal code
  • sku_id - id of sku
  • sku_upc - the configured upc of the sku, if there is one. this is a user input value like the factory sku
  • sku_attributes - the full set of user configured attributes for the sku. This includes things like size and color for merchandise skus
 
Other parameters
  • set_acknowledged: If set to 'true', the returned orders will be given a status of acknowledged.

Example Request

Return all orders where Spin Name contains "Test Spin 123" 

search={"terms":[["spin_name","Test Spin 123"]]}

Return all orders where Spin Name contains "Only" AND Order Date is 2008-10-30 

search={"terms":[["spin_name","Only"],["order_date","2008-10-30"]]}

Return all digital orders where Spin Name contains "Only" AND Order Date is 2008-10-30 

search={"filter":"digital", "terms":[["spin_name","Only"],["order_date","2008-10-30"]]}

 Example Response

JSON response
{"response":
  [{"fan":"hello@topspinmedia.com",
    "shipping":0,
    "shipping_address":{
      "phone":"5551234567",
      "address2":"Suite 777",
      "firstname":"Justin",
      "city":"Oakland",
      "lastname":"Davis",
      "state":"CA",
      "postal_code":"94610",
      "country":"US",
      "address1":"74 Foobar Ave"
    },
    "line_items": [{        
      "bundle_product_id":118888,
      "tax":"0.00",
      "quantity":1,
      "campaign_id":1005,
      "subtotal":"4.99",
      "shipping":"0.00",
      "id":222,
      "bundle_sku_id":555,
    }],
    "items":[
      {"shipped":false,
       "status": "pending",
       "product_name":"Takin Over Your Ears - CD",
       "sku_id":25,
        "sku_attributes": {
            "Type": "Standard",
            "Color": "Red"
        },
       "product_type": "merchandise",
       "merchandise_type": "apparel",
       "line_item_id":222,
       "shipping_date": "2009-12-08",
       "spin_name":"CD Promo",
       "bundle_sku_id": 20,
       "sku_upc": "22-2222-222",
       "product_id": 10,
       "campaign_id": 30,
       "poster_image": "http://api.topspin.net/4gfa4",
       "factory_sku": "55665", 
       "quantity": 1,
       "id":3 /* The id of the item entity */
      }],
    "tax":0,
    "subtotal":0,
    "created_at":"2009-10-27",
    "id":3, /* The id of the order */
    "artist_id": 20}],
    "current_page" => 1,
    "page_size"      => 250,
    "total_entries"  => 1,
    "total_pages"   => 1,
    "status":"ok"
}

 

Field Descriptions:

  • status - "ok" if the command completed successfully, otherwise "error"
  • response - list of orders matching your search terms
  • current_page - current page of matching orders
  • page_size - number of orders to include in each page
  • total_entries - total number of orders that match your search terms
  • total_pages - total number of pages
  • product_type - One of "ticket", "merchandise"
  • merchandise_type - One of "apparel", "cd", "dvd", "vinyl", "poster", "other"

Update Orders

POST /api/v1/order/update

 

Update individual orders 
NOTE: Orders that are marked "shipped" and over 15 days old can not be updated.

NOTE: "tracking_type" and "tracking_code" must be edited simultaneously.

Parameters 

Parameter
Values
Description
shippedstringAllowed: "pending", "shipped". Marks order as shipped or still pending shipment.
shipping_datestring - YYYY-MM-DDDate order was shipped.
tracking_codestringcarrier-generated Code used to track package.
tracking_typestringAllowed: "DHL", "FEDEX", "UPS", "USPS", "Other". Carrier used to ship.

Optional Parameters

  • email_on_update = true or false

If you would like to notify fans that order status has changed, pass the optional email_on_update=true parameter.

Example: 
https://app.topspin.net/api/v1/order/update?email_on_update=true

Example Request

Example Request
{
   "orders": [
      {
         "id": 14,
         "items": [
            {
               "id": 21,
               "status": "shipped"

            }
         ]
      }
   ]
}

Example Response

Response will contain:

  • email - Set to 1 if email was sent to fan, 0 if email is not sent
  • modified - Set to 1 if order was modified, 0 if not modified
Example Response
{
   "response": {
      "email": 0,
      "modified": 1
   },
   "status": "ok"
}


View SKUs

POST /api/v1/sku

Returns all SKUs currently available in any of an artist's active campaign.

Parameters

  • updated_after - return SKUs that have been updated since given date (YYYY-MM-DD)
  • campaign_id - return SKUs that are being sold in the given campaign(s). Comma-separate multiple campaign IDs.

Example Request

https://app.topspin.net/api/v1/sku

Example Response

Response JSON
{
    "status": "ok",
    "response": {
        "skus": [{
            "in_stock_quantity": 10,
            "max_backorder_quantity": 0,
            "reserve_quantity": 0,
            "sold_unshipped_quantity": 5,
            "sold_shipped_quantity": 100,
            "product_name": "First Merch Product",
            "artist_id": 799,
            "attributes": {
                "Size": "S",
                "Gender": "Male",
                "Color": "Red",
                "Moon Phase": "Full"
            },
            "poster_image": "http://app.topspin.net/images/avatar_default.jpg",
            "artist_name": "KrisProd",
            "id": 239015,
            "weight": {
               "US":  "1.5 lb",
               "SI" :  "680.38 g", 
            }
        },
        {
            "available": 1,
            "product_name": "First Merch Product",
            "artist_id": 799,
            "attributes": {
                "Size": "S",
                "Gender": "Male",
                "Color": "Red",
                "Moon Phase": "Half"
            },
            "in_stock_quantity": 100,
            "max_backorder_quantity": 5,
            "reserve_quantity": 10,
            "sold_unshipped_quantity": 50,
            "sold_shipped_quantity": 75,
            "poster_image": "http://app.topspin.net/images/avatar_default.jpg",
            "artist_name": "KrisProd",
            "id": 239016,
            "weight": {
               "US":  "1.5 lb",
               "SI" :  "680.38 g", 
            }
        }]
    }
}

Update SKUs

POST /api/v1/sku/update

Update individual SKUs

Parameters

  • id - id of the sku
  • available - (true | false) SKU is available to purchase
  • factory_sku - The factory sku of the item
  • weight - The weight of the SKU
  • weight_unit - Unit of given weight. Must be one of 'lb','oz','kg','g'
  • in_stock_quantity - set the in-stock quantity
  • max_backorder_quantity - set the max-backorder quantity
  • reserve_quantity - set the reserve quantity

Example Request

id=50&available=true&factory_sku=ABCDEFG

Example Response

Response JSON
{"status":"ok"}

 

List of attached files
 idName descuploadedSizeDownloads
1 274 default client.rb ViewDownload   Order API Client (Ruby) Tue 19 of Oct., 2010 21:03 EDT by abozanich 9.15 Kb 30
2 113 default TopSpin.cs ViewDownload   Topspin Orders API Client in C# Mon 22 of Feb., 2010 14:07 EST by kwehner 3.44 Kb 77
3 112 defaultTopSpinDataObjects.cs ViewDownload   C# Data structure definitions for Topspin Orders API Mon 22 of Feb., 2010 14:06 EST by kwehner 1.54 Kb 44
4 16 htmlorder_api_form.html ViewDownload   Order API Sample Mon 16 of Nov., 2009 13:45 EST by tread 1.20 Kb 232
Have more questions? Submit a request and our team will be able to help get you sorted.
Powered by Zendesk