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.