Introducing SpreadKit – Spreadshirt API for iOS

SpreadKit

We are very happy to announce that SpreadKit 1.0 is available!
SpreadKit is an Objective-C framework (currently iOS-only) for interacting with the Spreadshirt API. This means it just got easier for you to integrate the Spreadshirt platform into your iPhone and iPad apps. Some of SpreadKit’s features are:
  • mappings of all Spreadshirt API resource types into native Objective-C objects
  • asynchronous API for all CRUD operations
  • transparent SprdAuth support
  • Retina-aware image loading: All images are loaded in a suitable resolution for the device
  • basket manager class
  • much more
To see what all the fuzz is about, head over to the GitHub repository. There you will find a quick guide to SpreadKit that should bring you up to speed with the framework.
We are happy to answer your questions or hear your comments. Please just use the blog comments or GitHub issues.
Cheers,
Sebastian

The Order Report Model (API Terminology Explained #15)

In my last blog post in the series “API Terminology Explained”, I introduced the order model.
In this blog post, I will continue with the order report model. Understanding the order report model together with the order model allows you to trigger actions on the partner-side based on order item state transitions and to implement a working order API client.

Understanding the Order Report Model

In our terminology, an order report contains a list of all fulfillment state modifications on order items from time x to time y that belong to a specific partner. Thus, the fulfillment state change information from the order report together with the fulfillment states and the state transitions explained for the order resources in our developer wiki can be used to trigger actions based on fulfillment state transitions on the partner-side, such as sending a shipping confirmation e-mail to the partner’s customer. An order report has right now the following characteristics:

  • Core Data: Each order report has a state, i.e. ACTIVATED or DELETED, and a created and modified date.
  • Order Item Modifications: Each order report contains a list of order item modifications. An order item modification denotes the modification of the fulfillment state of an order’s order item. It therefore contains a link to the actual order and order item. It also contains the new fulfillment state, e.g. CREATED, ACCEPTED or SHIPPED, and a modified date.
  • Correlation: In case the partner provided correlation information on order creation, the order item modifications will contain the same correlation information. They allow the partner to easily connect the fulfillment state modifications on the order items on the Spreadshirt platform with order items of his e-commerce or ERP system.

Retrieving Order Reports

The order reports generated for a partner, such as partner 1102730, can in general be received by conducting a HTTP GET call on the order reports resource http://api.spreadshirt.net/api/v1/orderReports?query=+partnerId:(1102730) +state:(ACTIVATED). A single order report can be fetched, by conducting a HTTP GET call on an order report resource, such as http://api.spreadshirt.net/api/v1/orderReports/123. The order report resources are described in detail in our developer wiki. A sample order report XML would look as follows:

‘The Order Report Model (API Terminology Explained #15)’

The Order Model (API Terminology Explained #14)

In my last blog post in the series “API Terminology Explained”, I told you about our shipping type model.
In this blog post, I will introduce the order model. Understanding the order model allows you to retrieve and create orders on the Spreadshirt platform using Spreadshirt API v1.

Understanding the Order Model

In our terminology, an order contains a set of abstract order items that link concrete order item elements. Right now, two concrete order item elements are supported: Spreadshirt product and article.
A typical order, e.g. an order with two products, is illustrated in the picture above. An order has right now the following characteristics:

  • Core Data: Each order has a shop assigned that represents the shop the products or articles are ordered for. It also has two attributes created and modified, that tell you when the order was created and when it was last modified.
  • Order Items: An order can have one or more order items. An order item represents an abstract item added to the order. Each order item has a description, a quantity, a price, a shop and a concrete order item element.
    The concrete order item element has a type attribute, which can right now be set to the supported types sprd:article or sprd:product, and a xlink:href attribute which links the actual product or article that is available via the API. Depending on the type, one can set type specific element properties. In case of Spreadshirt article and product, these properties are size and appearance.
    Please note that price and description are taken from the item linked by the order item element. Quantity is always a value greater equal 1.
    You can only add products or articles to an order, if they are available in the desired size and appearance (see product’s product type stock states). Some products do not allow to change the default color (freeColorSelection = false) and thus can not be added to the order in a different appearance than the configured one.
    An order item also has two attributes created and modified that tell you when the order item was created and when it was last modified.
    It can also have a baseOrderItem attribute that tell you which order item is the predecessor order item of the current one. This can happen for example if a customer sends an ordered item back to Spreadshirt and we ship it again to the customer.
  • Payment: The payment block allows to provide the necessary payment information for the order. Right now, we only support EXTERNAL_FULFILLMENT as payment type, which means that the partner orders products or articles for his customers on his account and has either made a prepayment at the beginning of a month that he can use, or he gets an invoice from Spreadshirt for all ordered products or articles at the end of the month for example. In this case, we assume that the partner operates his own checkout and that he collects the money from his customers.
  • Shipping: The shipping block allows to provide shipping information for order and order item. For the order, the shipping block contains the attributes shipping type, i.e. standard or express shipping in Europe, and shipping address.
    The shipping address can either be the partner’s address or in the white-label fulfillment case the customer’s address. Make sure that you send us the e-mail address of your service instead of the customer’s e-mail address for the white-label fulfillment case.
    For the order item, the shipping block right now only contains the shipping type with which the order item was actually shipped.
  • Billing: The billing block allows to provide a billing address that will be used  for billing.
  • Correlation: Correlation blocks can be provided for the order and all order items. By providing external order and order item ids, it is possible to connect the order and all order items of the Spreadshirt platform with the order and order items stored in the partners e-commerce or ERP system.
  • Attachments: Attachments can be provided for each order item. They allow to attach the product that shall be ordered with this order item and even links to images used in the product. That makes it possible to provide everything required to order a custom created product in one XML payload and with one HTTP request.
  • Errors: The error block contains all relevant information about errors that occured on processing the received order.

‘The Order Model (API Terminology Explained #14)’

Order API Released

A couple of days ago, we released our new order API. The order API allows partners to

  • implement their own checkout,
  • handle customer payments and interactions themselves and
  • use Spreadshirt as white-label fulfiller only.

That means for Spreadshirt, that we

  • receive orders from the partner,
  • produce the order items on the partner’s account and
  • deliver the produced order items to the partner’s customers.

The partner handles all customer interactions, starting from customer payments to handling customer questions to sending e-mails on delivery of order items. In order to use the order API, the partner has to sign a contract with Spreadshirt, that makes sure that we are allowed to produce the order items on the partner’s account. The partner has to pay a monthly invoice for all produced order items.
In general, the order API is thought for partners that generate a relevant number of orders per year, e.g. more than 2000 orders. Please contact Spreadshirt sales team (sales(at)spreadshirt(dot)net) for contract infos and further information on the order API.

The new order API basically provides the following new features: ‘Order API Released’

Resource Types supported by Spreadshirt API v1

As described in Spreadshirt API v1 Explained, the Spreadshirt Data and Image API is provided as a RESTful (Representational State Transfer) API via HTTP, which means that we use HTTP methods, HTTP status codes, URL structures and the concepts of resource and representation correctly to allow API clients to retrieve, create, update and delete data and images.

The Wikipedia article about REST (Representational State Transfer) describes the REST-style architecture and the concept of resource and representation as follows: “REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.” The section on RESTful web services in the Wikipedia article also describes the proposed URL structures and usage of HTTP methods for what is called collections and elements in the article. ‘Resource Types supported by Spreadshirt API v1′

How do I earn money, selling articles and custom created products via my own client application using Spreadshirt API v1?

For those of you that start writing their own client applications based on Spreadshirt API v1, quite quickly the question arises: How do I earn money, selling articles and custom created products via my own client application using Spreadshirt API v1? Therefore, in this blog post, I want to explain, how you can earn money with articles, products and designs that exist already and products and designs created via Spreadshirt API v1. ‘How do I earn money, selling articles and custom created products via my own client application using Spreadshirt API v1?’

Media Types supported by Spreadshirt API v1

Using Spreadshirt’s API, you will notice, that data is always returned in the Extensible Markup Language (XML) and images are always returned as Portable Network Graphics (PNG). An example for data returned as XML is http://api.spreadshirt.net/api/v1/shops/205909/articles?query=herz and for images http://image.spreadshirt.net/image-server/v1/products/5617609/views/1.

However, in some cases XML or PNG is not sufficient. Therefore, you can provide a query parameter mediaType and the desired media type abbreviation, like json or jpg. An example URL for returning data in the JavaScript Object Notation (JSON) would be http://api.spreadshirt.net/api/v1/shops/205909/articles?query=herz&mediaType=json.

As described in Spreadshirt API v1 Explained, Spreadshirt API consists right now of a Data API and an Image API.

‘Media Types supported by Spreadshirt API v1′

The Shipping Type Model (API Terminology Explained #13)

In my blog posts in the series “API Terminology Explained”, I already told you about some of our data models, like the product type model, the product model or the basket model.
In this blog post, I will add another data model you should be familiar with, the shipping type model. Understanding the shipping type model allows you to display the right shipping countries, regions and prices for shops and to calculate correct shipping prices for baskets and orders.

Understanding the Shipping Type Model

In our terminology, a shipping type defines the way Spreadshirt delivers an ordered item to a customer. Depending on whether the customer ordered a real item, like a t-shirt, or a virtual item, like a gift certificate, we either need to ship the item using a standard carrier, like Deutsche Post or UPS, or we can send it using e-mail.

A shipping type has right now the following characteristics:

  • Core Data: Each shipping type has a name and a description, that can be used for displaying shipping type information in a client application. For shipping types that denote a shipping of a real item with a standard carrier, there are the available shipping countries and the shipping regions with the shipping costs for different order values defined.
  • Shipping Country: A shipping country is a country that Spreadshirt ships items to using the specified standard carries, like UPS. A shipping country has a name that can be used for displaying country information in a client application. It also links to a specific shipping region that contains the actual shipping costs for different order values.
  • Shipping Region: A shipping region contains the shipping costs for different order value ranges for a set of shipping countries, like France or United Kingdom if your country of delivery is Germany. Each order value range defines a from order value (lower bound), like 0.00 €, and might define a to order value (upper bound), like 24.89 € or unbound (undefined). Depending on the order value of the order, the shipping costs of the matching order value range apply.

‘The Shipping Type Model (API Terminology Explained #13)’

Formatting Prices (API Terminology Explained #12)

In one of my last blog posts, I told you about how to calculate product prices. The next question is certainly, how to format prices correctly in order to display them in your application. That is what I want to talk about in this blog post.

Preliminaries

When working with the Spreadshirt API and our platform, you will find prices everywhere. As described in my last blog post, print types, print colors and product types have prices attached that tell you how much needs to be payed when using them. Designs have commissions attached that are payed to the designer when using them. Articles also have prices that are calculated based on the actual product price and commissions on top of that, that are payed to the article owner for each sale.

Data about prices, commissions or costs are returned by the API in always the same price format. A price always consists of the following data:

  • price without VAT – price without value added tax (VAT), e.g. 0,42 €
  • price with VAT – price with value added tax (VAT), e.g. 0,50 €
  • VAT - value added tax (VAT) percentage, e.g. 19% in Germany
  • currency – the currency for which the price is given

‘Formatting Prices (API Terminology Explained #12)’

Calculating Product Prices (API Terminology Explained #11)

In my last blog post in the series “API Terminology Explained”, I told you about how to map coordinates from Spreadshirt’s SVG user coordinate system to your application’s coordinate system in order to display products in your application correctly. In this blog post, I will tell you more about how to calculate product prices correctly.

Preliminaries

As already explained in the product model, a product is always based on a product type, such as a shirt. A product has one or more text or design configurations that define on which print area Spreadshirt shall print text or designs with a specific print type, such as flock, flex or digital, and for non-digital print types with specific print colors, such as black, red or white.
Product types, print types and print colors have shop specific prices. Designs may have a design commission adjusted by the owner of the design.  Please note that when working in a shop context, e.g. /shops/205909, all prices are returned in the adjusted shop currency.

‘Calculating Product Prices (API Terminology Explained #11)’