Support Center/Developer Knowledge Base/Topspin APIs
Order API
David Widaman
posted this on July 01, 2011 06:10 pm
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:
- Create a test artist account to create test orders
- Setup a test merchandise product in that account, and create a $0 purchase button that offers the product.
- Follow the purchase process several times for the $0 product to create test orders
- Contact topspin artist support to get an API key to access the account
The way the integration typically works is as follows:
- 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)
- 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.
- 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:
- 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.
- 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.
- 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.
- 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:
- 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:
Followed by the method call:
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
Example Response
Responses are returned as JSON strings. For more information on JSON, see http://www.json.org.
Empty Response
http://pastie.org/pastes/2152579
Error Response
API Methods
Summary
|
Method
|
URL
|
HTTP Method
|
Function
|
| View Orders | /api/v1/order | POST | returns list of order details |
| Update Orders | /api/v1/order/update | POST | update individual orders |
| View SKUs | /api/v1/sku | POST | returns all SKUs created by the artist |
| Update SKUs | /api/v1/sku/update | POST | update 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:
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"
Return all orders where Spin Name contains "Only" AND Order Date is 2008-10-30
Return all digital orders where Spin Name contains "Only" AND Order Date is 2008-10-30
Example Response
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
|
|
| shipped | string | Allowed: "pending", "shipped". Marks order as shipped or still pending shipment. | |
| shipping_date | string - YYYY-MM-DD | Date order was shipped. | |
| tracking_code | string | carrier-generated Code used to track package. | |
| tracking_type | string | Allowed: "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 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
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
Example Response
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
Example Response
| id | Name | desc | uploaded | Size | Downloads | ||
|---|---|---|---|---|---|---|---|
| 1 | 274 |  client.rb |
  |
Order API Client (Ruby) | Tue 19 of Oct., 2010 21:03 EDT by abozanich | 9.15 Kb | 30 |
| 2 | 113 | TopSpin.cs |
|
Topspin Orders API Client in C# | Mon 22 of Feb., 2010 14:07 EST by kwehner | 3.44 Kb | 77 |
| 3 | 112 | TopSpinDataObjects.cs |
|
C# Data structure definitions for Topspin Orders API | Mon 22 of Feb., 2010 14:06 EST by kwehner | 1.54 Kb | 44 |
| 4 | 16 |  order_api_form.html |
|
Order API Sample | Mon 16 of Nov., 2009 13:45 EST by tread | 1.20 Kb | 232 |