Product Resources

This document specifies the API for accessing product data.

Resources Product

Retrieve Shop Product List

Url .../v1/shops/{shopId}/products
Sample http://api.spreadshirt.net/api/v1/shops/40000/products
Type LIST
Method GET
Special Status Codes  

Response Representation:

<products ...>
  ...
</products>

See Product Representation

Retrieve Shop Product Entity

Url .../v1/shops/{shopId}/products/{productId}
Sample http://api.spreadshirt.net/api/v1/shops/40000/products/1082550
Type ENTITY
Method GET
Special Status Codes  

Response Representation:

<product ...>
   ...
</product>

See Product Representation

Retrieve Shop Product Price Entity

Url .../v1/shops/{shopId}/products/{productId}/price
Sample http://api.spreadshirt.net/api/v1/shops/40000/products/1082550/price
Type ENTITY
Method GET
Special Status Codes  

Response Representation:

<price ...>
   ...
</price>

Create Shop Product Entity

Url .../v1/shops/{shopId}/products
Sample http://api.spreadshirt.net/api/v1/shops/40000/products
Type LIST
Method POST
Special Status Codes 201 (Product Created)
APIKey true
SessionId false (true if user is logged in)

Request Representation:

<product ...>
   ...
</product>

See Product Representation

Response Representation:

Header:

Location: .../v1/shops/2345/products/70aab75c0b6217c2aff1fe301111929291

Delete Shop Product

Url .../v1/shops/{shopId}/products/{productId}
Sample http://api.spreadshirt.net/api/v1/shops/40000/products/10815
Type Entity
Method DELETE
Special Status Codes
APIKey true
SessionId false (true if user is logged in)

Retrieve User Product List

Url .../v1/users/{userId}/products
Sample http://api.spreadshirt.net/api/v1/users/40000/products
Type LIST
Method GET
Special Status Codes  
APIKey true
SessionId true

Response Representation:

<products ...>
  ...
</products>

See Product Representation

Retrieve User Product Entity

Url .../v1/users/{userId}/products/{productId}
Sample http://api.spreadshirt.net/api/v1/users/40000/products/1082550
Type ENTITY
Method GET
Special Status Codes  
APIKey true
SessionId true

Response Representation:

<product ...>
   ...
</product>

See Product Representation

Retrieve User Product Price Entity

Url .../v1/users/{userId}/products/{productId}/price
Sample http://api.spreadshirt.net/api/v1/users/40000/products/1082550/price
Type ENTITY
Method GET
Special Status Codes  
APIKey true
SessionId true

Response Representation:

<price ...>
   ...
</price>

Create User Product Entity

Url .../v1/users/{userId}/products
Sample http://api.spreadshirt.net/api/v1/users/40000/products
Type LIST
Method POST
Special Status Codes 200
201 (Product Created)
APIKey true
SessionId true

Request Representation:

<product ...>
 ...
</product>

See Product Representation

Response Representation:

Header:

Location: .../v1/users/2345/products/70aab75c0b6217c2aff1fe301111929291

Delete User Product

Url .../v1/users/{userId}/products/{productId}
Sample http://api.spreadshirt.net/api/v1/users/40000/products/10815
Type Entity
Method DELETE
Special Status Codes
APIKey true
SessionId true

Retrieve Shop Article Category List

Url .../v1/shops/{shopId}/articleCategories
Sample http://api.spreadshirt.net/api/v1/shops/40000/articleCategories
Type LIST
Method GET
Special Status Codes  

Search request:

Use ?query=... to search on marketplace articles and filter relevant articles. Works for marketplace shops (eu = 205909) only!

To restrict search to specific categories use categoryIds, productTypeDepartmentIds, productTypeCategoryIds, productTypeSizeIds and designIds set in query, e.g. ?query=liebe +categoryIds:(1000017 1000018 1000019) +productTypeDepartmentIds:(1 4) +productTypeCategoryIds:(100 200) +productTypeSizeIds:(2 3).

Use showFacets attribute like ?query=...&showFacets=true to show the result entry facets for product type departments and product type categories additionally to the entry results per article category.

Note:

Entry counts are only provided for search requests (?query...).

Response Representation:

<articleCategories ...>
  ...
</articleCategories>

See ArticleCategory Representation

Retrieve Shop Article Category Article List

