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.
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:
Update orders, and optionally send an email notification to fans
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.
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.
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
page - page to return (default 1)
page_size - number of orders on each page (default 250)
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
set_acknowledged: If set to 'true', the returned orders will be given a status of acknowledged.
Return all orders where Spin Name contains "Test Spin 123"