If you had a custom system running based on a Legacy User Area (LUA) shop and your implementation broke in September or October 2019, it is because your account was migrated to the Partner Area (PA). This tutorial will show you how to adjust your implementation to get your custom system working again. If you do not know what the LUA is, this tutorial is not relevant to you.
Your custom system broke because the PA is not just another frontend, but because the domain entities we work with are slightly different and slightly different API endpoints have to be used. Your integration has thus to be adjusted to keep working as explained below.
Which parts of Spreadshirt's API are still valid and what exactly changed?
The good news is that the vast majority of the domain entities and their corresponding REST resources were not changed. They are still valid and work like they used to. However, articles and articleCategories became obsolete and will stop working once you are migrated. Products still exist, but they should not be worked with directly anymore when developing an online shop integration. Use ideas and sellables (sic!) instead as described here.
These new entities can be characterized as follows:
- an idea represents an image you uploaded in the Partner Area that you gave a name and added other meta data to. In the Partner Area this is loosely referred to as a design. This is not to be confused with the technical "design" term that we use in this document!
- a sellable is a representation of an idea printed on a product type. Depending on the product range selected in the Partner Area, one idea might have 100+ sellables associated with it.
A sellable is thus something concrete that a customer can buy, while an idea represents a grouping of content mainly intended to make administration easier.
The basket resources generally still work as they used to. However, keep in mind that only sellables can be added to a basket.
If your basket implementation is still XML based on you do not want to rework it entirely, just adapt your requests to use this payload fragment instead:
Note that the type property needs a different constant now and a shop tag needs to be sent as well.
Legacy article mapping resource
You may still have deeplinks or internal data structures referencing the soon-deleted articles.
To ease the transition phase, we provide the following resource that allows you to find the corresponding sellable your article was migrated to:
The response contains the identifiers necessary to make the connection between old and new domain entities.
This is too abstract for me. Do you have code examples available?
Yes, there is an example integration of this API available here.
It shows a draft of a shop system written in php that might be helpful to understand the (list-page -> detail-page -> add-to-basket) workflow.
There is no Public API available for uploading or updating ideas or sellables. This should be done via Partner Area.
Note that not only the content you upload in the Partner Area, but also the shop settings affect the output of the sellable resources. For example, enabling model images affects the image URLs returned by the API.
Will the design resources keep working?
Yes. Every idea and sellable references a design. The designs can thus be considered an alternative view on the data you manage in the Partner Area. However, in standard implementations, using these resources should not be necessary.
I am using a non-official designer-tool integration. How can I enable editing of sellables for my customers?
The designer tool can be bootstrapped with a parameter named sellableId. This will only work in Sketchomat/Smartomat, but not in Tablomat. Alternatively, bootstrapping the tool with productType & design still works.