This is the documentation for 2022-02-01.
Variants
Here you can view a product variant or design a new one from an existing product variant.
When designing, information such as customizations, dimensions, files, etc. must be transferred. After that you will receive a new product variant that can be ordered.
#List
Returns a collection of variants.
#Filtering
You can filter your results as follows:
#List variants for specified id(s)
/variants?filter[id]=1
/variants?filter[id]=1,2,3
#List variants for a specified sku
The filtering is not an exact search, it looks for a part in the attribute value.
/variants?filter[origin.sku]=42443
See: Pagination, Filtering
#List variants for external identifier
You can filter your external identifier.
/variants?filter[origin.external_identifier]=extern-123
See: Pagination, Filtering
#List variants for specified collection name(s)
/variants?filter[collection_name]=catalogue
Allowed values are:
| Collection name | Description |
|---|---|
| catalogue | All variants which are created in the app administration. This can be used for designing. |
| custom | Variants which are designed by you but not ordered. See Design. |
| ordered | All ordered variants. |
See: Pagination, Filtering
#Expanding relationships
You can expand some resources to show more details.
See: Expanding Objects
#Expand product
You can show the content of the product instead of the id.
/variants?expand=product
#Expand customizations resource
You can show the content of the customizations' resource. The type is described by the resource_type attribute of the customization.
/variants?expand=views.customizations.resource
#Example listing products
Request
GET /variants HTTP/1.1
Response
{
"data": [
{
"id": 6,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "CadetBlue",
"name": "Cadet blue",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "m",
"name": "medium",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": 8,
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 25,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-cadetblue.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [
{
"id": 2,
"hash": "f6a925c77977ab958267ad897cf7af25706c02c6",
"production_method": {
"id": 1,
"collection_name": "dtg",
"handle": "dtg",
"name": "Direct to garmin",
"description": "Digital print",
"created_at": "2022-02-21T11:08:37+00:00",
"updated_at": "2022-02-21T11:08:37+00:00"
},
"resource_type": "logo",
"resource": 5,
"price": 0,
"calculation_type": "square_centimeter",
"calculation_value": 119.52,
"x": 130,
"y": 50,
"width": 144,
"height": 83,
"position": "tc",
"rotation": 0,
"created_at": "2022-02-21T11:11:33+00:00",
"updated_at": "2022-02-21T11:11:33+00:00"
}
]
},
],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
},
{
"id": 6,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "yellow",
"name": "yellow",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "xl",
"name": "extra large",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": 8,
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 6,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-yellow.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
},
{
"id": 6,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "red",
"name": "red",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "s",
"name": "small",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": 8,
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 6,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-red.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
},
...
],
"links": {
"first": "https://api.smake.io/v2/variants?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/variants?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/variants",
"per_page": 15,
"to": 15
}
}
#Example expanding relationships
Request
GET /variants?expand=product,views.customizations.resource HTTP/1.1
Response
{
"data": [
{
"id": 6,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "cadet-blue",
"name": "cadet blue",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "m",
"name": "medium",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": {
"id": 8,
"is_test": 0,
"title": "T-Shirt",
"description": "T-shirt with DTG",
"created_at": "2022-02-21T11:11:33+00:00",
"updated_at": "2022-02-21T11:11:33+00:00",
"variants": [
6,
7,
8,
...
]
},
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 25,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-cadetblue.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [
{
"id": 2,
"hash": "bcdba886ce2266fcbfbe779d4adcf365c29878ea",
"production_method": 1,
"resource_type": "logo",
"resource": {
"id": 5,
"state": "completed",
"collection_name": "ordered",
"name": "bat-1775692_960_720",
"production_method": 1,
"texts": [],
"media": [
{
"id": 1764,
"is_test": 0,
"collection_name": "original-data",
"file_name": "bat-1775692_960_720.png",
"size": 26618,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "ready",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-28T13:07:13+00:00",
"updated_at": "2022-02-28T13:07:13+00:00"
},
{
"id": 1765,
"is_test": 0,
"collection_name": "production-file",
"file_name": "bat-1775692_960_720.png",
"size": 26618,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "pending",
"failure_message": null,
"custom_properties": {
"width": 960,
"height": 480,
"mime-type": "image/png"
},
"created_at": "2022-02-28T13:07:13+00:00",
"updated_at": "2022-02-28T13:07:13+00:00"
},
{
"id": 1766,
"is_test": 0,
"collection_name": "preview-file",
"file_name": "bat-1775692_960_720.png",
"size": 19077,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "pending",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-28T13:07:15+00:00",
"updated_at": "2022-02-28T13:07:15+00:00"
}
],
"failure_message": null,
"created_at": "2022-02-28T13:07:09+00:00",
"updated_at": "2022-02-28T13:07:15+00:00"
},
"price": 21.5,
"calculation_type": "square_centimeter",
"calculation_value": 100,
"x": null,
"y": null,
"width": 100,
"height": 100,
"position": null,
"rotation": null,
"created_at": "2022-02-28T13:07:09+00:00",
"updated_at": "2022-02-28T13:07:16+00:00"
}
]
},
],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
},
...
],
"links": {
"first": "https://api.smake.io/v2/variants?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/variants?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/variants",
"per_page": 15,
"to": 15
}
}
#Get
Returns the product variant with the id = x.
#Expanding relationships
You can expand some resources to show more details.
See: Expanding Objects
#Expand product
You can show the content of the product instead of the id.
/variants/1?expand=product
#Expand customizations resource
You can show the content of the customizations' resource. The type is described by the resource_type attribute of the customization.
/variants/1?expand=views.customizations.resource
#Example get a variant
Request
GET /variants/1 HTTP/1.1
Response
{
"id": 1,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "cadet-blue",
"name": "cadet blue",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "m",
"name": "medium",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": 8,
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 25,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-cadetblue.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [
{
"id": 2,
"hash": "f6a925c77977ab958267ad897cf7af25706c02c6",
"production_method": {
"id": 1,
"collection_name": "dtg",
"handle": "dtg",
"name": "Direct to garmin",
"description": "Digital print",
"created_at": "2022-02-21T11:08:37+00:00",
"updated_at": "2022-02-21T11:08:37+00:00"
},
"resource_type": "logo",
"resource": 5,
"price": 0,
"calculation_type": "square_centimeter",
"calculation_value": 119.52,
"x": 130,
"y": 50,
"width": 144,
"height": 83,
"position": "tc",
"rotation": 0,
"created_at": "2022-02-21T11:11:33+00:00",
"updated_at": "2022-02-21T11:11:33+00:00"
}
]
},
],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
}
#Example expanding relationships
Request
GET /variants/1?expand=product,views.customizations.resource HTTP/1.1
Response
{
"id": 1,
"state": "ready",
"collection_name": "catalogue",
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"option_values": [
{
"handle": "cadet-blue",
"name": "cadet blue",
"option_type": {
"handle": "color",
"name": "color"
}
},
{
"handle": "m",
"name": "medium",
"option_type": {
"handle": "size",
"name": "size"
}
},
],
"origin": {
"sku": "0441837446362",
"external_identifier": "56879425369"
},
"product": {
"id": 8,
"is_test": 0,
"title": "T-Shirt",
"description": "T-shirt with DTG",
"created_at": "2022-02-21T11:11:33+00:00",
"updated_at": "2022-02-21T11:11:33+00:00",
"variants": [
6,
7,
8,
...
]
},
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 25,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-cadetblue.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e1fd546508dd484b908c5fc653f65818/view-image-front-lime.png?xyz",
"state": "completed",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-21T11:10:40+00:00",
"updated_at": "2022-02-21T11:10:40+00:00"
}
],
"customizations": [
{
"id": 2,
"hash": "f6a925c77977ab958267ad897cf7af25706c02c6",
"production_method": {
"id": 1,
"collection_name": "dtg",
"handle": "dtg",
"name": "Direct to garmin",
"description": "Digital print",
"created_at": "2022-02-21T11:08:37+00:00",
"updated_at": "2022-02-21T11:08:37+00:00"
},
"resource_type": "logo",
"resource": {
"id": 5,
"state": "completed",
"collection_name": "ordered",
"name": "bat-1775692_960_720",
"production_method": 1,
"texts": [],
"media": [
{
"id": 1764,
"is_test": 0,
"collection_name": "original-data",
"file_name": "bat-1775692_960_720.png",
"size": 26618,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "ready",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-28T13:07:13+00:00",
"updated_at": "2022-02-28T13:07:13+00:00"
},
{
"id": 1765,
"is_test": 0,
"collection_name": "production-file",
"file_name": "bat-1775692_960_720.png",
"size": 26618,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "pending",
"failure_message": null,
"custom_properties": {
"width": 960,
"height": 480,
"mime-type": "image/png"
},
"created_at": "2022-02-28T13:07:13+00:00",
"updated_at": "2022-02-28T13:07:13+00:00"
},
{
"id": 1766,
"is_test": 0,
"collection_name": "preview-file",
"file_name": "bat-1775692_960_720.png",
"size": 19077,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/cf1fdca0862a4c7296b5bd02a7d6ce58/bat-1775692_960_720.png?xyz",
"state": "pending",
"failure_message": null,
"custom_properties": [],
"created_at": "2022-02-28T13:07:15+00:00",
"updated_at": "2022-02-28T13:07:15+00:00"
}
],
"failure_message": null,
"created_at": "2022-02-28T13:07:09+00:00",
"updated_at": "2022-02-28T13:07:15+00:00"
},
"price": 0,
"calculation_type": "square_centimeter",
"calculation_value": 119.52,
"x": 130,
"y": 50,
"width": 144,
"height": 83,
"position": "tc",
"rotation": 0,
"created_at": "2022-02-21T11:11:33+00:00",
"updated_at": "2022-02-21T11:11:33+00:00"
}
]
},
],
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
}
#Design
#Background processing
When you design a product variant, this happens asynchronously. You can use
use Polling or Webhooks for status updated. A new product variant is created implicitly.
Therefore, you will already receive the new product variant id in the header for later reference.
The current state of the asynchronous process is represented due the following states:
| State | Meaning |
|---|---|
draft |
The initial state of a new variant |
checking |
Variant is processed automatically in background. For example images will be generated or downloaded. |
failed |
Something went wrong during the checking process. The reason can be found in the failure_message attribute. For example an image could not be downloaded. |
completed |
All automatic processes were successful. The variant is ready to use. |
It is not possible to order this product variant before state completed.
#How to design
Designing a product variant is made possible by placing customizations on the corresponding view (e. g. front or back).
| Field | Type | Description | Required |
|---|---|---|---|
| type | string | The variant designing type. Current available type is basic. |
yes |
| views | array | Contains the views on which customizations are placed. The maximum number is 4. One object each for front, back, left and right. See Views Object |
yes |
| adopt_design_from_variant | object | You can adopt the designs from another variant. Note that the variants must belong to the same product. |
#Views Object
| Field | Type | Description | Required |
|---|---|---|---|
| handle | string | Unique identifier for the view. Possible values are front, back, left and right. |
yes |
| media | array | A collection of images for the view. Allowed collection name is mockup. See Media Object. |
yes |
| customizations | array | A collection of customizations. See Customization Object. |
#Customization Object
| Field | Type | Description | Required |
|---|---|---|---|
| resource_type | string | Defines the resource type of the placement. Possible values are logo and additional-instruction. |
yes |
| width | float | The width of the customization in millimetres (mm). | sometimes* |
| height | float | The height of the customization in millimetres (mm). | sometimes* |
| resource | object | The content of the customization. See Resource Object | yes |
* Required for manual production methods. Prohibited for additional instructions.
#Resource Object
| Field | Type | Description | Required |
|---|---|---|---|
| production_method | object | Defines the production method for this resource. See Production Methods | yes* |
| id | int | Use this id if you want to use an existing logo or an additional instruction. Only additional instructions with type = product can be assigned as customization resource. Depends on the resource_type attribute of the Customization object. See Customization Object. |
yes** |
| media | array | Use this collection, if you want to create the customizations resource (Logo) with a media. See Media Object. Allowed collection names: production-file |
yes** |
* Required if you want to create a logo with a media url or a media id.
** You must use either a id or a media object for the customization.
#Media Object
| Field | Type | Description | Required |
|---|---|---|---|
| collection_name | string | Unique identifier for the intended use. Allowed names can be found on the object which is using the media. | yes |
| id | int | Use this id if you want to use an existing Media from your uploads. See Media. |
yes* |
| url | string | Url which references a file. This file will be downloaded and attached to the resource. | yes* |
* You have to choose exactly one of id or url.
#Production Method Object
For a list of available production methods see Production Methods.
| Field | Type | Description | Required |
|---|---|---|---|
| id | int | The production methods id. | yes* |
| handle | string | The production method handle which is defined by the producer. | yes* |
* You have to choose exactly one of id or handle.
#Adobt design from variant object
With the use of this object you can adopt the design from another variant of the same product.
| Field | Type | Description | Required |
|---|---|---|---|
| id | integer | The id from the variant which contains the customizations you want to adopt. | yes |
#Example
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"views": [
{
"handle": "front",
"media": [
{
"url": "https://any.link.to/image",
"collection_name": "mockup"
}
],
"customizations": [
{
"resource_type": "logo",
"width": 200,
"height": 200,
"resource": {
"production_method": {
"handle": "dtg"
},
"media": [
{
"url": "https://any.link.to/production-file",
"collection_name": "production-file"
}
]
}
},
{
"resource_type": "additional-instruction",
"resource": {
"id": 1
}
}
]
}
]
}
Response
HTTP/1.1 202 Accepted
Location https://api.smake.io/jobs/1
X-Identifier: 137
The X-Identifier is the new generated product variant id for later reference.
#Further design examples
You can combine the usage of id and url on different models.
#Design with media id
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"views": [
{
"handle": "front",
"media": [
{
"id": 5,
"collection_name": "mockup"
}
],
"customizations": [
{
"resource_type": "logo",
"width": 200,
"height": 200,
"resource": {
"production_method": {
"handle": "dtg"
},
"media": [
{
"id": 7,
"collection_name": "production-file"
}
]
}
},
]
}
]
}
#Design with logo id
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"views": [
{
"handle": "front",
"media": [
{
"id": 5,
"collection_name": "mockup"
}
],
"customizations": [
{
"resource_type": "logo",
"resource": {
"id": 25
}
},
]
}
]
}
#Design with logo id and resize logo
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"views": [
{
"handle": "front",
"media": [
{
"id": 5,
"collection_name": "mockup"
}
],
"customizations": [
{
"resource_type": "logo",
"width": 350,
"height": 350,
"resource": {
"id": 25
}
},
]
}
]
}
#Design with media id and mockup with url
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"views": [
{
"handle": "front",
"media": [
{
"url": "https://any.link.to/mockup",
"collection_name": "mockup"
}
],
"customizations": [
{
"resource_type": "logo",
"width": 200,
"height": 200,
"resource": {
"production_method": {
"handle": "dtg"
},
"media": [
{
"id": 7,
"collection_name": "production-file"
}
]
}
},
]
}
]
}
#Adopt design from another variant
In some cases, it is necessary to adopt the design from another variant. For example, the user wants to order one predesigned variant in different sizes.
Request
POST /variants/136/design HTTP/1.1
{
"type": "basic",
"adopt_design_from_variant": {
"id": 158
}
}