Url .../v1/shops/{shopId}/articleCategories/{categoryId}/articles
Sample http://api.spreadshirt.net/api/v1/shops/205909/articleCategories/600/articles
Type LIST
Method GET
Special Status Codes  

Search request:

Use ?query=... to search on marketplace category articles and filter relevant articles. Works for marketplace shops (eu = 205909) only!

To restrict search to specific categories use categoryIds, productTypeDepartmentIds, productTypeCategoryIds, productTypeSizeIds and designIds set in query, e.g. ?query=liebe +categoryIds:(1000017 1000018 1000019) +productTypeDepartmentIds:(1 4) + productTypeCategoryIds:(100 200) +productTypeSizeIds:(2 3).

Please note that articles are grouped by used design!!! To disable that behaviour, you can use set the parameter groupSimilarItems to false like ?query=...&groupSimilarItems=false.

Response Representation:

<articles ...>
  ...
</articles>

See Article Representation

Retrieve Shop Article List

Url .../v1/shops/{shopId}/articles
Sample http://api.spreadshirt.net/api/v1/shops/40000/articles
Type LIST
Method GET
Special Status Codes  

Search request:

Use ?query=... to search on marketplace category articles and filter relevant articles. Works for marketplace shops (eu = 205909) only!

To restrict search to specific categories use categoryIds, productTypeDepartmentIds, productTypeCategoryIds, productTypeSizeIds and designIds set in query, e.g. ?query=liebe +categoryId:(1000017 1000018 1000019) +productTypeDepartmentIds:(1 4) + productTypeCategoryIds:(100 200) +productTypeSizeIds:(2 3).

Please note that articles are grouped by used design!!! To disable that behaviour, you can use set the parameter groupSimilarItems to false like ?query=...&groupSimilarItems=false.

Response Representation:

<articles ...>
  ...
</articles>

See Article Representation

Retrieve Shop Article Entity

Url .../v1/shops/{shopId}/articles/{articleId}
Sample http://api.spreadshirt.net/api/v1/shops/40000/articles/2876817
Type ENTITY
Method GET
Special Status Codes  

Response Representation:

<article ...>
   ...
</article>

See Article Representation

Retrieve Shop Article Price Entity

Url .../v1/shops/{shopId}/articles/{articleId}/price
Sample http://api.spreadshirt.net/api/v1/shops/40000/articles/2876817/price
Type ENTITY
Method GET
Special Status Codes  

Response Representation:

<price ...>
   ...
</price>

Representations

Product

Field Description
product Represents a platform product. A product represents a product type with one or more designs or text on one or multiple print areas.
product/@weight
The weight of the product in a list. Used for sorting products in a list.
product/user
Reference to the user that owns that product.
product/productType
Reference to the product type that was used to create this product. See Retrieve Shop ProductType Entity for more details.
product/appearance
Reference to the product type appearance (aka color) that was selected to create this product.
product/restrictions
Set of restrictions that tell you what you can't do with this product.
product/restrictions/freeColorSelection
FreeColorSelection set to false means you can't buy this product with a different product type appearance. So you should not allow to switch product type appearance in your web apps for such products.
product/configurations
List of configurations applied to the specified product type, i.e. text or designs.
product/configurations/configuration
One configuration applied to a print area of a product type.
product/configurations/configuration/@type
There are two types of configurations right now that apply either text or designs to a product type print area. So the type can either be text or design.
product/configurations/configuration/@id
The identifier of this configuration.
product/configurations/configuration/printArea
Reference to the print area to which the design or text is applied.
product/configurations/configuration/printType
Reference to the print type that shall later be used to actually print the text or design on the product type. See Retrieve Shop PrintType Entity for more details.
product/configurations/configuration/offset
The position relative to the print area's x,y coordinates starting from the left-top corner.
product/configurations/configuration/content
The actual configuration content. We use SVG to describe a configuration. We describe text configurations with SVG text and tspan tags and design configurations with image tags. Please read SVG specification for more details.
product/configurations/configuration/designs
List of designs extracted from SVG content (design configurations only). See Retrieve Shop Design Entity for more details.
product/configurations/configuration/designs/design
 
product/configurations/configuration/fontFamilies
List of font families extracted from SVG content (text configurations only). See Retrieve Shop FontFamily Entity for more details.
product/configurations/configuration/fontFamilies/fontFamily
 
product/configurations/configuration/restrictions
The restrictions tell you what you can't do with this configuration.
product/configurations/configuration/restrictions/changeable
Changeable tells you whether the configuration can be modified after product creation or not.
product/configurations/configuration/resources
References to configuration resources (aka images). Use this links in case you want to display configuration images!
product/configurations/configuration/resources/resource
 
product/resources
References to product resources (aka images). Use this links in case you want to display product images.
product/resources/resource
 

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns="http://api.spreadshirt.net" 
         weight="0.0" xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/9531579" id="9531579">
        <name>Unisex AA V-neck</name>
        <user xlink:href="http://api.spreadshirt.net/api/v1/users/1" id="1"/>
        <productType xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/productTypes/538" id="538"/>
        <appearance id="4"/>
        <restrictions>
            <freeColorSelection>false</freeColorSelection>
            <example>false</example>
        </restrictions>
        <configurations>
            <configuration type="design" id="13681987">
                <printArea id="1065"/>
                <printType xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/printTypes/14" id="14"/>
                <offset unit="mm">
                    <x>72.5713406593407</x>
                    <y>133.978373626374</y>
                </offset>
                <content dpi="25.4" unit="mm">
                    <svg viewBox="0 0 183.938 199.813">
                        <image xlink:href="http://image.spreadshirt.net/image-server/v1/designs/1475439,colors[0]=0091D3" transform="" height="199.813" width="183.938" printColorRGBs="#0091D3" printColorIds="16" designId="1475439"/>
                    </svg>
                </content>
                <designs>
                    <design xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/designs/1475439" id="1475439"/>
                </designs>
                <restrictions>
                    <changeable>true</changeable>
                </restrictions>
                <resources>
                    <resource xlink:href="http://image.spreadshirt.net/image-server/v1/configurations/13681987" mediaType="png"/>
                </resources>
            </configuration>
        </configurations>
        <resources>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/products/9531579/views/1,width=42,height=42" type="preview" mediaType="png"/>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/products/9531579/views/1" type="product" mediaType="png"/>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/compositions/9531579/views/1" type="composition" mediaType="png"/>
        </resources>
 </product>

Product with Multiple Lines of Text

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <productType id="95"/>
    <appearance id="2"/>
    <restrictions>
        <freeColorSelection>false</freeColorSelection>
        <example>false</example>
    </restrictions>
    <configurations>
        <configuration type="text">
            <printArea id="154"/>
            <printType id="14"/>
            <offset unit="mm">
                <x>1.0</x>
                <y>1.0</y>
            </offset>
            <content dpi="25.4" unit="mm">
                <svg>
                    <text transform="" font-style="normal" font-size="52"
                          font-weight="normal" font-family="Stop"
                          text-anchor="start" y="110" x="30" printColorId="12">
                        <tspan printColorId="17">Techno&#x26;</tspan>
                        <tspan y="170" x="30" printColorId="165">House&#x26;</tspan>
                        <tspan y="230" x="30" printColorId="87">Acid&#x26;</tspan>
                        <tspan y="290" x="30" printColorId="167">Jazz!</tspan>
                    </text>
                </svg>
            </content>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>
        </configuration>
    </configurations>
</product>

Product with Text and Design

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <productType id="6"/>
    <appearance id="2"/>
    <restrictions>
        <freeColorSelection>false</freeColorSelection>
        <example>false</example>
    </restrictions>
    <configurations>
        <configuration type="design">
            <printArea id="4"/>
            <printType id="2"/>
            <offset unit="mm">
                <x>100</x>
                <y>85</y>
            </offset>
            <content dpi="25.4" unit="mm">
                <svg>
                    <image transform="" height="200.025" width="109.008333333" printColorIds="1,8" designId="m2484607-2"/>
                </svg>
            </content>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>
        </configuration>
       <configuration type="text">
            <printArea id="4"/>
            <printType id="2"/>
            <offset unit="mm">
                <x>100.0</x>
                <y>135.0</y>
            </offset>
            <content dpi="25.4" unit="mm">
                <svg>
                    <text transform="" font-style="normal" font-size="44"
                          font-weight="normal" font-family="BelloScript"
                          text-anchor="start" y="65" x="1" printColorId="1">
                        <tspan>Heidi</tspan>
                    </text>
                </svg>
            </content>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>
        </configuration>
    </configurations>
</product>

Product with Design

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<product xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net">
    <productType id="6"/>
    <appearance id="2"/>
    <restrictions>
        <freeColorSelection>false</freeColorSelection>
        <example>false</example>
    </restrictions>
    <configurations>
        <configuration type="design">
            <printArea id="4"/>
            <printType id="2"/>
            <offset unit="mm">
                <x>60.0</x>
                <y>70.0</y>
            </offset>
            <content dpi="25.4" unit="mm">
                <svg>
                    <image transform="" width="200.025" height="194.945" printColorIds="1" designId="m1294214-1"/>
                </svg>
            </content>
            <restrictions>
                <changeable>false</changeable>
            </restrictions>
        </configuration>
    </configurations>
</product>

You can find more product examples in the API Browser application.

Article

Field
Description
article Represents a platform article. An article represents a product that is placed in a specific shop (marketplace) with a fixed price tag on it.
article/@weight
The weight of the article in a list. Used for sorting articles in a list.
article/name
The i18n name of the article in case of a marketplace article or the normal article name in case of a shop article.
article/description
The i18n description of the article in case of a marketplace article or the normal article description in case of a shop article.
article/tags
The i18n tags of the article in case of a marketplace article or the normal article tags in case of a shop article.
article/price
The article price in the currency of the shop.
article/shop
Reference to the shop to which this article belongs to.
article/product
Reference to the product on which this article is based. See Product for more details.
article/articleCategories
Reference to the article categories in which this article is placed.
article/articleCategories/articleCategory
 
article/resources
References to article resources (aka images). Use this links in case you want to display article images!
article/resources/resource
 
article/created
date when article was created
article/modified
date when article was last modified

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<article xmlns:xlink="http://www.w3.org/1999/xlink"                      
         xmlns="http://api.spreadshirt.net" 
         weight="-379425.0" 
         xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/articles/8306211" id="8306211">
        <name>Start a band </name>
        <description>Start a band </description>
        <price>
            <vatExcluded>22.90</vatExcluded>
            <vatIncluded>22.90</vatIncluded>
            <vat>0</vat>
            <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
        </price>
        <shop xlink:href="http://api.spreadshirt.net/api/v1/shops/205909" id="205909"/>
        <product xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/products/9531579" id="9531579">
            <productType xlink:href="http:///api.spreadshirt.net/v1/shops/205909/productTypes/538" id="538"/>
            <appearance id="4"/>
            <restrictions>
                <freeColorSelection>false</freeColorSelection>
                <example>false</example>
            </restrictions>
        </product>
        <articleCategories>
            <articleCategory id="1000029"/>
        </articleCategories>
        <resources>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/products/9531579/views/1,width=42,height=42" type="preview" mediaType="png"/>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/products/9531579/views/1" type="product" mediaType="png"/>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/compositions/9531579/views/1" type="composition" mediaType="png"/>
        </resources>
        <created>2010-06-07T19:15:11Z</created>
        <modified>2010-07-30T15:17:15Z</modified>
</article>

Article result search with article grouping - see related articles!!!:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<article ...>
    ...
    <relatedArticles>
            <relatedArticle id="4984934" xlink:href="http://localhost:8080/api/v1/shops/205909/articles/4984934"/>
            <relatedArticle id="4984935" xlink:href="http://localhost:8080/api/v1/shops/205909/articles/4984935"/>
    <relatedArticles>
    ...
</article>

Article Category

Field Description
articleCategory Represents a platform article category.
articleCategory/@type
Represents the type of the article category. In shop context, you will find the following types:
  • MY_ARTICLES
  • MARKETPLACE - Type for marketplace categories. Marketplace categories are categories from our special marketplace shop (eu - 205909, na - 117728)
  • SHOP - Type for generic shop categories defined by Spreadshirt.
  • SHOP_CUSTOM - Type of custom shop specific categories created by Spreadshirt partner.
  • BESTSELLER - Type for a magic category that allows to retrieve an ordered list of all items of the parent's sub categories.
    In user context, the types will be:
  • MY_ARTICLES
  • OWN - Articles owned by the partner.
articleCategory/@weight
The weight of the category is used for sorting categories in the category tree.
articleCategory/name
The i18n name of the category.
articleCategory/articles
Reference to the list of articles linked to this category.
articleCategory/articleCategories
List of sub categories of the article category.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<articleCategory xmlns:xlink="http://www.w3.org/1999/xlink"
                 xmlns="http://api.spreadshirt.net" 
                 type="MARKETPLACE" weight="0.0" id="1000171">
    <name>Vehicles</name>
    <articles xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/articleCategories/1000171/articles"/>
    <articleCategories>
        <articleCategory type="BESTSELLER" weight="-1.0" id="b1000171">
            <name>All Subtopics</name>
            <articles xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/articleCategories/b1000171/articles"/>
        </articleCategory>
        ...
    </articleCategories>
    ...
</articleCategory>

Search result - (see entry counts):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<articleCategories xmlns:xlink="http://www.w3.org/1999/xlink" 
                   xmlns="http://api.spreadshirt.net" 
                   query="liebe" sortOrder="asc" sortField="default" count="-1" limit="10" offset="0"  
                   xlink:href="http://localhost:8080/api/v1/shops/205909/articleCategories?fullData=true">
    <articleCategory type="BESTSELLER" weight="-1.0" id="600">
        <name>Bestseller</name>
        <entryCount>0</entryCount>
        <articles xlink:href="http://localhost:8080/api/v1/shops/205909/articleCategories/600/articles?query=liebe"/>
        <articleCategories/>
    </articleCategory>
   ...
</articleCategories>

Search result for faceted search:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<articleCategories xmlns:xlink="http://www.w3.org/1999/xlink" 
                   xmlns="http://api.spreadshirt.net" 
                   query="liebe" sortOrder="asc" sortField="default" count="-1" limit="10" offset="0" 
                   xlink:href="http://localhost:8080/api/v1/shops/205909/articleCategories?fullData=true">
    <facets>
        <facet type="PRODUCT_TYPE_DEPARTMENT">
            <entryCount>1059</entryCount>
            <optionPattern>+productTypeDepartmentIds:(x)</optionPattern>
            <entries>
                <entry id="1">
                    <entryCount>843</entryCount>

                    <option>+productTypeDepartmentIds:(1)</option>
                </entry>
                <entry id="3">
                    <entryCount>214</entryCount>
                    <option>+productTypeDepartmentIds:(3)</option>
                </entry>
                <entry id="4">

                    <entryCount>1</entryCount>
                    <option>+productTypeDepartmentIds:(4)</option>
                </entry>
                <entry id="5">
                    <entryCount>1</entryCount>
                    <option>+productTypeDepartmentIds:(5)</option>
                </entry>

            </entries>
        </facet>
        <facet type="PRODUCT_TYPE_CATEGORY">
            <entryCount>1059</entryCount>
            <optionPattern>+productTypeCategoryIds:(x)</optionPattern>
            <entries>
                <entry id="34">
                    <entryCount>83</entryCount>

                    <option>+productTypeCategoryIds:(34)</option>
                </entry>
                <entry id="33">
                    <entryCount>130</entryCount>
                    <option>+productTypeCategoryIds:(33)</option>
                </entry>
                <entry id="37">

                    <entryCount>1</entryCount>
                    <option>+productTypeCategoryIds:(37)</option>
                </entry>
                <entry id="25">
                    <entryCount>100</entryCount>
                    <option>+productTypeCategoryIds:(25)</option>
                </entry>

                <entry id="24">
                    <entryCount>680</entryCount>
                    <option>+productTypeCategoryIds:(24)</option>
                </entry>
                <entry id="40">
                    <entryCount>1</entryCount>
                    <option>+productTypeCategoryIds:(40)</option>

                </entry>
                <entry id="27">
                    <entryCount>63</entryCount>
                    <option>+productTypeCategoryIds:(27)</option>
                </entry>
                <entry id="47">
                    <entryCount>1</entryCount>

                    <option>+productTypeCategoryIds:(47)</option>
                </entry>
            </entries>
        </facet>
    </facets>
    <articleCategory type="BESTSELLER" weight="-1.0" id="600">
        <name>Bestseller</name>
        <entryCount>0</entryCount>

        <articles xlink:href="http://localhost:8080/api/v1/shops/205909/articleCategories/600/articles?query=liebe"/>
        <articleCategories/>
    </articleCategory>
   ...
</articleCategories>

Use Cases

Product Update Scenario

Please note that products are for a couple of reasons immutable - for example because of the generated and cached product images. So, to update a product, you need to delete the current one and add the new one. The image below describes an example scenario.

1.+2. Get current Product

Retrieve the data of the current product (optional).

3.+4. Delete current Product

Delete the old product that we have updated.

5.+6. Create new Product

Create the new product with the changed data.

7.+.8. Retrieve new Product

Retrieve the data of the added product (optional).

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.