The Product Model (API Terminology Explained #4)

After telling you about our product type and design model in my last blog posts, I want to introduce our product model today. Knowing how our product model works, you will be able to work with existing products via our API. You will also be able to create new products which allows you for example to build mass customization applications.

Understanding the Product Model

In our terminology, a product represents a product type with designs and/or text lines applied to one or more print areas. A typical product, e.g. a product that contains the “I Heart” design from our marketplace and a text line, is illustrated in the picture above. A product has the following characteristics:

  • Core Data: Each product belongs to a user and has a price. The price is calculated based on the used product type, designs and print types + colors. Different from articles which have a fixed price set, the price for a product is calculated based on the added configurations on the fly.
  • ProductType Data: A product is created based on a specific product type. Therefore, it links a product type and a specific product type appearance, e.g. a yellow American Apparel shirt.
  • Default Values: Each product also has a set of default values. One default value is for example the defaultView attribute, that tells you which view to use when displaying a product, e.g. front or back.
  • Restrictions: The product data also always contains a set of restrictions, that tell you what you can’t do with that product. One attribute is for example the freeColorSelection attribute, that tells you whether it is allowed to order that product in another appearance (color/pattern combination).
  • Configurations: A product can have one or more configurations. A configuration applies a text or a design to a print area of the selected product type.
    A configuration is always connected to one print type, e.g. flex, flock or digi, with which that configuration is printed on the corresponding print area in the production process (I will give you more information about our print type model in one of the next blog posts). Therefore, in the configuration description, you can only use the print colors of that print type! Depending on the used print type, you can use fixed, print type specific colors, e.g. for flex, or free RGB or CMYK colors, e.g. for digital direct.
    A configuration is positioned on the print area using the offset values and has a specific size that is calculated from the design or text size.
    We differentiate between design and text configurations. To describe both types of configuration, we use SVG. We use the SVG image concept to describe design configurations and the SVG text/tspan concepts to describe text configurations.
    Please note, that we call the set of configurations applied to one product type view composition.

Retrieving Product Data

Now that you know how the product model works, I will show you how you can retrieve the data required for creating own applications. For each product, we provide an XML description as well as images for different views on the product, different sizes and different media types. As described in Spreadshirt API v1 Explained, you can use the Data API to retrieve the XML descriptions and the Image API to retrieve the images.

  • XML description: To retrieve a product’s XML description, you can for example use a URL similar to the following one: http://api.spreadshirt.net/api/v1/shops/524249/products/17636761. Using that URL, you will receive an XML description similar to the following one:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <product id="17636761" ...>
        ...
        <restrictions>
            ...
        </restrictions>
        <defaultValues>
            ...
        </defaultValues>
        <configurations>
            <configuration type="design" id="24654348">
                ...
                <offset unit="mm">
                    <x>56.977658795749676</x>
                    <y>62.97518748524202</y>
                </offset>
                <content dpi="25.4" unit="mm">
                    <svg viewBox="0 0 278.035 151.522">
                        <image xlink:href="http://image.spreadshirt.net/image-server/v1/designs/m2484607-1?config:colors[0]=000000&amp;config:colors[1]=D41C3B"
                               transform="" height="151.522" width="278.035" 
                               printColorRGBs="#000000 #D41C3B" printColorIds="13 20" 
                               designId="m2484607-1"/>
                    </svg>
                </content>
                ...
            </configuration>
            <configuration type="text" id="24654349">
                ...
                <offset unit="mm">
                    <x>56.977658795749676</x>
                    <y>236.90671050767412</y>
                </offset>
                <content dpi="25.4" unit="mm">
                    <svg viewBox="0 18.891 262.996 65.419">
                        <text height="84.31" width="262.996"
                              transform="" font-style="normal" 
                              font-size="68.792" font-weight="normal" 
                              font-family="CooperBlackLTRegular" fill="#000000"
                              text-anchor="middle" y="68.936" x="131.498" 
                              printColorId="13" fontId="45" fontFamilyId="24">Leipzig</text>
                    </svg>
                </content>
                ...
            </configuration>
        </configurations>
        ...
    </product>

    You can see, that the highlighted XML tags correspond to the parts of a product described above. You can find the XML schema definition for products in the api.xsd.

  • Images: To retrieve a product image, you can use a URL similar to the following one:  http://image.spreadshirt.net/image-server/v1/products/17636761/views/1. This image will show a picture of the whole product type view with the configurations applied.
    Besides that, our image API is also able to return images for compositions and configurations. Use URLs similar to the following ones to retrieve those: http://image.spreadshirt.net/image-server/v1/compositions/17636761/views/1 or http://image.spreadshirt.net/image-server/v1/configurations/24654349.
    It is important to understand that these URLs are provided with the resources parts of the product XML description:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <product id="17636761" ...>
        ...
        <configurations>
            <configuration type="design" id="24654348">
                ...
                <resources>
                    <resource xlink:href="http://image.spreadshirt.net/image-server/v1/configurations/24654348" mediaType="image/png"/>
                </resources>
            </configuration>
            <configuration type="text" id="24654349">
                ...
                <resources>
                    <resource xlink:href="http://image.spreadshirt.net/image-server/v1/configurations/24654349" mediaType="image/png"/>
                </resources>
            </configuration>
        </configurations>
        ...
        <resources>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/products/17636761/views/1" mediaType="image/png"/>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/compositions/17636761/views/1" mediaType="image/png"/>
        </resources>
    </product>

    Please use the provided resource data and don’t put static URLs into your source code!

Creating Products

Creating products is as simple as retrieving product data. To create the product displayed above, you simply can take the already described product payload and conduct a HTTP POST call on a URL similar to http://api.spreadshirt.net/api/v1/shops/524249/products. This will create a new customer product in your shop. You can then use this product to put it in a basket and send the customer to our HTML checkout. Please note, that you need an API key and the required API feature to create customer products.

In this blog post, I told you about the different parts of our product model. I also explained, how you can retrieve the required XML descriptions and images from our API. With this knowledge, you will be able to retrieve and create own products using our API, which allows you for example to build mass customization applications. In my next blog post, I will tell you about our basket model.

Please also have a look at the other articles in the series “API Terminology Explained”:

6 Responses to “The Product Model (API Terminology Explained #4)”


  1. 1 by Louis Vuitton Handbags | May 28th, 2010 at 1:43 am
    Gravatar of Louis Vuitton Handbags

    googd thanks a lot,this is very useful!!

  2. 2 by Victor Dukart | Jun 1st, 2010 at 8:07 am
    Gravatar of Victor Dukart

    Hi,this is Victor Dukart,just identified your Post on google and i must say this blog is great.may I share some of the writing found in the post to my local friends?i am not sure and what you think?in either case,Many thanks!

  3. 3 by Aion Kinah | Jun 2nd, 2010 at 1:12 am
    Gravatar of Aion Kinah

    Such a usefule blog wow !!!!

  1. 1 The Basket Model (API Terminology Explained #5) | Spreadshirt Developer Blog
  2. 2 Image Types Explained (API Terminology Explained #6) | Spreadshirt Developer Blog
  3. 3 The Shipping Type Model (API Terminology Explained #13) | Spreadshirt Developer Blog

Leave a Reply