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:
Continue reading “The Order Report Model (API Terminology Explained #15)”
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.
Continue reading “The Order Model (API Terminology Explained #14)”
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.
Continue reading “The Shipping Type Model (API Terminology Explained #13)”
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.
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
Continue reading “Formatting Prices (API Terminology Explained #12)”
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.
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.
Continue reading “Calculating Product Prices (API Terminology Explained #11)”
In this blog post, I will tell you how to translate product type, product, design and text coordinates correctly from Spreadshirt’s SVG user coordinate system to your application’s coordinate system. You need to understand how the translation works in case you want to display and manipulate Spreadshirt products in your own applications. Please read the Text and Design Positioning Guide to learn more about how to position text and designs on Spreadshirt products. Also read Product Model, ProductType Model, Design Model to learn more about them in case you don’t know already.
When displaying a Spreadshirt product or creating a new one in your own application, you need to consider different coordinates and sizes from Spreadshirt product types, products, designs and text. The coordinates and sizes to be considered are as follows:
- View size – size of the view, e.g. front, back or left side on a shirt
- ViewMap offset – position of the print area on the actual view
- PrintArea size – size of the print area we can print on
- Configuration offset – position of the actual configuration on the print area
- Size – actual size of the design
- Position – start position of the text depending on the given text anchor
- Font size – size of the font used for the text
- Text anchor – alignment of the text, e.g. left, center, right
Spreadshirt does all internal calculations in Spreadshirt’s SVG user coordinate system in millimeters right now. That means all coordinates, sizes and font sizes are provided in millimeters! So when displaying a Spreadshirt product in a Web browser or creating a new one, you always need to translate the millimeter coordinates, sizes and font sizes to pixels and vice versa. Continue reading “Mapping Coordinates from Spreadshirt’s SVG User Coordinate System to your Application’s Coordinate System (API Terminology Explained #10)”
In this blog post, I will tell you more about how to position text and designs on product types using product configurations. To better understand what we discuss here, read the product type model and the product model first. Then have a look at the product model specification and the supported SVG subset specification.
So let’s start. We always want to place text or designs on a product type, e.g. a woman’s shirt. A shirt has different views, e.g. front, back or left arm. In our example we use the front view as you can see in the image above. A view has always a width and height, i.e. size, given in millimeter.
Continue reading “Positioning Text and Designs on Product Types (API Terminology Explained #9)”
In my last blog post about the font model, I told you about how our font model works and how you can use it to display existing or create new products with text. In this blog post, I will tell you more about our print type model.
Understanding the Print Type Model
In our terminology, a print type or printing type basically defines the technology that is used to apply the layers of the selected print colors to a product type, e.g. a t-shirt, the appearance of the applied colors, e.g. smooth, velvety or pattern, and the colors that can be used for printing. The most common print types flock, flex, special flex and digital printing are illustrated in the picture above.
The common print types can be described as follows:
- Flock Printing: For flock printing, a computerised blade is used to slice designs out of a soft, velvety material. Using high pressure and temperatures, this design is then pressed onto the fabric.
- Flex Printing: With flex printing, a large computerised blade is used to cut designs out of a smooth, thin material. This design is then pressed onto the fabric, using high pressure and temperatures.
- Special Flex Printing: With special flex printing, a large computerised blade is used to cut designs out of a smooth, thin material. This design is then pressed onto the fabric, using high pressure and temperatures.
- Digital Printing: The colours are printed directly onto the material with a special ink-jet printer. The print places a very thin and soft layer over the material. When printing onto dark-coloured t-shirts, a thin layer of white is applied as a primer before the full design is printed.
A print type has the following characteristics:
- Core Data: Each print type has right now the following core data: name, description, size, dpi, price and restrictions.
Name and description can be used to display print type information in applications.
The size defines the maximum size in which one color layer of a design or text can be printed on a product type in millimeter. The dpi attribute tells you with how many dpis the design or text will be printed on the product type, finally.
The price contains the price of the print type in the currency of the shop that must be payed when using the print type in your product configurations.
Finally, the restrictions information tell you about general print type restrictions and about restrictions when using the print type in combination with other print types.
General print type restriction attributes are for example colorSpace, whiteSupported and transparencySupported. The colorSpace tells you about the color space used by this print type. This can be print_colors if only special colors defined for this print type can be used, e.g. for flex and flock printing, rgb if all colors in rgb color space can be used, e.g. for digital printing, or cmyk if all colors in cmyk color space can be used. WhiteSupported and transparencySupported tell you whether transpareny and white color can be printed with this print type.
Print type restrictions required when using combinations of print types on a product type are maxPrintColorLayers, printableAlongWithPrintTypes and printableAbovePrintTypes. The maxPrintColorLayers attribute defines how many print color layers can be printed above each other when this print type is involved. PrintableAlongWithPrintTypes and printableAbovePrintTypes tells you which print types can be combined in general and which print types can be printed above each other, when printing text over a design for example.
- Colors: Each print type that uses the print_colors color space also defines one or more colors. Each color has the following data: name, price, resources, fill and restrictions.
The name attribute contains the name of the print color and can be used for displaying purposes. The price tells you how much the usage of this print color costs. Fill and resources data can be used for displaying print color panels as well as text and design layers in the print color in your application. While the resources data contains a URL that points to a print color image, e.g. a special flex print color image, the fill attribute contains an rgb hex value that matches the print color image as best as possible. Use the fill data to display text and design layers with the defined color in your applications.
The restrictions data of a color is basically the printableAbovePrintColors list that defines which other print colors can be printed above this print color.
Continue reading “The Print Type Model (API Terminology Explained #8)”
In my last blog posts, I told you about the essential models you need to understand in order to be able to display existing or create new products and allow your customers to buy them using our checkout. In the next blog posts of the series “API Terminology Explained”, I want to go a bit more into the details and tell you about our font and print type model as well as about how to position text and design on product types and how to calculate product prices. I will start with the font model in this blog post.
Understanding the Font Model
In our terminology, a font family is a grouping of similar fonts that basically differ in their shape, i.e. regular, bold or italic. A typical font family, e.g. Arial, is illustrated in the picture above. A font family has right now the following characteristics:
- Core Data: Each font family has a name, a deprecated attribute and a list of allowed print types.
The deprecated attribute indicates whether a font is outdated. If a font is outdated it can be used for displaying existing products and render product images but not for creating new products.
The list of allowed print types contains those print types that allow to print text and use fonts from the font family therefore.
- Fonts: Each font family also has a list of one or more fonts that belong to one font group, e.g. Arial. The fonts basically differ in their shape, e.g. regular, bold, italic. A font therefore has a name, a style, a weight and a minimalSize attribute and a list of resources.
The name is usually used to address a font when displaying existing products or creating new ones.
Style and weight attribute indicate which special shape shall be used. Thereby, the style can contain values like normal (aka regular) or italic and the weight attribute values like normal (aka regular) or bold. All 4 combinations of the values are allowed.
The minimalSize attribute defines the minimum size in which this font can be printed on apparel. This value is checked when creating new products.
Continue reading “The Font Model (API Terminology Explained #7)”
In my previous blog posts, I introduced our data models for product types, designs, products and articles to you and told you how to retrieve those data from our data API. In this blog post, I will tell you, how you can retrieve the corresponding images for that data from the image API, in order to display product type, design or product images in your custom applications.
Understanding the Different Image Types
Our image API delivers in general images for product types, designs, products, product type appearances, print colors and fonts.
Product Type Images
For product types, we deliver the following images: