Page tree
Skip to end of metadata
Go to start of metadata

This document specifies the API for accessing product data.

Resources Product

Retrieve Shop Product List

Url

.../v1/shops/{shopId}/products

Sample

https://api.spreadshirt.net/api/v1/shops/40000/products

Type

LIST

Method

GET

Special Status Codes

 

API Keyyes

Response Representation:

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

See Product Representation

Retrieve Shop Product Entity

Url

.../v1/shops/{shopId}/products/{productId}

Sample

https://api.spreadshirt.net/api/v1/shops/40000/products/1082550

Type

ENTITY

Method

GET

Special Status Codes

 

API Keyyes

Response Representation:

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

See Product Representation

Retrieve Shop Product Price Entity

Url

.../v1/shops/{shopId}/products/{productId}/price

Sample

https://api.spreadshirt.net/api/v1/shops/40000/products/1082550/price

Type

ENTITY

Method

GET

Special Status Codes

 

API Keyyes

Response Representation:

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

Create Shop Product Entity

Url

.../v1/shops/{shopId}/products

Sample

https://api.spreadshirt.net/api/v1/shops/40000/products

Type

LIST

Method

POST

Special Status Codes

201 (Product Created)

APIKey

yes

SessionId

no (yes 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

https://api.spreadshirt.net/api/v1/shops/40000/products/10815

Type

Entity

Method

DELETE

Special Status Codes

 

APIKey

yes

SessionId

no (yes if user is logged in)

Retrieve User Product List

Url

.../v1/users/{userId}/products

Sample

https://api.spreadshirt.net/api/v1/users/40000/products

Type

LIST

Method

GET

Special Status Codes

 

APIKey

yes

SessionId

yes

Response Representation:

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

See Product Representation

Retrieve User Product Entity

Url

.../v1/users/{userId}/products/{productId}

Sample

https://api.spreadshirt.net/api/v1/users/40000/products/1082550

Type

ENTITY

Method

GET

Special Status Codes

 

APIKey

yes

SessionId

yes

Response Representation:

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

See Product Representation

Retrieve User Product Price Entity

Url

.../v1/users/{userId}/products/{productId}/price

Sample

https://api.spreadshirt.net/api/v1/users/40000/products/1082550/price

Type

ENTITY

Method

GET

Special Status Codes

 

APIKey

yes

SessionId

yes

Response Representation:

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

Create User Product Entity

Url

.../v1/users/{userId}/products

Sample

https://api.spreadshirt.net/api/v1/users/40000/products

Type

LIST

Method

POST

Special Status Codes

200
201 (Product Created)

APIKey

yes

SessionId

yes

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

https://api.spreadshirt.net/api/v1/users/40000/products/10815

Type

Entity

Method

DELETE

Special Status Codes

 

APIKey

yes

SessionId

yes

Retrieve Shop Article Category List

Url

.../v1/shops/{shopId}/articleCategories

Sample

https://api.spreadshirt.net/api/v1/shops/40000/articleCategories

Type

LIST

Method

GET

Special Status Codes

 

API Keyyes

Search request:

Use ?query=... to search articles and filter relevant articles.

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

https://api.spreadshirt.net/api/v1/shops/205909/articleCategories/600/articles

Type

LIST

Method

GET

Special Status Codes

 

API Keyyes

Search request:

Use ?query=... to search category articles and filter relevant articles.

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

https://api.spreadshirt.net/api/v1/shops/40000/articles

Type

LIST

Method

GET

Special Status Codes

 

API Keyyes

Search request:

Use ?query=... to search on articles and filter relevant articles. 

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

https://api.spreadshirt.net/api/v1/shops/40000/articles/2876817

Type

ENTITY

Method

GET

Special Status Codes

 

API Keyyes

Response Representation:

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

See Article Representation

Retrieve Shop Article Price Entity

Url

.../v1/shops/{shopId}/articles/{articleId}/price

Sample

https://api.spreadshirt.net/api/v1/shops/40000/articles/2876817/price

Type

ENTITY

Method

GET

Special Status Codes

 

API Keyyes

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="https://api.spreadshirt.net/api/v1/shops/205909/products/9531579" id="9531579">
        <name>Unisex AA V-neck</name>
        <user xlink:href="https://api.spreadshirt.net/api/v1/users/1" id="1"/>
        <productType xlink:href="https://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="https://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="https://image.spreadshirtmedia.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="https://api.spreadshirt.net/api/v1/shops/205909/designs/1475439" id="1475439"/>
                </designs>
                <restrictions>
                    <changeable>true</changeable>
                </restrictions>
                <resources>
                    <resource xlink:href="https://image.spreadshirtmedia.net/image-server/v1/configurations/13681987" mediaType="png"/>
                </resources>
            </configuration>
        </configurations>
        <resources>
            <resource xlink:href="https://image.spreadshirtmedia.net/image-server/v1/products/9531579/views/1,width=42,height=42" type="preview" mediaType="png"/>
            <resource xlink:href="https://image.spreadshirtmedia.net/image-server/v1/products/9531579/views/1" type="product" mediaType="png"/>
            <resource xlink:href="https://image.spreadshirtmedia.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>

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="https://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="https://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
        </price>
        <shop xlink:href="https://api.spreadshirt.net/api/v1/shops/205909" id="205909"/>
        <product xlink:href="https://api.spreadshirt.net/api/v1/shops/205909/products/9531579" id="9531579">
            <productType xlink:href="https:///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="https://image.spreadshirtmedia.net/image-server/v1/products/9531579/views/1,width=42,height=42" type="preview" mediaType="png"/>
            <resource xlink:href="https://image.spreadshirtmedia.net/image-server/v1/products/9531579/views/1" type="product" mediaType="png"/>
            <resource xlink:href="https://image.spreadshirtmedia.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 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="https://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="https://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="https://api.spreadshirt.net/api/v1/shops/205909/articleCategories?fullData=true">
    <articleCategory type="BESTSELLER" weight="-1.0" id="600">
        <name>Bestseller</name>
        <entryCount>0</entryCount>
        <articles xlink:href="https://api.spreadshirt.net/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="https://api.spreadshirt.net/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="https://api.spreadshirt.net/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).

  • No labels