# Introduction (/docs/checkout/2021-02-23)
You are viewing the documentation for API version **2021-02-23**. This version
is frozen — new integrations should use
[version 2022-02-01](/docs/checkout/2022-02-01). See the
[changelog](/docs/checkout/2022-02-01/references/changelog) for migration notes.
The Smake API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). It has
predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and
uses standard HTTP response codes, authentication, and verbs.
You can browse your products, upload media and combine them to create new designed variants. Then you can
create an order through our checkout to trigger the production process.
## Basic terms [#basic-terms]
| Term | Description |
| ---------- | ----------------------------------------------------------- |
| Resource | An object (for example, a product variant) |
| Collection | Listing of objects (for example, all variants of a product) |
## API Endpoint [#api-endpoint]
```bash
https://api.smake.io/v2/apps/{APP_ID_HERE}
```
### Note about the API Endpoint [#note-about-the-api-endpoint]
Within the Api endpoint, the substring `APP_ID_HERE` must be replaced with your App Id.
## Using these docs with AI tools [#using-these-docs-with-ai-tools]
This documentation is also served as plain Markdown for AI assistants like Claude, Claude Code, or ChatGPT:
* [`/llms.txt`](/llms.txt) — index of all pages
* [`/llms-full.txt`](/llms-full.txt) — the complete documentation as a single Markdown document
* Append `.md` to any page URL to get that page as Markdown
For example, point your AI tool at `https://docs.smake.com/llms-full.txt` to give it the full API context — or use the **Copy Markdown** / **Open in …** buttons at the top of each page.
# Introduction (/docs/checkout/2022-02-01)
The [endpoint reference](/docs/checkout/2022-02-01/endpoints/orders/listOrders) ("Endpoints" in the
sidebar) is generated from our OpenAPI specification — with a try-it
playground and code examples in 8 languages, including PHP.
The Smake API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). It has
predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and
uses standard HTTP response codes, authentication, and verbs.
You can browse your products, upload media and combine them to create new designed variants. Then you can
create an order through our checkout to trigger the production process.
## Basic terms [#basic-terms]
| Term | Description |
| ---------- | ----------------------------------------------------------- |
| Resource | An object (for example, a product variant) |
| Collection | Listing of objects (for example, all variants of a product) |
## API Endpoint [#api-endpoint]
```bash
https://api.smake.io/v2/apps/{APP_ID_HERE}
```
### Note about the API Endpoint [#note-about-the-api-endpoint]
Within the Api endpoint, the substring `APP_ID_HERE` must be replaced with your App Id.
## Using these docs with AI tools [#using-these-docs-with-ai-tools]
This documentation is also served as plain Markdown for AI assistants like Claude, Claude Code, or ChatGPT:
* [`/llms.txt`](/llms.txt) — index of all pages
* [`/llms-full.txt`](/llms-full.txt) — the complete documentation as a single Markdown document
* Append `.md` to any page URL to get that page as Markdown
For example, point your AI tool at `https://docs.smake.com/llms-full.txt` to give it the full API context — or use the **Copy Markdown** / **Open in …** buttons at the top of each page.
# Introduction (/docs/master/2022-07-01)
The Smake API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). It has
predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and
uses standard HTTP response codes, authentication, and verbs.
You can browse your products, upload media and combine them to create new designed variants. Then you can
create an order through our checkout to trigger the production process.
## Basic terms [#basic-terms]
| Term | Description |
| ---------- | ----------------------------------------------------------- |
| Resource | An object (for example, a product variant) |
| Collection | Listing of objects (for example, all variants of a product) |
## API Endpoint [#api-endpoint]
```bash
https://api.smake.io/master-administration/{ENDPOINTS_HERE}
```
### Note about the API Endpoint [#note-about-the-api-endpoint]
Within the Api endpoint, the substring `ENDPOINTS_HERE` must be replaced with desired endpoint.
## Using these docs with AI tools [#using-these-docs-with-ai-tools]
This documentation is also served as plain Markdown for AI assistants like Claude, Claude Code, or ChatGPT:
* [`/llms.txt`](/llms.txt) — index of all pages
* [`/llms-full.txt`](/llms-full.txt) — the complete documentation as a single Markdown document
* Append `.md` to any page URL to get that page as Markdown
For example, point your AI tool at `https://docs.smake.com/llms-full.txt` to give it the full API context — or use the **Copy Markdown** / **Open in …** buttons at the top of each page.
# Conditional Request (/docs/checkout/2021-02-23/basic/conditional-request)
All **successful GET requests** responses return an `ETag` header. You can use the `ETag` value to make
subsequent requests to those resources using the `If-None-Match` header. If the resource has not changed,
the server returns a `304 Not Modified`.
Making a conditional request and receiving a 304 response does not count against your [Rate Limit](./rate-limit),
so we encourage you to use it whenever possible.
## Examples [#examples]
### Without If-None-Match Header [#without-if-none-match-header]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
GET /orders HTTP/1.1 200 OK
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
***
### With If-None-Match Header [#with-if-none-match-header]
Request
```json
GET /orders HTTP/1.1
If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
Response
```json
GET /orders HTTP/1.1 304 Not Modified
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
# Expanding Objects (/docs/checkout/2021-02-23/basic/expanding-objects)
Many objects contain the `id` of a related object in their response properties. For example, a Product may
have associated Variant ids. Those objects can be expanded inline with the `expand` request parameter.
Objects that can be expanded are noted in this documentation.
You can expand recursively by specifying nested fields after a dot (`.`). For example,
requesting `items.variant` on an order will expand the variant property into a full variant object.
You can expand multiple objects at once by separating them with a comma.
Variants Not Expanded
#### Request [#request]
```json
GET /products/1 HTTP/1.1
```
#### Response [#response]
```json
{
"is_test": false,
"id": 1,
"title": "qui ut nemo",
"description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:48+00:00",
"variants": [
90,
92,
94,
]
}
```
Variants Expanded
#### Request [#request-1]
```json
GET /products/1?expand=variants HTTP/1.1
```
#### Response [#response-1]
```json
{
"is_test": false,
"id": 1,
"title": "qui ut nemo",
"description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:48+00:00",
"variants": [
{
"id": 90,
"total": 101.7,
"price": 85.46,
"tax": 16.24,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "RoyalBlue"
},
{
"name": "size",
"value": "S"
}
],
"origin": {
"code": "0635579894134"
},
"media_id": 607,
"views": {
"back": {
"composite_media_id": 609,
"customizations": []
},
"left": {
"composite_media_id": 610,
"customizations": []
},
"front": {
"composite_media_id": 608,
"customizations": []
},
"right": {
"composite_media_id": 611,
"customizations": []
}
},
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:50+00:00"
},
{
"id": 92,
"total": 185.21,
"price": 173.09,
"tax": 12.12,
"tax_rate": 7,
"attributes": [
{
"name": "color",
"value": "DarkCyan"
},
{
"name": "size",
"value": "L"
}
],
"origin": {
"code": "6904687103174"
},
"media_id": 617,
"views": {
"back": {
"composite_media_id": 619,
"customizations": []
},
"left": {
"composite_media_id": 620,
"customizations": []
},
"front": {
"composite_media_id": 618,
"customizations": []
},
"right": {
"composite_media_id": 621,
"customizations": []
}
},
"created_at": "2017-11-15T08:07:49+00:00",
"updated_at": "2017-11-15T08:07:50+00:00"
},
{
"id": 94,
"total": 24.52,
"price": 20.61,
"tax": 3.91,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "Blue"
},
{
"name": "size",
"value": "L"
}
],
"origin": {
"code": "1243574262255"
},
"media_id": 627,
"views": {
"back": {
"composite_media_id": 629,
"customizations": []
},
"left": {
"composite_media_id": 630,
"customizations": []
},
"front": {
"composite_media_id": 628,
"customizations": []
},
"right": {
"composite_media_id": 631,
"customizations": []
}
},
"created_at": "2017-11-15T08:07:50+00:00",
"updated_at": "2017-11-15T08:07:50+00:00"
}
]
}
```
# Filtering (/docs/checkout/2021-02-23/basic/filtering)
You can search within a collection using `?filter[field]`.
## URL Syntax [#url-syntax]
* `/resources?filter[field]=value`
**Not all attributes are searchable**. Some attributes are **computed attributes** and are not physically
so that they are not searchable. In this case, an exception is thrown.
## Example [#example]
Request
```json
GET /orders?filter[state]=delivered HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"state": "delivered",
"customer_locale": "de",
"currency": "EUR",
"total": 87.76,
"subtotal": 86.63,
"total_tax": 1.13,
"total_items_price": 82.98,
"shipping_total": 4.78,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:11:03+00:00",
"cancelled_at": null,
"items": [
{
"id": 1,
"quantity": 4,
"total": 82.98,
"price": 20.54,
"total_tax": 0.82,
"tax_rate": 1,
"variant": {
"id": 27,
"total": 186.58,
"price": 174.37,
"tax": 12.21,
"tax_rate": 7,
"attributes": [
{
"name": "color",
"value": "Khaki"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "4490824589755"
},
"media_id": 251,
"views": [],
"created_at": "2017-09-27T10:10:38+00:00",
"updated_at": "2017-09-27T10:10:38+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 40,
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "12345 67890",
"addresses": [
{
"id": 10,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"email": "john@example.com",
"phone": "12345 67890",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
},
{
"id": 11,
"default": false,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"email": "john@example.com",
"phone": "12345 67890",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
],
"default_address": {
"id": 10,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"email": "john@example.com",
"phone": "12345 67890",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"shipping_address": {
"id": 45,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"email": "john@example.com",
"phone": "12345 67890",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"billing_address": {
"id": 44,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"email": "john@example.com",
"phone": "12345 67890",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"whitelabel_address": null,
"transactions": [
{
"amount": 87.76,
"title": "Invoice"
}
],
"fulfillments": [
{
"id": 1,
"tracking_number": "2229446017085",
"order": 1,
"parcels": [
[
1
]
],
"created_at": "2021-02-24T11:04:46+01:00",
"updated_at": "2021-02-25T11:35:50+01:00"
}
],
"id_tags": [
{
"id": 1,
"order_item_id": 1,
"current_state": "Goods booked in",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 2,
"order_item_id": 1,
"current_state": "Released to production stage",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 3,
"order_item_id": 1,
"current_state": "Shipped",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 4,
"order_item_id": 1,
"current_state": "Scanned on machine (DTG)",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
]
}
],
"links": {
"first": "https://api.smake.io/v2/orders?filter%5Bitems.quantity%5D=4&filter%5Bstate%5D=delivered&filter%5Bcustomer.first_name%5D=like%3A%2Aendr%2A&page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/orders",
"per_page": 25,
"to": 1
}
}
```
# HTTP Status (/docs/checkout/2021-02-23/basic/http-status)
Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.
In the case of a problem, the status contains the error code, while the body of the response will usually
contain additional information about the problem that was encountered.
## Successful [#successful]
In general, if the status returned is in the **200** range, it indicates that the request was
fulfilled successfully and that no error was encountered.
## Client error [#client-error]
Return codes in the **400** range typically indicate that there was an issue with the request that was sent. Among
other things, this could mean that you did not authenticate correctly, that you are requesting an action
that you do not have authorization for, that the object you are requesting does not exist, or that your request
is malformed.
## Server Error [#server-error]
If you receive a status in the **500** range, this generally indicates a server-side problem. This means that we
are having an issue on our end and cannot fulfill your request currently. The following table summarizes the
typical status codes:
## Codes [#codes]
| Code | Description |
| --------------------------- | ------------------------------------------------------------ |
| 200 - OK | Everything works as expected. |
| 201 - Created | The resource was created successfully. |
| 202 - Accepted | The request was accepted and is processed in the background. |
| 204 - No Content | The resource was successfully deleted. |
| 400 - Bad Request | Valid data was specified, but the request failed. |
| 401 - Unauthorized | No valid Api Key has been specified. |
| 404 - Not Found | The requested resource does not exist. |
| 422 - Unprocessable Entity | The payload has missing required parameters or invalid data. |
| 429 - Too Many Requests | Too many requests in a short time. |
| 500 - Internal Server Error | Request failed due to an internal error in Smake. |
| 503 - Service Unavailable | Smake is offline for maintenance. |
We recommend writing code that gracefully handles all possible API exceptions.
Please handle the status codes and not the `message` or `errors`. These only contain additional
information for you to analyze the problem.
## Examples [#examples]
Generic Errors
```json
HTTP/1.1 401 Unauthenticated
{
"status_code": 401,
"message": "API Key is invalid.",
"errors": []
}
```
Validation Errors
```json
HTTP/1.1 422 Unprocessable Entity
{
"status_code": 422,
"message": "The request data you sent is not valid.",
"errors": {
"shipping_address": {
"first_name": [
"The firstname field is required."
]
},
"items": [
{
"quantity": [
"The items.0.quantity must be at least 1."
]
}
]
}
}
```
# Localization (/docs/checkout/2021-02-23/basic/localization)
## Display [#display]
By default, a resource is presented in **english**.
You can also display the resource in another language.
With the `Accept-Language` header a resource can be localized.
However, this does not affect validation messages or any errors. These
are still displayed in English.
The following locales are currently available for Accept-Language:
`en`, `de`, `nl`, `fr`, `ar`, `sv`, `pl` and `tk`
## Saving [#saving]
In some cases, you can also save a resource localized. For example, the **Checkout Api** uses this to save
an order in a **specified language**. By default it is stored in english, using the `Accept-Language` header
you can control how it is stored.
This is important if, for example, the delivery note is to be displayed in a specific language.
The localization of documents (e. g.: delivery note) cannot be regenerated afterwards.
## Examples [#examples]
### Request for display a response with another language [#request-for-display-a-response-with-another-language]
Request
```json
GET /variants/1 HTTP/1.1
Accept-Language: 'de'
```
Response
```json
Content-Language: 'de'
{
"id": 1,
"attributes": [
{
"name": "color",
"value": "Gelb"
}
]
...
}
```
### Request for saving a resources with another language [#request-for-saving-a-resources-with-another-language]
Request
```json
POST /orders HTTP/1.1
Accept-Language: 'de'
{
"email": "customer@example.com",
"items": [
{
"variant_id": 1,
"quantity": 1
}],
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"street1": "123 Main St",
"zip": "12345",
"city": "Anytown",
"country_code": "DE",
"province_code": "NW",
"phone": "12345 67890",
"email": "shipping@example.com"
}
}
```
Response
```json
Content-Language: 'de'
{
"id": 1,
"external_identifier": null,
"external_reference": null,
"state": "incompleted",
"customer_locale": "de",
...
}
```
# Pagination (/docs/checkout/2021-02-23/basic/pagination)
Each collection always has a `meta` and `links` key with information about the paginator.
## Meta [#meta]
`meta` contains the complete information of the paginator, such as the current page or the number of results.
## Links [#links]
`links` contains the direct URLs for navigating through the result set (`first`, `last`, `prev` and `next`).
## Parameters [#parameters]
By default, **25** objects are returned per page.
You can request a different pagination limit or force pagination by appending `?per_page` to the request
with the number of items you would like per page. For instance, to show only two results per page, you could
add `?per_page=2` to the end of your query. The maximum number of results per page is **100**.
You can use the URLs listed under `links` to browse through the pages or directly select a page using
the `?page` query string parameter. With `?page=4` you can e. g. go directly to page 4.
## Example [#example]
Request
```json
GET /media?per_page=2&page=4 HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1005,
"is_test": true,
"file_name": "39b8196929f742e7bccab01a643b6524.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1005/download",
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00"
},
{
"id": 1006,
"is_test": true,
"file_name": "5d9de455299a4c369fcf719b677cf4cd.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1006/download",
"created_at": "2017-09-28T08:46:21+00:00",
"updated_at": "2017-09-28T08:46:21+00:00"
}
],
"links": {
"first": "https://api.smake.io/v2/media?page=1&per_page=2",
"last": null,
"prev": "https://api.smake.io/v2/media?page=3&per_page=2",
"next": "https://api.smake.io/v2/media?page=2&per_page=2"
},
"meta": {
"current_page": 4,
"from": 1,
"path": "https://api.smake.io/v2/media",
"per_page": 2,
"to": 2,
}
}
```
# Pooling (/docs/checkout/2021-02-23/basic/polling)
If a task takes longer than the request timeout limit, the request is acknowledged by a `202 Accepted`
and treated as a background job.
You don't get the requested data directly, instead you get the URL of the background job in the `Location` header,
which shows you the background job status.
A far more efficient way to get the desired data are [Webhooks](./webhooks).
## Query job status [#query-job-status]
You need to check this URL periodically to check when the background job is finished.
When the background job is completed, a `200 OK` is returned and the response body filled the `resource_url` to complete the next step. If not, a `202 Accepted` will still be returned and the `resource_url` will remain empty.
## Examples [#examples]
### Create a long running task [#create-a-long-running-task]
Request
```json
POST /variant/1/design HTTP/1.1
```
Response
```json
HTTP/1.1 202 Accepted
Location: https://api.smake.io/v2/jobs/1
```
***
### The job is not finished. [#the-job-is-not-finished]
Request
```json
GET /jobs/1 HTTP/1.1
```
Response
```json
Location: https://api.smake.io/v2/jobs/1
{
"id": 1,
"is_test": true,
"resource_url": null,
"state": "queued"
}
```
### The job is finished. [#the-job-is-finished]
Request
```json
GET /jobs/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": true,
"resource_url": "https://api.smake.io/v2/custom-variants/2",
"state": "finished"
}
```
# Rate Limit (/docs/checkout/2021-02-23/basic/rate-limit)
The number of requests that can be made through the API is currently limited to 5000 requests per hour.
The rate limiting information is contained within the response headers of each request.
If the `X-RateLimit-Remaining` **0** is reached, subsequent requests receive a **429** error code until the
`X-RateLimit-Reset` is reached.
## Headers [#headers]
| Header Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-RateLimit-Limit | The number of requests that can be made per hour. |
| X-RateLimit-Remaining | The number of requests that remain before you hit your request limit. |
| X-RateLimit-Reset | This represents the time when the oldest request will expire. The value is given in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time). |
If you exceed your rate limit, you can likely fix the issue by caching API responses and using [Conditional Request](./conditional-request).
## Examples [#examples]
### Rate Limit not reached [#rate-limit-not-reached]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4954
{
"data": [
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
....
}
]
}
```
### Rate Limit reached [#rate-limit-reached]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
GET /orders HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "Too many attempts."
}
```
# Request Id (/docs/checkout/2021-02-23/basic/request-id)
Each API request has an associated request identifier.
You can find this value in the response headers, under `X-Request-Id`.
### Request [#request]
```json
GET /orders HTTP/1.1 200 OK
```
### Response [#response]
```json
X-Request-Id: d312517c-7ac9-402d-87c5-0a6b9da92a4d
```
If you need to contact us about a specific request, providing the request identifier will
ensure the fastest possible resolution.
# Request (/docs/checkout/2021-02-23/basic/request)
Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI.
The interface responds to different methods depending on the action required.
| Method | Use |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | For simple retrieval of information, you should use the GET method. The information you request will be returned to you as a JSON object. Any request using the GET method is read-only and will not affect any of the objects you are querying. |
| DELETE | To destroy a resource, use the DELETE method. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. |
| PUT | To update the information about a resource, the PUT method is available. The PUT request contains all attributes that are to be updated for an object. |
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint. |
# Response (/docs/checkout/2021-02-23/basic/response)
When a request is successful, a response body will typically be sent back in the form of a JSON object.
One exception is the `DELETE` request, which will result in a successful `HTTP 204 status` and an empty response body.
Another exception is when a request is processed asynchronously, it will result in a successful
`HTTP 202 status` and an empty response body.
## Collection [#collection]
A collection of resources will be displayed within the `data` object.
```json
{
"data": [
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
....
}
]
}
```
## Resource [#resource]
A resource are presented directly.
```json
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
...
}
```
## Attribute [#attribute]
If an attribute has no value it is presented as `null`.
If an attribute is some kind of list and it is represented by an array, an array will be returned, even if empty.
```json
{
"company": null,
"addresses": [],
...
}
```
## Timestamp [#timestamp]
All time values presented in ISO8601 format: `YYYYY-MM-DDTHH:MM:SSZ`.
# Webhooks (/docs/checkout/2021-02-23/basic/webhooks)
Webhooks are a feature that allows you to have your system receive notifications about a certain event on our site.
When an event happens, the Smake server sends a POST request to your defined endpoint URLS.
This request contains all the relevant information about the Event, including the type and the data
associated with that. You can have Smake send a single event to multiple webhook endpoints.
Webhook data is sent as JSON in the POST request body.
To acknowledge receipt of a event, your endpoint must return a 2xx HTTP status code.
All response codes outside this range indicate to Smake that you did not receive the event.
If you do not acknowledge receipt of a event, Smake will continue to deliver your webhooks with
an exponential backoff for up to one day.
This is similar to [polling](./polling), webhooks provide your application a way of consuming data that
takes longer to proccess, but instead of sending repeated requests for new data, you will be informed per events.
**Webhooks are the prefered way of consuming data that takes longer to proccess, because there are far more efficient.**
## Retry frequency [#retry-frequency]
Smake has implemented a timeout period of 10 seconds and a retry period for webhook subscriptions.
Smake waits for a response to each webhook request for ten seconds. If no response is received or an error is returned, Smake will attempt to establish the connection 50 times within the next 48 hours.
To avoid timeouts and errors, you should consider postponing app processing until the webhook response has been successfully sent.
## Webhooks and API versions [#webhooks-and-api-versions]
The structure of the payload an event sent in a webhook is dictated by the API Version you set in the
app at the time of the event's occurrence. For example, if your app is set to an older
API version, such as `2017-09-25`, and you change the API version for a specific request via versioning,
the payload generated and sent to your endpoint is still based upon the `2017-09-25` API version.
## Signatures [#signatures]
Smake can optionally sign the webhook events it sends to your endpoints. We do so by including a
signature in each event’s `X-Signature` header, when your secret token is set. Smake uses it to create a hash
signature with each payload. This allows you to validate that the events were sent by Smake, not by a third party.
### Validating payloads [#validating-payloads]
Smake uses an HMAC hexdigest to compute the hash, so you could change your server to look a little like this:
```php
class WebhookController extends Controller
{
public function handleVariantDesigned(Request $request)
{
$payload = json_decode($request->getContent(), true);
if (! $this->hasValidSignature($request, $payload)) {
// Handle invalid Signature
return response()->setStatusCode(422);
}
// Handle Payload
return response()->setStatusCode(200);
}
protected function hasValidSignature(Request $request, string $payload): bool
{
$token = config('my-secret-token');
return $request->header('X-Signature') === 'sha1='.hash_hmac('sha1', $payload, $token);
}
}
```
## Best Practice [#best-practice]
### Acknowledge events immediately [#acknowledge-events-immediately]
If your webhook script performs complex logic, or makes network calls, it’s possible that the script would time out
before Smake sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by
returning a `2xx` status code) is separate of any other logic you do for that event.
### Handle duplicate events [#handle-duplicate-events]
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against
duplicated event receipts by making your event processing idempotent. One way of doing this is logging the
events you’ve processed, and then not processing already-logged events.
### Order Events [#order-events]
Smake does not guarantee delivery of events in the order in which they are generated.
You should handle this accordingly.
# Additional Instructions (/docs/checkout/2021-02-23/endpoints/additional-instructions)
The endpoint lists all available additional instructions that can be transferred
in the endpoint [variants/\{id}/design](./variants#content-design).
## List [#list]
Returns a collection of additional instructions.
### Filtering [#filtering]
You can filter your results as follows:
#### List additional instructions for specified id(s) [#list-additional-instructions-for-specified-ids]
* `/additional-instructions?filter[id]=1`
* `/additional-instructions?filter[id]=1,2,3`
#### List additional instructions for specified name [#list-additional-instructions-for-specified-name]
* `/additional-instructions?filter[name]=qui`
#### List additional instructions for a specified origin code [#list-additional-instructions-for-a-specified-origin-code]
* `/additional-instructions?filter[type]=product`
* `/additional-instructions?filter[type]=shipping`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example [#example]
Request
```json
GET /additional-instructions HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"name": "Apply Marvel stickers",
"price": 8.0,
"type": "product"
},
{
"id": 2,
"name": "Sticker on the package",
"price": 10.2,
"type": "shipping"
}
...
],
"links": {
"first": "https://api.smake.io/v2/additional-instructions?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/additional-instructions?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/additional-instructions",
"per_page": 25,
"to": 25
}
}
```
## Get [#get]
Returns the additional instruction with the `id` = **x**.
### Example [#example-1]
Request
```json
GET /additional-instructions/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"name": "Apply Marvel stickers",
"price": 8.0,
"type": "product"
}
```
# Checkouts (/docs/checkout/2021-02-23/endpoints/checkouts)
You have to pass through the checkout process to place an order with your product variants.
## Create [#create]
### Attribute [#attribute]
| Field | Type | Description | Required |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| external\_reference | string | External reference may be use to specifies where an order originally came from. | |
| external\_identifier | string | External identifier may be used to reference an order from another external system. We do not check for uniqueness! | |
| cost\_centre | string | Cost centre will be printed on packing slip. | |
| email | string | E-mail. RFC3696/5321 compliant | yes |
| items | array | Items. An array of [Item Objects](#content-item-object) | yes |
| shipping\_address | object | Shipping address. [Address Object](#content-address-object) | yes |
| billing\_address | object | Billing address. If you do not specify this address, it corresponds to the shipping address. [Address Object](#content-address-object) | |
| whitelabel\_address | object | White label / Sender address. [Address Object](#content-address-object) | |
### Item Object [#item-object]
[Back to Attributes](#content-attribute)
| Field | Type | Description | Required |
| ----------- | ------- | -------------------------- | -------- |
| variant\_id | integer | Id of the product variant | yes |
| quantity | integer | The quantity to be ordered | yes |
### Address Object [#address-object]
[Back to Attributes](#content-attribute)
| Field | Type | Description | Required |
| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| company | string | Company | |
| first\_name | string | First name | yes |
| last\_name | string | Last name | yes |
| street1 | string | First street line. Limited to **35** characters | yes |
| street2 | string | Second street line. Limited to **35** characters | |
| zip | string | Zip code | yes |
| city | string | City | yes |
| province\_code | string | Requires a one or three-digit code. Example: 'AL' (Alabama) or 'QLD' (Queensland) | Only for shipments to the United States, Canada, Australia and Israel. |
| country\_code | ISO 3166-1-alpha-2 code (ISO 2 country code) | Example: 'US' or 'DE'. All accepted values can be found on the [Official ISO website](http://www.iso.org/). | yes |
| email | string | Contact person's e-mail address, RFC3696/5321 compliant. | yes |
| phone | string | So that, for example, the parcel service can call the address/dispatcher of the parcel in case of problems with shipping. | yes |
| vat\_in | string | Sales tax | |
### Example [#example]
Request
```json
POST /checkouts HTTP/1.1
{
"email": "customer@example.com",
"cost_centre": "lorem 1234",
"items": [
{
"variant_id": 1,
"quantity": 1
}
],
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"street1": "123 Main St",
"zip": "12345",
"city": "Anytown",
"country_code": "DE",
"province_code": "NW",
"phone": "12345 67890",
"email": "shipping@example.com"
}
}
```
Response
```json
{
"id": 1,
"is_test": true,
"external_identifier": null,
"external_reference": null,
"cost_centre": "lorem 1234",
"state": "incompleted",
"customer_locale": "en",
"currency": "EUR",
"total": 123.75,
"subtotal": 103.99,
"total_tax": 19.76,
"total_items_price": 123.75,
"shipping_line": [],
"created_at": "2017-09-29T09:14:11+00:00",
"updated_at": "2017-09-29T09:14:11+00:00",
"cancelled_at": null,
"items": [
{
"id": 75,
"quantity": 1,
"total": 123.75,
"price": 103.99,
"total_tax": 19.76,
"tax_rate": 19,
"variant": {
"id": 1,
"total": 123.75,
"price": 103.99,
"tax": 19.76,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "LightPink"
},
{
"name": "size",
"value": "M"
}
],
"origin": {
"code": "2032095419441"
},
"media_id": 81,
"views": [],
"state": "finished",
"created_at": "2017-09-27T10:10:33+00:00",
"updated_at": "2017-09-27T10:10:34+00:00"
},
"created_at": "2017-09-29T09:14:11+00:00",
"updated_at": "2017-09-29T09:14:11+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 98,
"first_name": null,
"last_name": null,
"email": "customer@example.com",
"phone": null,
"addresses": [],
"default_address": null,
"created_at": "2017-09-29T09:14:11+00:00",
"updated_at": "2017-09-29T09:14:11+00:00"
},
"shipping_address": {
"id": 190,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "shipping@example.com",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-29T09:14:11+00:00",
"updated_at": "2017-09-29T09:14:11+00:00"
},
"billing_address": {
"id": 191,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "shipping@example.com",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-29T09:14:11+00:00",
"updated_at": "2017-09-29T09:14:11+00:00"
},
"whitelabel_address": null,
"transactions": [],
"fulfillments": [],
"id_tags": []
}
```
## Shipping Rates [#shipping-rates]
To be able to send the order, it is necessary to query the shipping rates and select the appropriate shipping method.
This happens asynchronously and you have to use [Polling](../basic/polling) or [Webhooks](../basic/webhooks).
If the response is `200 OK`, you have to update the `shipping_line` in the checkout with the desired shipment `handle`.
### Example [#example-1]
Request
```json
GET /checkouts/1/shipping-rates HTTP/1.1
```
Response
```json
HTTP/1.1 202 Accepted
Location https://api.smake.io/jobs/1
```
Request as soon as the task is completed.
```json
GET /checkouts/1/shipping-rates HTTP/1.1
```
Response
```json
{
"data": [
{
"is_test": true,
"order_id": 1,
"handle": "pickup",
"title": "Abholung",
"price": 22
}
],
"links": {
"first": "/?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "/",
"per_page": 15,
"to": 1
}
}
```
Webhook Payloads always have all shipping rates, so the pagination is not available.
## Update [#update]
During the process it is possible to update the checkout.
If you change `shipping_address` afterwards, you have to request the shipping ratess again
and update the `shipping_line`.
### Examples [#examples]
Request to update the items
```json
PUT /checkouts/1 HTTP/1.1
{
"items": [
{
"variant_id": 3,
"quantity": 1
},
{
"variant_id": 4,
"quantity": 5
}
]
}
```
Response
```json
{
...
"items": [
{
"id": 77,
"quantity": 1,
...
"variant": {
"id": 3,
...
},
},
{
"id": 78,
"quantity": 5,
...
"variant": {
"id": 4,
...
},
}
],
...
}
```
Request to update the shipping\_line
```json
PUT /checkouts/1 HTTP/1.1
{
"shipping": {
"handle": "pickup"
}
}
```
Response
```json
{
...
"shipping_line": {
"title": "Pickup",
"price": 22.06,
"total": 26.25,
"tax": 4.19
},
...
}
```
## Complete [#complete]
To complete the purchase, the `payment.handle` must be transferred. The `payment.handle` parameter accepts all handles that are
listed within endpoint [payment-methods](./payment-methods).
You can then use the [orders](./orders) endpoint to list and filter your orders.
### Example [#example-2]
Request to complete a checkout
```json
PUT /checkouts/1/complete HTTP/1.1
{
"payment": {
"handle": "invoice",
}
}
```
# Media (/docs/checkout/2021-02-23/endpoints/media)
Under Media you can store image files for different areas and reuse them several times with reference to the Media Id.
Currently, media ids are required for the following areas:
| Area | Attributes | Description |
| --------------------------------------------- | --------------------- | ---------------------------------- |
| [Design a variant](./variants#content-design) | composite\_media\_id | Product picture with customization |
| [Design a variant](./variants#content-design) | production\_media\_id | Production file for customization |
## Upload [#upload]
The following file formats are currently supported:
| Type | Options |
| -------- | ------------------------------------- |
| JPG/JPEG | RGB, 360dpi recommended |
| PNG | RGB, transparency, 360dpi recommended |
The maximum file size is 20MB.
### Example [#example]
Request
```json
POST /media HTTP/1.1
Content-Type: image/jpeg
Content-Length: 42840
raw content
```
Response
```json
{
"id": 1,
"is_test": true,
"file_name": "39b8196929f742e7bccab01a643b6524.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1/download",
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00"
}
```
***
## List [#list]
Returns a collection of uploaded images.
### Example [#example-1]
Request
```json
GET /media HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1005,
"is_test": true,
"file_name": "39b8196929f742e7bccab01a643b6524.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1005/download",
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00"
},
{
"id": 1006,
"is_test": true,
"file_name": "5d9de455299a4c369fcf719b677cf4cd.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1006/download",
"created_at": "2017-09-28T08:46:21+00:00",
"updated_at": "2017-09-28T08:46:21+00:00"
},
{
"id": 1007,
"is_test": true,
"file_name": "4efd66336f274163b6ef8c34a9c77570.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1007/download",
"created_at": "2017-09-28T08:46:26+00:00",
"updated_at": "2017-09-28T08:46:26+00:00"
},
{
"id": 1008,
"is_test": true,
"file_name": "391f3972c2bd473ba186752555b74cab.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1008/download",
"created_at": "2017-09-28T08:46:27+00:00",
"updated_at": "2017-09-28T08:46:27+00:00"
},
{
"id": 1009,
"is_test": true,
"file_name": "f868b1172fb74d0dbd6877f3e02f3386.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1009/download",
"created_at": "2017-09-28T08:46:28+00:00",
"updated_at": "2017-09-28T08:46:28+00:00"
},
...
],
"links": {
"first": "https://api.smake.io/v2/media?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/media",
"per_page": 25,
"to": 16
}
}
```
***
## Get [#get]
Returns the resource for the uploaded image with `id` = **x**.
### Example [#example-2]
Request
```json
GET /media/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": true,
"file_name": "39b8196929f742e7bccab01a643b6524.jpeg",
"size": 42840,
"mime_type": "image/jpeg",
"download_url": "https://api.smake.io/v2/media/1/download",
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00"
}
```
***
## Download [#download]
Returns the image data for the uploaded image with the `id` = **x** as download.
For example, in PHP you can read the `raw content` with `file_get_contents('php://input');`.
### Example [#example-3]
Request
```json
GET /media/1/download HTTP/1.1
```
Response
```json
raw content
```
# Orders (/docs/checkout/2021-02-23/endpoints/orders)
An order is created when the checkout process is complete.
### Expandable Objects [#expandable-objects]
The following ressources can be expanded by adding the mentioned query paramters to your request
#### Expand Order Type [#expand-order-type]
`{endpoint}?expand=orderType`
See: [Expanding Objects](../basic/expanding-objects)
## List [#list]
Returns a collection of created orders.
### Filtering [#filtering]
You can filter your results as follows:
#### List orders for specified id(s) [#list-orders-for-specified-ids]
* `/orders?filter[id]=1`
* `/orders?filter[id]=1,2,3`
#### List orders for specified state [#list-orders-for-specified-state]
* `/orders?filter[state]=cancelled`
* `/orders?filter[state]=delivered`
#### List orders for specified external identifier [#list-orders-for-specified-external-identifier]
* `/orders?filter[external_identifier]=organic`
#### List orders for specified external reference [#list-orders-for-specified-external-reference]
* `/orders?filter[external_reference]=143000`
#### List orders with an ID greater than the specified ID [#list-orders-with-an-id-greater-than-the-specified-id]
* `/orders?filter[since_id]=1`
* `/orders?filter[since_id]=2`
#### List orders for a given date, only resources created after the provided date will be returned [#list-orders-for-a-given-date-only-resources-created-after-the-provided-date-will-be-returned]
* `/orders?filter[created_at_min]=2017-09-27`
#### List orders for a given date, only resources created before the provided date will be returned [#list-orders-for-a-given-date-only-resources-created-before-the-provided-date-will-be-returned]
* `/orders?filter[created_at_max]=2017-11-15`
#### List orders for a given date, only resources updated after the provided date will be returned [#list-orders-for-a-given-date-only-resources-updated-after-the-provided-date-will-be-returned]
* `/orders?filter[updated_at_min]=2017-09-27`
#### List orders for a given date, only resources updated before the provided date will be returned [#list-orders-for-a-given-date-only-resources-updated-before-the-provided-date-will-be-returned]
* `/orders?filter[updated_at_max]=2017-09-27`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example [#example]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"order_type": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"cost_centre": "lorem 12345",
"state": "delivered",
"customer_locale": "en",
"currency": "EUR",
"total": 57.20,
"subtotal": 52.00,
"total_tax": 5.20,
"total_items_price": 52.80,
"shipping_total": 4.40,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:11:03+00:00",
"cancelled_at": null,
"ordered_at": "2017-09-27T10:11:03+00:00",
"items": [
{
"id": 1,
"quantity": 4,
"total": 52.80,
"price": 12.00,
"total_tax": 4.80,
"tax_rate": 10,
"variant": {
"id": 27,
"total": 13.20,
"price": 12.00,
"tax": 1.20,
"tax_rate": 10,
"attributes": [
{
"name": "color",
"value": "Khaki"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "4490824589755"
},
"media_id": 251,
"views": [],
"created_at": "2017-09-27T10:10:38+00:00",
"updated_at": "2017-09-27T10:10:38+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 40,
"first_name": "John",
"last_name": "Doe",
"email": "John@example.com",
"phone": "12345 67890",
"addresses": [],
"default_address": {
"id": 122,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.com",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:11:01+00:00",
"updated_at": "2017-09-27T10:11:01+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"shipping_address": {
"id": 45,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "John",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "john@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"billing_address": {
"id": 44,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "john@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"whitelabel_address": null,
"transactions": [
{
"amount": 57.20,
"title": "Invoice"
}
],
"fulfillments": [
{
"id": 1,
"tracking_number": "2229446017085",
"order": 1,
"parcels": [
[
1
]
],
"created_at": "2021-02-24T11:04:46+01:00",
"updated_at": "2021-02-25T11:35:50+01:00"
}
],
"id_tags": [
{
"id": 1,
"order_item_id": 1,
"current_state": "Goods booked in",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 2,
"order_item_id": 1,
"current_state": "Released to production stage",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 3,
"order_item_id": 1,
"current_state": "Shipped",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 4,
"order_item_id": 1,
"current_state": "Scanned on machine (DTG)",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
]
},
{
"id": 2,
"order_type": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "dicta",
"coste_centre": "ipsum 8765",
"state": "incompleted",
"customer_locale": "en",
"currency": "EUR",
"total": 28.60,
"subtotal": 26.00,
"total_tax": 2.60,
"total_items_price": 22.00,
"shipping_total": 6.60,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null,
"ordered_at": "2017-09-27T10:11:03+00:00",
"items": [
{
"id": 2,
"quantity": 1,
"total": 22.00,
"price": 20.00,
"total_tax": 2.00,
"tax_rate": 10,
"variant": {
"id": 53,
"total": 22.00,
"price": 20.00,
"tax": 2.00,
"tax_rate": 10,
"attributes": [
{
"name": "color",
"value": "LightCyan"
},
{
"name": "size",
"value": "S"
}
],
"origin": {
"code": "0729845433827"
},
"media_id": 436,
"views": [],
"created_at": "2017-09-27T10:10:43+00:00",
"updated_at": "2017-09-27T10:10:43+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 41,
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "12345 67890",
"addresses": [],
"default_address": {
"id": 124,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.org",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:11:01+00:00",
"updated_at": "2017-09-27T10:11:01+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"shipping_address": {
"id": 47,
"default": true,
"company": "MyComapny",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.org",
"province_code": "BW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"billing_address": {
"id": 46,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.org",
"province_code": "BY",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"whitelabel_address": null,
"transactions": [
{
"amount": 28.60,
"title": "Invoice"
}
],
"fulfillments": [
{
"id": 1,
"tracking_number": "2229446017085",
"order": 1,
"parcels": [
[
1
]
],
"created_at": "2021-02-24T11:04:46+01:00",
"updated_at": "2021-02-25T11:35:50+01:00"
}
],
"id_tags": [
{
"id": 5,
"order_item_id": 2,
"current_state": "Production stages combined (stitching)",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
]
}
...
],
"links": {
"first": "https://api.smake.io/v2/orders?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/orders?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/orders",
"per_page": 25,
"to": 25
}
}
```
## Get [#get]
Returns the order with `id` = **x**.
### Example [#example-1]
Request
```json
GET /orders/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"order_type": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"cost_centre": "lorem 1234",
"state": "delivered",
"customer_locale": "en",
"currency": "EUR",
"total": 57.20,
"subtotal": 52.00,
"total_tax": 5.20,
"total_items_price": 52.80,
"shipping_total": 4.40,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:11:03+00:00",
"cancelled_at": null,
"ordered_at": "2017-09-27T10:11:03+00:00",
"items": [
{
"id": 1,
"quantity": 4,
"total": 52.80,
"price": 12.00,
"total_tax": 4.80,
"tax_rate": 10,
"variant": {
"id": 27,
"total": 13.20,
"price": 12.00,
"tax": 1.20,
"tax_rate": 10,
"attributes": [
{
"name": "color",
"value": "Khaki"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "4490824589755"
},
"media_id": 251,
"views": [],
"created_at": "2017-09-27T10:10:38+00:00",
"updated_at": "2017-09-27T10:10:38+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 40,
"first_name": "John",
"last_name": "Doe",
"email": "John@example.com",
"phone": "12345 67890",
"addresses": [],
"default_address": {
"id": 122,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.com",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:11:01+00:00",
"updated_at": "2017-09-27T10:11:01+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"shipping_address": {
"id": 45,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"billing_address": {
"id": 44,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"whitelabel_address": null,
"transactions": [
{
"amount": 57.20,
"title": "Invoice"
}
],
"fulfillments": [
{
"id": 1,
"tracking_number": "2229446017085",
"order": 1,
"parcels": [
[
1
]
],
"created_at": "2021-02-24T11:04:46+01:00",
"updated_at": "2021-02-25T11:35:50+01:00"
}
],
"id_tags": [
{
"id": 1,
"order_item_id": 1,
"current_state": "Goods booked in",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 2,
"order_item_id": 1,
"current_state": "Released to production stage",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 3,
"order_item_id": 1,
"current_state": "Shipped",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 4,
"order_item_id": 1,
"current_state": "Scanned on machine (DTG)",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
]
}
```
***
## Cancel [#cancel]
You can cancel an already placed order by executing the following request.
Depending on the cancellation setting it may be that an order can no longer be canceled. In
this case an API exception is thrown.
### Example [#example-2]
Request
```json
PUT /orders/1/cancel HTTP/1.1
```
Response
```json
{
"id": 1,
"order_type": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"cost_centre": "lorem 1234",
"state": "delivered",
"customer_locale": "en",
"currency": "EUR",
"total": 57.20,
"subtotal": 52.00,
"total_tax": 5.20,
"total_items_price": 52.80,
"shipping_total": 4.40,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:11:03+00:00",
"cancelled_at": null,
"ordered_at": "2017-09-27T10:11:03+00:00",
"items": [
{
"id": 1,
"quantity": 4,
"total": 52.80,
"price": 12.00,
"total_tax": 4.80,
"tax_rate": 10,
"variant": {
"id": 27,
"total": 13.20,
"price": 12.00,
"tax": 1.20,
"tax_rate": 10,
"attributes": [
{
"name": "color",
"value": "Khaki"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "4490824589755"
},
"media_id": 251,
"views": [],
"created_at": "2017-09-27T10:10:38+00:00",
"updated_at": "2017-09-27T10:10:38+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00",
"cancelled_at": null
}
],
"customer": {
"id": 40,
"first_name": "John",
"last_name": "Doe",
"email": "John@example.com",
"phone": "12345 67890",
"addresses": [],
"default_address": {
"id": 122,
"default": true,
"company": null,
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.com",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:11:01+00:00",
"updated_at": "2017-09-27T10:11:01+00:00"
},
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"shipping_address": {
"id": 45,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"billing_address": {
"id": 44,
"default": true,
"company": "MyCompany",
"first_name": "John",
"last_name": "Doe",
"city": "Anytown",
"street1": "123 Main St",
"street2": null,
"zip": "12345",
"phone": "12345 67890",
"email": "John@example.net",
"province_code": "NW",
"country_code": "DE",
"vat_in": null,
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
"whitelabel_address": null,
"transactions": [
{
"amount": 57.20,
"title": "Invoice"
}
],
"fulfillments": [
{
"id": 1,
"tracking_number": "2229446017085",
"order": 1,
"parcels": [
[
1
]
],
"created_at": "2021-02-24T11:04:46+01:00",
"updated_at": "2021-02-25T11:35:50+01:00"
}
],
"id_tags": [
{
"id": 1,
"order_item_id": 1,
"current_state": "Goods booked in",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 2,
"order_item_id": 1,
"current_state": "Released to production stage",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 3,
"order_item_id": 1,
"current_state": "Shipped",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
},
{
"id": 4,
"order_item_id": 1,
"current_state": "Scanned on machine (DTG)",
"created_at": "2017-09-27T10:10:59+00:00",
"updated_at": "2017-09-27T10:10:59+00:00"
}
]
}
```
# Payment methods (/docs/checkout/2021-02-23/endpoints/payment-methods)
The endpoint lists all available payment methods that can be transferred in
the endpoint [checkouts/1/complete](./checkouts#content-complete).
## List [#list]
Returns a collection of payment methods.
### Filtering [#filtering]
You can filter your results as follows:
#### List payment methods for specified name(s) [#list-payment-methods-for-specified-names]
* `/payment-methods?filter[name]=Invoice`
* `/payment-methods?filter[name]=Invoice,Pickup`
#### List payment methods for specified handle(s) [#list-payment-methods-for-specified-handles]
* `/payment-methods?filter[handle]=invoice`
* `/payment-methods?filter[handle]=invoice,pickup`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example [#example]
Request
```json
GET /payment-methods HTTP/1.1
```
Response
```json
{
"data": [
{
"name": "Invoice",
"handle": "invoice",
},
{
"name": "Pickup",
"handle": "pickup",
}
...
],
"links": {
"first": "https://api.smake.io/v2/payment-methods?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/payment-methods?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/payment-methods",
"per_page": 25,
"to": 25
}
}
```
# Products (/docs/checkout/2021-02-23/endpoints/products)
The Products endpoint lets you list all products available.
Variants Attribute is expandable. See: [Expanding Objects](../basic/expanding-objects)
## List [#list]
Returns a collection of products.
### Filtering [#filtering]
You can filter your results as follows:
#### List products for specified id(s) [#list-products-for-specified-ids]
* `/products?filter[id]=1`
* `/products?filter[id]=1,2,3`
#### List products for specified title [#list-products-for-specified-title]
* `/products?filter[title]=qui`
#### List products for a specified origin code [#list-products-for-a-specified-origin-code]
* `/products?filter[variants.origin.sku]=58975`
#### List products for a specified origin manufacturer\_number [#list-products-for-a-specified-origin-manufacturer_number]
* `/products?filter[origin.manufacturer_number]=X01234`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example [#example]
Request
```json
GET /products HTTP/1.1
```
Response
```json
{
"data": [
{
"is_test": false,
"id": 1,
"title": "qui ut nemo",
"description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:48+00:00",
"variants": [
90,
92,
94,
]
},
{
"is_test": false,
"id": 30,
"title": "ut",
"description": "Et voluptatem quas neque praesentium qui harum. Ea occaecati perferendis inventore tempore nemo. Nobis perferendis voluptas sed tempore at.",
"created_at": "2017-11-15T08:07:51+00:00",
"updated_at": "2017-11-15T08:07:51+00:00",
"variants": [
96,
98,
100
102,
104
]
}
...
],
"links": {
"first": "https://api.smake.io/v2/products?page=1",
"last": null,
"prev": null,
"next": "https://api.smake.io/v2/products?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/products",
"per_page": 25,
"to": 25
}
}
```
## Get [#get]
Returns the product with the `id` = **x**.
### Example [#example-1]
Request
```json
GET /products/1 HTTP/1.1
```
Response
```json
{
"is_test": false,
"id": 1,
"title": "qui ut nemo",
"description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:48+00:00",
"variants": [
90,
92,
94,
]
}
```
# Variants (/docs/checkout/2021-02-23/endpoints/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 [#list]
Returns a collection of variants.
### Filtering [#filtering]
You can filter your results as follows:
#### List variants for specified id(s) [#list-variants-for-specified-ids]
* `/variants?filter[id]=1`
* `/variants?filter[id]=1,2,3`
#### List variants for a specified origin code [#list-variants-for-a-specified-origin-code]
The filtering is not an exact search, it looks for a part in the attribute value.
* `/variants?filter[origin.sku]=42443`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example [#example]
Request
```json
GET /variants HTTP/1.1
```
Response
```json
{
"data": [
{
"is_test": false,
"id": 6,
"total": 97.37,
"price": 91,
"tax": 6.37,
"tax_rate": 7,
"attributes": [
{
"name": "color",
"value": "CadetBlue"
},
{
"name": "size",
"value": "M"
}
],
"origin": {
"code": "0441837446362"
},
"media_id": 150,
"views": {
"back": {
"media_id": 151,
"composite_media_id": 155,
"customizations": []
},
"left": {
"media_id": 152,
"composite_media_id": 156,
"customizations": []
},
"front": {
"media_id": 150,
"composite_media_id": 154,
"customizations": []
},
"right": {
"media_id": 153,
"composite_media_id": 157,
"customizations": []
}
},
"created_at": "2018-02-21T10:49:41+00:00",
"updated_at": "2018-02-21T10:49:41+00:00"
},
{
"is_test": false,
"id": 10,
"total": 191.59,
"price": 161,
"tax": 30.59,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "DarkSalmon"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "2673696529018"
},
"media_id": 165,
"views": {
"back": {
"composite_media_id": 167,
"customizations": []
},
"left": {
"composite_media_id": 168,
"customizations": []
},
"front": {
"composite_media_id": 166,
"customizations": []
},
"right": {
"composite_media_id": 169,
"customizations": []
}
},
"created_at": "2018-02-21T10:49:42+00:00",
"updated_at": "2018-02-21T10:49:42+00:00"
},
{
"is_test": false,
"id": 11,
"total": 152.88,
"price": 128.47,
"tax": 24.41,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "Navy"
},
{
"name": "size",
"value": "S"
}
],
"origin": {
"code": "4244363429184"
},
"media_id": 180,
"views": {
"back": {
"composite_media_id": 182,
"customizations": []
},
"left": {
"composite_media_id": 183,
"customizations": []
},
"front": {
"composite_media_id": 181,
"customizations": []
},
"right": {
"composite_media_id": 184,
"customizations": []
}
},
"created_at": "2018-02-21T10:49:42+00:00",
"updated_at": "2018-02-21T10:49:42+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 [#get]
Returns the product variant with the `id` = **x**.
### Example [#example-1]
Request
```json
GET /variants/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": true,
"total": 259.98,
"price": 218.47,
"tax": 41.51,
"tax_rate": 19,
"attributes": [
{
"name": "color",
"value": "LightYellow"
},
{
"name": "size",
"value": "XL"
}
],
"origin": {
"code": "0635579894134"
},
"media_id": 1094,
"views": {
"back": {
"composite_media_id": 10680,
"customizations": [
{
"type": "dtg",
"production_media_id": 1,
"preview_media_id": 1001,
"dimension": {
"width": 100.55,
"height": 200.66
}
},
{
"type": "dtg",
"production_media_id": 2,
"preview_media_id": 1002,
"dimension": {
"width": 100.66,
"height": 200.12
}
}
]
},
"front": {
"composite_media_id": 1093,
"customizations": [
{
"type": "dtg",
"production_media_id": 2,
"preview_media_id": 1003,
"dimension": {
"width": 100.55,
"height": 200.66
}
},
{
"type": "dtg",
"production_media_id": 2,
"preview_media_id": 1004,
"dimension": {
"width": 1001.55,
"height": 2000.66
}
},
{
"type": "dtg",
"production_media_id": 2,
"preview_media_id": 1095,
"dimension": {
"width": 100.55,
"height": 200.66
}
},
{
"type": "dtg",
"production_media_id": 2,
"preview_media_id": 1096,
"dimension": {
"width": 1001.55,
"height": 2000.66
}
}
]
}
},
"created_at": "2017-09-28T14:48:05+00:00",
"updated_at": "2017-09-28T14:48:05+00:00"
}
```
## Design [#design]
When you design a product variant, this happens asynchronously and you have to
use [Polling](../basic/polling) or [Webhooks](../basic/webhooks). A new product variant is created implicitly.
Therefore, you will already receive the new product variant ID in the header for later reference.
It is not possible to order this product variant before.
Designing a product variant is made possible by placing customizations on the corresponding view (e. g. front or back).
| Field | Type | Description | Required |
| ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| views | object | Contains the views on which customizations are placed. Allowed are `front`, `back`, `left` and `right`. [Views Object](#content-views-object) | yes |
### Views Object [#views-object]
| Field | Type | Description | Required |
| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| front.composite\_media\_id | integer | The media id that represents the product image with customizations. See [Media](./media) | yes |
| front.customizations | array | Contains all customizations to be placed for the view. An array of [Customizations Objects](#content-customization-object) | yes |
| front.additional\_instructions | array | Contains all additional instructions to be placed for the view. An array of [Additional Instruction Objects](#content-additional-instruction-object) | no |
### Customization Object [#customization-object]
| Field | Type | Description | Required |
| --------------------- | ------- | ------------------------------------------------------------------------------------------ | -------- |
| type | string | Processing format of the customizations. Allowed is `dtg` | yes |
| production\_media\_id | integer | The media id that contains the production file of the customizations. See [Media](./media) | yes |
| dimension | object | [Dimension Object](#content-dimension-object) | yes |
### Dimension Object [#dimension-object]
| Field | Type | Description | Required |
| ------ | ----- | --------------------------------------------------- | -------- |
| width | float | The width of the customization in millimetres (mm) | yes |
| height | float | The height of the customization in millimetres (mm) | yes |
### Additional Instruction Object [#additional-instruction-object]
| Field | Type | Description | Required |
| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- |
| id | integer | The additional instruction id that represents the additional instruction. See [Additional Instructions](./additional-instructions) | yes |
### Example [#example-2]
Request
```json
POST /variants/136/design HTTP/1.1
{
"views": {
"front": {
"composite_media_id": 1,
"customizations": [
{
"type": "dtg",
"production_media_id": 2,
"dimension": {
"width": 100.55,
"height": 200.66
}
},
{
"type": "dtg",
"production_media_id": 2,
"dimension": {
"width": 1001.55,
"height": 2000.66
}
}
]
"additional_instructions": [
{
"id": 1
}
]
}
}
}
```
Response
The `X-Identifier` is the new generated product variant ID for later reference.
```json
HTTP/1.1 202 Accepted
Location https://api.smake.io/jobs/1
X-Identifier: 137
```
# Webhooks (/docs/checkout/2021-02-23/endpoints/webhooks)
You can configure webhook endpoints via the API to be notified about events that happen in Smake.
You can create up to 10 webhooks per event.
## Available Events [#available-events]
Currently, these are all events you can listen to:
* `order.shipped`
* `order.cancelled`
* `shipping-rate.calculated`
* `variant.designed`
* `id-tag.updated`
## List [#list]
Request
```json
GET /webhooks HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"is_test": true,
"url": "https://requestb.in/xjggz4xj",
"event_types": [
{
"id": 1,
"name": "order.shipped"
}
]
},
{
"id": 2,
"is_test": true,
"url": "https://requestb.in/1hd29kc1",
"event_types": [
{
"id": 1,
"name": "order.shipped"
}
]
}
],
"links": {
"first": "https://api.smake.io/v2/webhooks?page=1",
"last": "https://api.smake.io/v2/webhooks?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/webhooks",
"per_page": 25,
"to": 2,
}
}
```
## Get [#get]
Request
```json
GET /webhooks/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": true,
"url": "https://requestb.in/xjggz4xj",
"event_types": [
{
"id": 1,
"name": "order.shipped"
}
]
}
```
## Create [#create]
### Attributes [#attributes]
| Field | Type | Description | Required |
| ------------ | ------ | ------------------------------------------------------------------------------ | -------- |
| url | string | The URL to listen for incoming POST notification containing event information. | yes |
| token | string | A token to secure your url | |
| event\_types | array | An array of [Event-Type Objects](#content-item-type-object) | yes |
### Event-Type Object [#event-type-object]
[Back to Attributes](#content-attribute)
| Field | Type | Description | Required |
| ----- | ------ | ----------- | -------- |
| name | string | name | yes |
Request
```json
POST /webhooks HTTP/1.1
{
"url": "https://requestb.in/1hd29kc1",
"token": "my-secret-token",
"event_types": [
{
"name": "order.shipped"
}
]
}
```
Response
```json
{
"id": 2,
"is_test": true,
"url": "https://requestb.in/1hd29kc1",
"event_types": [
{
"id": 1,
"name": "order.shipped"
}
]
}
```
## Update [#update]
Request
```json
PUT /webhooks/1 HTTP/1.1
{
"url": "http://example.com"
}
```
Response
```json
{
"id": 1,
"is_test": true,
"url": "http://example.com",
"event_types": [
{
"id": 1,
"name": "order.shipped"
}
]
}
```
## Delete [#delete]
Request
```json
DELETE /webhooks/1 HTTP/1.1
```
# Changelog (/docs/checkout/2021-02-23/references/changelog)
The changelog is a list of backwards-incompatible updates in the API. As described before, new additions and forwards-compatible changes don’t need a new API version and will not appear in this list.
## 2021-02-23 [#2021-02-23]
* The `fulfillments` object has now all `parcels` objects. See in the endpoint [orders](../endpoints/orders).
* The `fulfillments.order_id` was changed to an `order` object. See in the endpoint [orders](../endpoints/orders).
## 2020-01-17 [#2020-01-17]
* The `project_name` parameter has changed to `external_reference` in the endpoint [checkouts](../endpoints/checkouts#content-create).
* The `project_name` in the order resource within the endpoints [checkouts](../endpoints/checkouts) and
[orders](../endpoints/orders) has changed to `external_reference`.
## 2019-10-01 [#2019-10-01]
* The `payment.amount` parameter must not be passed in the endpoint [checkouts/complete](../endpoints/checkouts#content-complete).
* The `payment.handle` parameter in endpoint [checkouts/complete](../endpoints/checkouts#content-complete) now accepts all handles that are listed within endpoint [payment-methods](../endpoints/payment-methods).
## 2019-02-28 [#2019-02-28]
* `include` parameter is replaced by the `expand` parameter.
* On the products endpoint the variant resource initially only shows `ids`. You have to use `?expand=variants` to show the complete resource
* Removed `current_state` in `id_tags`
## 2018-12-06 [#2018-12-06]
* The variant resource is not automatically loaded on the products endpoint. You have to you use `?include=variants`
* Pagination simplified.
* Removed `meta.last_page` and `meta.total` attribute.
* `links.last` will always be `null`.
* `shipping_line` attribute removed in orders endpoint and added a `shipping_total` attribute
* Added `state` and `order_id` to `id_tags`
## 2017-09-25 [#2017-09-25]
* Initial Release
# Versioning (/docs/checkout/2021-02-23/references/versioning)
Smake Api uses versioning to roll out backwards-incompatible changes over time.
## Backwards-compatible changes [#backwards-compatible-changes]
Smake considers the following changes to be backwards-compatible:
* Adding new API resources.
* Adding new optional request parameters to existing API methods.
* Adding new attributes to existing API responses.
* Changing the order of attributes in existing API responses.
* Adding new event types.
## About Versioning [#about-versioning]
The API version will control the API and webhook behaviors, such as parameters accepted in requests, and
response properties.
A new version of the API is released when backwards-incompatible changes are made to the API. To avoid
breaking your code, we will never force you to upgrade until you’re ready.
We will be releasing backwards-compatible changes without introducing new versions. Your code will be able
to handle these changes no matter what version it’s on.
## Upgrade your Api Version [#upgrade-your-api-version]
We recommend staying up-to-date with the current API version to take advantage of latest
improvements to the Smake API.
To see your current version and upgrade to the latest, visit the API Page on your app.
Versioning of the Smake API will be released as dates, displayed as: `YYYY-MM-DD`
## Test Before Upgrading [#test-before-upgrading]
To test your code under a different API version before committing the change, you can set the API version
on a specific request by setting a header with the version you are testing. The version will be set for
subsequent requests until it’s changed back.
Users can only upgrade their API to the latest version. Once you’ve upgraded your API version, you cannot
roll back to an earlier version. Please make sure to test thoroughly before doing so.
## Example [#example]
```json
GET /products HTTP/1.1
X-Api-Version: 2018-12-06
```
# Authentication (/docs/checkout/2021-02-23/setup/authentication)
In order to use the API, you must authenticate **each request** by including your API Token as a bearer token value:
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
```
You must replace `API_TOKEN_HERE` with your personal API Token.
# Headers (/docs/checkout/2021-02-23/setup/headers)
The API only supports the data format **JSON**. Therefore, make sure you have the following headers
set on **each request**.
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
Accept: application/json
Content-Type: application/json
```
# Test Mode (/docs/checkout/2021-02-23/setup/test-mode)
First you will receive a test application which works similar to your later live application.
To make the API as explorable as possible, you will receive a test and a live token. There is no **switch** for
changing between them, just use the appropriate token to perform a live or test request.
Requests made within a test application never creates real orders and cause no costs.
| Field | Type | Description |
| -------- | ------- | ------------------------------------------------------------------------------------ |
| is\_test | boolean | Flag indicating whether the resource exists in live application or test application. |
```json
{
"id": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"state": "delivered",
"customer_locale": "en",
"currency": "EUR",
...
}
```
# Batch-Endpoints (/docs/checkout/2022-02-01/basic/batch-filtering)
You can search within a collection using the `filter`-field.
## URL Syntax [#url-syntax]
### GET Method [#get-method]
```json
GET /resources?filter[field]=value HTTP/1.1
```
### Other Methods [#other-methods]
```json
POST, UPDATE, PATCH, DELETE /resources HTTP/1.1
```
Request
```json
{
"filter": {
"field": "value",
"nested.filter": "value"
}
}
```
**Not all attributes are searchable**. You will see the actual filterable fields in the endpoint documentation.
# Conditional Request (/docs/checkout/2022-02-01/basic/conditional-request)
All **successful GET requests** responses return an `ETag` header. You can use the `ETag` value to make
subsequent requests to those resources using the `If-None-Match` header. If the resource has not changed,
the server returns a `304 Not Modified`.
Making a conditional request and receiving a 304 response does not count against your [Rate Limit](./rate-limit),
so we encourage you to use it whenever possible.
## Examples [#examples]
### Without If-None-Match Header [#without-if-none-match-header]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
GET /orders HTTP/1.1 200 OK
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
***
### With If-None-Match Header [#with-if-none-match-header]
Request
```json
GET /orders HTTP/1.1
If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
Response
```json
GET /orders HTTP/1.1 304 Not Modified
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
# Expanding Objects (/docs/checkout/2022-02-01/basic/expanding-objects)
Many objects contain the `id` of a related object in their response properties. For example, a Product may
have associated Variant ids. Those objects can be expanded inline with the `expand` request parameter.
Objects that can be expanded are noted in this documentation.
You can expand recursively by specifying nested fields after a dot (`.`). For example,
requesting `items.variant` on an order will expand the variant property into a full variant object.
You can expand multiple objects at once by separating them with a comma.
## Variants Not Expanded [#variants-not-expanded]
Request
```json
GET /products/1 HTTP/1.1
```
Response
```json
{
"is_test": false,
"id": 1,
"title": "qui ut nemo",
"description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
"created_at": "2017-11-15T08:07:48+00:00",
"updated_at": "2017-11-15T08:07:48+00:00",
"variants": [
1,
2,
3,
]
}
```
## Variants Expanded [#variants-expanded]
Request
```json
GET /products/1?expand=variants HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": false,
"title": "T-Shirt 1 not designable",
"description": "Qui excepturi voluptas et esse in quis dolores. At molestiae ipsam provident earum aut omnis inventore non. Ea repellat distinctio laboriosam et mollitia qui.",
"created_at": "2022-04-28T14:31:45+00:00",
"updated_at": "2022-04-28T14:31:45+00:00",
"variants": [
{
"id": 1,
"state": "completed",
"collection_name": "catalogue",
"total": 20.49,
"price": 19.15,
"tax": 1.34,
"tax_rate": 7,
"option_values": [
{
"handle": "S",
"name": "S",
"option_type": {
"handle": "size",
"name": "Size"
}
},
{
"handle": "lime",
"name": "lime",
"option_type": {
"handle": "color",
"name": "Color"
}
}
],
"origin": {
"sku": "production-variant-1",
"external_identifier": "56879425366"
},
"product": 1,
"views": [
{
"handle": "front",
"name": "Front View",
"media": [
{
"id": 38,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-lime.png",
"size": 54738,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/19258c4eeefe4ce98ea37ed670501ba6/view-image-front-lime.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=1b129f611ab0a6a6ec2facfc0a6076297d7f2ab809de7f0047bff475a85111c2",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:08+00:00",
"updated_at": "2022-04-28T14:31:08+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Rear View",
"media": [
{
"id": 39,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-back-lime.png",
"size": 40214,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/6214cdeb5f51499bba015c32e0d29917/view-image-back-lime.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=38d4f41af9a6bb7f4c38dc98831519f64c0f65eba005cab6205a01c800fb496e",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:08+00:00",
"updated_at": "2022-04-28T14:31:08+00:00"
}
],
"customizations": []
},
{
"handle": "left",
"name": "Left View",
"media": [
{
"id": 40,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-left-lime.png",
"size": 33003,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/d238d888cfc3448d9d9b06ef24456a68/view-image-left-lime.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=3e8c53c1ec85803c35bdb90ac3d0e7adbd27fb55bb1cf128bbb064434d72fc67",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:09+00:00",
"updated_at": "2022-04-28T14:31:09+00:00"
}
],
"customizations": []
},
{
"handle": "right",
"name": "Right View",
"media": [
{
"id": 41,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-right-lime.png",
"size": 33411,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/fe2af0c54eaf4fc4b84d3b2e657d12b4/view-image-right-lime.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=d5bb51e9790a204da95869e91b7c081e46ddcddb61a13d06acadad84892529f8",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:09+00:00",
"updated_at": "2022-04-28T14:31:09+00:00"
}
],
"customizations": []
}
],
"failure_message": null,
"created_at": "2022-04-28T14:31:45+00:00",
"updated_at": "2022-04-28T14:31:45+00:00"
},
{
"id": 2,
"state": "completed",
"collection_name": "catalogue",
"total": 201.32,
"price": 169.18,
"tax": 32.14,
"tax_rate": 19,
"option_values": [
{
"handle": "S",
"name": "S",
"option_type": {
"handle": "size",
"name": "Size"
}
},
{
"handle": "cyan",
"name": "cyan",
"option_type": {
"handle": "color",
"name": "Color"
}
}
],
"origin": {
"sku": "production-variant-1",
"external_identifier": "56879425367"
},
"product": 1,
"views": [
{
"handle": "front",
"name": "Front View",
"media": [
{
"id": 42,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-cyan.png",
"size": 54723,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/c0979fbf9dc54db1a4c6ae2a5162a743/view-image-front-cyan.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=db5ec9bc2d528789f554373e4943920c1cbad87344804c90fddb2e372a3ffb11",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:09+00:00",
"updated_at": "2022-04-28T14:31:09+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Rear View",
"media": [
{
"id": 43,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-back-cyan.png",
"size": 40319,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/c156101fa055404990dfb52ede9b576d/view-image-back-cyan.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=86570f7742c678a64856c8f2218d7933733a8bc0d3ff2e3a8b40ceab5733629d",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:10+00:00",
"updated_at": "2022-04-28T14:31:10+00:00"
}
],
"customizations": []
},
{
"handle": "left",
"name": "Left View",
"media": [
{
"id": 44,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-left-cyan.png",
"size": 33012,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/5a12c902143240c892701825ca152027/view-image-left-cyan.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=f3c6e0fc6e3779af8a686f27e3e4f104d217e1eee933b8a287ecdf0ccbce77c9",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:10+00:00",
"updated_at": "2022-04-28T14:31:10+00:00"
}
],
"customizations": []
},
{
"handle": "right",
"name": "Right View",
"media": [
{
"id": 45,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-right-cyan.png",
"size": 33623,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/ef8d0d40eaa841bba7fe51c95e260a30/view-image-right-cyan.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=2e0b60e17d6297d0b8ab2194963cb6a28f77b06c1f4015ce39d6023183f18b69",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:10+00:00",
"updated_at": "2022-04-28T14:31:10+00:00"
}
],
"customizations": []
}
],
"failure_message": null,
"created_at": "2022-04-28T14:31:45+00:00",
"updated_at": "2022-04-28T14:31:45+00:00"
},
{
"id": 3,
"state": "completed",
"collection_name": "catalogue",
"total": 193.89,
"price": 162.93,
"tax": 30.96,
"tax_rate": 19,
"option_values": [
{
"handle": "S",
"name": "S",
"option_type": {
"handle": "size",
"name": "Size"
}
},
{
"handle": "purple",
"name": "purple",
"option_type": {
"handle": "color",
"name": "Color"
}
}
],
"origin": {
"sku": "production-variant-1",
"external_identifier": "56879425368"
},
"product": 1,
"views": [
{
"handle": "front",
"name": "Front View",
"media": [
{
"id": 46,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-front-purple.png",
"size": 54946,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/e7a5042b6e7748579cc3bd405cc3dd80/view-image-front-purple.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=73632df9f33f69f36c6df0ee625beab0059174771f60ce4d4749b6c370c989e4",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:10+00:00",
"updated_at": "2022-04-28T14:31:10+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Rear View",
"media": [
{
"id": 47,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-back-purple.png",
"size": 40298,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/21d30e4f92444e5a919e76e63c48ef2d/view-image-back-purple.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=d5d109a6c3e55574cc4c891e9dd825d2e600be315fa6cbc38902622d2d79103e",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:11+00:00",
"updated_at": "2022-04-28T14:31:11+00:00"
}
],
"customizations": []
},
{
"handle": "left",
"name": "Left View",
"media": [
{
"id": 48,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-left-purple.png",
"size": 33095,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/de7cb3e2aaa9433d8871ae91b608bc70/view-image-left-purple.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=4076871583b9d13dfdf517f6eb95e604219930e30e2a59f288521bc94ae85c16",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:11+00:00",
"updated_at": "2022-04-28T14:31:11+00:00"
}
],
"customizations": []
},
{
"handle": "right",
"name": "Right View",
"media": [
{
"id": 49,
"is_test": 0,
"collection_name": "view-image",
"file_name": "view-image-right-purple.png",
"size": 33638,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/6bc4938844874946b0bee879f1b16b36/view-image-right-purple.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220429%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220429T111909Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=16c14c605614667ccb6a21a50ae5db3b6f6855121b8138a435cf89fca02bd7d6",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2022-04-28T14:31:11+00:00",
"updated_at": "2022-04-28T14:31:11+00:00"
}
],
"customizations": []
}
],
"failure_message": null,
"created_at": "2022-04-28T14:31:45+00:00",
"updated_at": "2022-04-28T14:31:45+00:00"
}
]
}
```
# Filtering (/docs/checkout/2022-02-01/basic/filtering)
You can search within a collection using `?filter[field]`.
## URL Syntax [#url-syntax]
* `/resources?filter[field]=value`
**Not all attributes are searchable**. Some attributes are **computed attributes** and are not physically
so that they are not searchable. In this case, an exception is thrown.
## Example [#example]
Request
```json
GET /production-methods?filter[handle]=dtg HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"collection_name": "dtg",
"handle": "dtg",
"name": "Digital print",
"description": "Digital print",
"is_digitizable": false,
"created_at": "2022-04-28T14:30:57+00:00",
"updated_at": "2022-04-28T14:30:57+00:00"
}
],
"links": {
"first": "https://api.smake.io/v2/apps/1/production-methods?filter%5Bhandle%5D=dtg&page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://api.smake.io/v2/apps/1/production-methods",
"per_page": 25,
"to": 1
}
}
```
# HTTP Status (/docs/checkout/2022-02-01/basic/http-status)
Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.
In the case of a problem, the status contains the error code, while the body of the response will usually
contain additional information about the problem that was encountered.
## Successful [#successful]
In general, if the status returned is in the **200** range, it indicates that the request was
fulfilled successfully and that no error was encountered.
## Client error [#client-error]
Return codes in the **400** range typically indicate that there was an issue with the request that was sent. Among
other things, this could mean that you did not authenticate correctly, that you are requesting an action
that you do not have authorization for, that the object you are requesting does not exist, or that your request
is malformed.
## Server Error [#server-error]
If you receive a status in the **500** range, this generally indicates a server-side problem. This means that we
are having an issue on our end and cannot fulfill your request currently. The following table summarizes the
typical status codes:
## Codes [#codes]
| Code | Description |
| --------------------------- | ------------------------------------------------------------ |
| 200 - OK | Everything works as expected. |
| 201 - Created | The resource was created successfully. |
| 202 - Accepted | The request was accepted and is processed in the background. |
| 204 - No Content | The resource was successfully deleted. |
| 400 - Bad Request | Valid data was specified, but the request failed. |
| 401 - Unauthorized | No valid Api Key has been specified. |
| 404 - Not Found | The requested resource does not exist. |
| 422 - Unprocessable Entity | The payload has missing required parameters or invalid data. |
| 429 - Too Many Requests | Too many requests in a short time. |
| 500 - Internal Server Error | Request failed due to an internal error in Smake. |
| 503 - Service Unavailable | Smake is offline for maintenance. |
We recommend writing code that gracefully handles all possible API exceptions.
Please handle the status codes and not the `message` or `errors`. These only contain additional
information for you to analyze the problem.
## Examples [#examples]
Generic Errors
```json
HTTP/1.1 401 Unauthenticated
{
"status_code": 401,
"message": "API Key is invalid.",
"errors": []
}
```
Validation Errors
```json
HTTP/1.1 422 Unprocessable Entity
{
"status_code": 422,
"message": "The request data you sent is not valid.",
"errors": {
"shipping_address": {
"first_name": [
"The firstname field is required."
]
},
"items": [
{
"quantity": [
"The items.0.quantity must be at least 1."
]
}
]
}
}
```
# Localization (/docs/checkout/2022-02-01/basic/localization)
## Display [#display]
By default, a resource is presented in **english**.
You can also display the resource in another language.
With the `Accept-Language` header a resource can be localized.
However, this does not affect validation messages or any errors. These
are still displayed in English.
The following locales are currently available for Accept-Language:
`en`, `de`, `nl`, `fr`, `ar`, `sv`, `pl` and `tk`
## Saving [#saving]
In some cases, you can also save a resource localized. For example, the **Checkout Api** uses this to save
an order in a **specified language**. By default it is stored in english, using the `Accept-Language` header
you can control how it is stored.
This is important if, for example, the delivery note is to be displayed in a specific language.
The localization of documents (e. g.: delivery note) cannot be regenerated afterwards.
## Examples [#examples]
### Request for display a response with another language [#request-for-display-a-response-with-another-language]
Request
```json
GET /variants/1 HTTP/1.1
Accept-Language: 'de'
```
Response
```json
Content-Language: 'de'
{
"id": 1,
"option_values": [
{
"handle": "yellow",
"name": "Gelb",
"option_type": {
"handle": "color",
"name": "Farbe"
}
},
...
],
...
}
```
### Request for saving a resources with another language [#request-for-saving-a-resources-with-another-language]
Request
```json
POST /orders HTTP/1.1
Accept-Language: 'de'
{
"email": "customer@example.com",
"items": [
{
"variant_id": 1,
"quantity": 1
}],
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"street1": "123 Main St",
"zip": "12345",
"city": "Anytown",
"country_code": "DE",
"province_code": "NW",
"phone": "12345 67890",
"email": "shipping@example.com"
}
}
```
Response
```json
Content-Language: 'de'
{
"id": 1,
"external_identifier": null,
"external_reference": null,
"state": "incompleted",
"customer_locale": "de",
...
}
```
# Pagination (/docs/checkout/2022-02-01/basic/pagination)
Each collection always has a `meta` and `links` key with information about the paginator.
## Meta [#meta]
`meta` contains the complete information of the paginator, such as the current page or the number of results.
## Links [#links]
`links` contains the direct URLs for navigating through the result set (`first`, `last`, `prev` and `next`).
## Parameters [#parameters]
By default, **25** objects are returned per page.
You can request a different pagination limit or force pagination by appending `?per_page` to the request
with the number of items you would like per page. For instance, to show only two results per page, you could
add `?per_page=2` to the end of your query. The maximum number of results per page is **100**.
You can use the URLs listed under `links` to browse through the pages or directly select a page using
the `?page` query string parameter. With `?page=4` you can e. g. go directly to page 4.
## Example [#example]
Request
```json
GET /production-methods?per_page=2&page=2 HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 3,
"collection_name": "dtg",
"handle": "dtg",
"name": "Digital print",
"description": "Digital print",
"is_digitizable": false,
"created_at": "2022-04-28T14:30:56+00:00",
"updated_at": "2022-04-28T14:30:56+00:00"
},
{
"id": 4,
"collection_name": "embroidery",
"handle": "embroidery",
"name": "Embroider",
"description": "Embroider",
"is_digitizable": true,
"created_at": "2022-04-28T14:30:56+00:00",
"updated_at": "2022-04-28T14:30:56+00:00"
},
],
"links": {
"first": "https://api.smake.io/v2/apps/1/production-methods?per_page=2&page=1",
"last": null,
"prev": "https://api.smake.io/v2/apps/1/production-methods?per_page=2&page=1",
"next": null
},
"meta": {
"current_page": 2,
"from": 3,
"path": "https://api.smake.io/v2/apps/1/production-methods",
"per_page": 2,
"to": 4
}
}
```
# Polling (/docs/checkout/2022-02-01/basic/polling)
If a task takes longer than the request timeout limit, the request is acknowledged by a `202 Accepted`
and treated as a background job.
You don't get the requested data directly, instead you get the URL of the background job in the `Location` header,
which shows you the background job status.
A far more efficient way to get the desired data are [Webhooks](./webhooks).
## Query job status [#query-job-status]
You need to check this URL periodically to check when the background job is finished.
When the background job is completed, a `200 OK` is returned and the response body filled the `resource_url` to complete the next step. If not, a `202 Accepted` will still be returned and the `resource_url` will remain empty.
## Examples [#examples]
### Create a long running task [#create-a-long-running-task]
Request
```json
POST /variant/1/design HTTP/1.1
```
Response
```json
HTTP/1.1 202 Accepted
Location: https://api.smake.io/v2/jobs/1
```
***
### The job is not finished. [#the-job-is-not-finished]
Request
```json
GET /jobs/1 HTTP/1.1
```
Response
```json
Location: https://api.smake.io/v2/jobs/1
{
"id": 1,
"is_test": true,
"resource_url": null,
"state": "queued"
}
```
### The job is finished. [#the-job-is-finished]
Request
```json
GET /jobs/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"is_test": true,
"resource_url": "https://api.smake.io/v2/custom-variants/2",
"state": "finished"
}
```
# Rate Limit (/docs/checkout/2022-02-01/basic/rate-limit)
The number of requests that can be made through the API is currently limited to 5000 requests per hour.
The rate limiting information is contained within the response headers of each request.
If the `X-RateLimit-Remaining` **0** is reached, subsequent requests receive a **429** error code until the
`X-RateLimit-Reset` is reached.
## Headers [#headers]
| Header Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-RateLimit-Limit | The number of requests that can be made per hour. |
| X-RateLimit-Remaining | The number of requests that remain before you hit your request limit. |
| X-RateLimit-Reset | This represents the time when the oldest request will expire. The value is given in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time). |
If you exceed your rate limit, you can likely fix the issue by caching API responses and using [Conditional Request](./conditional-request).
## Examples [#examples]
### Rate Limit not reached [#rate-limit-not-reached]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4954
{
"data": [
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
....
}
]
}
```
### Rate Limit reached [#rate-limit-reached]
Request
```json
GET /orders HTTP/1.1
```
Response
```json
GET /orders HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "Too many attempts."
}
```
# Request Id (/docs/checkout/2022-02-01/basic/request-id)
Each API request has an associated request identifier.
You can find this value in the response headers, under `X-Request-Id`.
### Request [#request]
```json
GET /orders HTTP/1.1 200 OK
```
### Response [#response]
```json
X-Request-Id: d312517c-7ac9-402d-87c5-0a6b9da92a4d
```
If you need to contact us about a specific request, providing the request identifier will
ensure the fastest possible resolution.
# Request (/docs/checkout/2022-02-01/basic/request)
Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI.
The interface responds to different methods depending on the action required.
| Method | Use |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | For simple retrieval of information, you should use the GET method. The information you request will be returned to you as a JSON object. Any request using the GET method is read-only and will not affect any of the objects you are querying. |
| DELETE | To destroy a resource, use the DELETE method. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. |
| PUT | To update the information about a resource, the PUT method is available. The PUT request contains all attributes that are to be updated for an object. |
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint. |
# Requested data (/docs/checkout/2022-02-01/basic/requested-data)
## Requested object [#requested-object]
Sometimes it is necessary to see which data is used to create a new resource.
For example, which file was used to create a media or which variant was used to create a new designed variant.
Therefore, a `requested` attribute is shown for a specific resource.
It's an object with unstructured data containing this information.
This information is for debugging purposes only and may change structurally over time. Do not use this data programmatically.
### Requested object on logo [#requested-object-on-logo]
Request
```json
POST logos HTTP/1.1
{
"production_method": {
"handle": "dtg"
},
"media": [
{
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/testfiles/logo.png",
"collection_name": "production-file"
}
]
}
```
Request
```json
POST logos/155 HTTP/1.1
{
"id": 1,
"state": "completed",
"collection_name": "catalogue",
"name": "logo",
"production_method": 4,
"texts": [],
"media": [
{
"id": 1987,
"is_test": 0,
"collection_name": "production-file",
"file_name": "logo.png",
"size": 7502,
"mime_type": "image/png",
"download_url": "https://smake-public.s3.eu-west-1.amazonaws.com/files/f02fbd307ca644838cb22204a83d8535/logo.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATV6IRLEXI2SRHX47%2F20220330%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220330T142111Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=a8821c9c306bccd4ac0067238e2832adc6e0c5d62ff9385dea9836fa06698ab8",
"state": "completed",
"requested": {
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/testfiles/logo.png",
"collection_name": "production-file"
},
"failure_message": null,
"created_at": "2022-03-30T14:21:02+00:00",
"updated_at": "2022-03-30T14:21:02+00:00"
}
],
"failure_message": null,
"created_at": "2022-03-30T14:21:01+00:00",
"updated_at": "2022-03-30T14:21:02+00:00"
}
```
# Response (/docs/checkout/2022-02-01/basic/response)
When a request is successful, a response body will typically be sent back in the form of a JSON object.
One exception is the `DELETE` request, which will result in a successful `HTTP 204 status` and an empty response body.
Another exception is when a request is processed asynchronously, it will result in a successful
`HTTP 202 status` and an empty response body.
## Collection [#collection]
A collection of resources will be displayed within the `data` object.
```json
{
"data": [
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
....
}
]
}
```
## Resource [#resource]
A resource are presented directly.
```json
{
"id": 1,
"is_test": true,
"first_name": "John",
"last_name": "Doe",
"company": null,
"addresses": [],
"created_at": "2017-09-28T08:40:44+00:00",
"updated_at": "2017-09-28T08:40:44+00:00",
...
}
```
## Attribute [#attribute]
If an attribute has no value it is presented as `null`.
If an attribute is some kind of list and it is represented by an array, an array will be returned, even if empty.
```json
{
"company": null,
"addresses": [],
...
}
```
## Timestamp [#timestamp]
All time values presented in ISO8601 format: `YYYYY-MM-DDTHH:MM:SSZ`.
# Webhooks (/docs/checkout/2022-02-01/basic/webhooks)
Webhooks are a feature that allows you to have your system receive notifications about a certain event on our site.
When an event happens, the Smake server sends a POST request to your defined endpoint URLS.
This request contains all the relevant information about the Event, including the type and the data
associated with that. You can have Smake send a single event to multiple webhook endpoints.
Webhook data is sent as JSON in the POST request body.
To acknowledge receipt of a event, your endpoint must return a 2xx HTTP status code.
All response codes outside this range indicate to Smake that you did not receive the event.
If you do not acknowledge receipt of a event, Smake will continue to deliver your webhooks with
an exponential backoff for up to one day.
This is similar to [polling](./polling), webhooks provide your application a way of consuming data that
takes longer to proccess, but instead of sending repeated requests for new data, you will be informed per events.
**Webhooks are the prefered way of consuming data that takes longer to proccess, because there are far more efficient.**
## Retry frequency [#retry-frequency]
Smake has implemented a timeout period of 10 seconds and a retry period for webhook subscriptions.
Smake waits for a response to each webhook request for ten seconds. If no response is received or an error is returned, Smake will attempt to establish the connection 50 times within the next 48 hours.
To avoid timeouts and errors, you should consider postponing app processing until the webhook response has been successfully sent.
## Webhooks and API versions [#webhooks-and-api-versions]
The structure of the payload an event sent in a webhook is dictated by the API Version you set in the
app at the time of the event's occurrence. For example, if your app is set to an older
API version, such as `2017-09-25`, and you change the API version for a specific request via versioning,
the payload generated and sent to your endpoint is still based upon the `2017-09-25` API version.
## Signatures [#signatures]
Smake can optionally sign the webhook events it sends to your endpoints. We do so by including a
signature in each event’s `X-Signature` header, when your secret token is set. Smake uses it to create a hash
signature with each payload. This allows you to validate that the events were sent by Smake, not by a third party.
### Validating payloads [#validating-payloads]
Smake uses an HMAC hexdigest to compute the hash, so you could change your server to look a little like this:
```php
class WebhookController extends Controller
{
public function handleVariantDesigned(Request $request)
{
$payload = json_decode($request->getContent(), true);
if (! $this->hasValidSignature($request, $payload)) {
// Handle invalid Signature
return response()->setStatusCode(422);
}
// Handle Payload
return response()->setStatusCode(200);
}
protected function hasValidSignature(Request $request, string $payload): bool
{
$token = config('my-secret-token');
return $request->header('X-Signature') === 'sha1='.hash_hmac('sha1', $payload, $token);
}
}
```
## Best Practice [#best-practice]
### Acknowledge events immediately [#acknowledge-events-immediately]
If your webhook script performs complex logic, or makes network calls, it’s possible that the script would time out
before Smake sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by
returning a `2xx` status code) is separate of any other logic you do for that event.
### Handle duplicate events [#handle-duplicate-events]
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against
duplicated event receipts by making your event processing idempotent. One way of doing this is logging the
events you’ve processed, and then not processing already-logged events.
### Order Events [#order-events]
Smake does not guarantee delivery of events in the order in which they are generated.
You should handle this accordingly.
# Changelog (/docs/checkout/2022-02-01/references/changelog)
The changelog is a list of backwards-incompatible updates in the API. As described before, new additions and forwards-compatible changes don’t need a new API version and will not appear in this list.
## 2022-01-01 [#2022-01-01]
### Removed webhook events [#removed-webhook-events]
* The webhook event `shipping-rate.calculated` was removed
* The webhook event `id-tag.updated` was removed
### Renamed webhook events [#renamed-webhook-events]
* The webhook event `logo.ready` was renamed to `logo.completed`
* The webhook event `order.ready` was renamed to `order.prepared`
* The webhook event `order.shipped` was renamed to `order.completed`
* The webhook event `variant.designed` was renamed to `variant.completed`
* The webhook event `fulfillment.ready` was renamed to `shipment.prepared`
### Removed endpoints [#removed-endpoints]
**Some media endpoints were removed**
* The end point `GET {{ endpoint }}/media` was removed
* The end point `GET {{ endpoint }}/media/{{ YOUR_MEDIA_ID }}/download` was removed
**All checkout endpoints were removed**
* The end point `POST {{ endpoint }}/checkouts` was removed
* The end point `GET {{ endpoint }}/checkouts/{{ YOUR_ORDER_ID }}/shipping-rates` was removed
* The end point `PUT {{ endpoint }}/checkouts/{{ YOUR_ORDER_ID }}` was removed
* The end point `PUT {{ endpoint }}/checkouts/{{ YOUR_ORDER_ID }}/complete` was removed
**All custom variant endpoints were removed**
* The end point `GET {{ endpoint }}/custom-variants` was removed
* The end point `GET {{ endpoint }}/custom-variants/{{ YOUR_CUSTOM_VARIANT_ID }}` was removed
### Added endpoints [#added-endpoints]
**Production methods endpoint**
* Endpoint `GET {{ endpoint }}/production-methods` has been added, for more information see page [production-methods](../api/production-methods).
**Logos endpoints**
* Endpoint `GET {{ endpoint }}/logos` has been added, for more information see page [logos](../api/logos).
* Endpoint `GET {{ endpoint }}/logos/{{ YOUR_LOGO_ID }}` has been added, for more information see page [logos](../api/logos).
* Endpoint `POST {{ endpoint }}/logos` has been added, for more information see page [logos](../api/logos).
* Endpoint `POST {{ endpoint }}/logos/{{ YOUR_LOGO_ID }}/design` has been added, for more information see page [logos](../api/logos).
**Shipping methods endpoint**
* Endpoint `GET {{ endpoint }}/shipping-methods` has been added, for more information see page [shipping-methods](../api/shipping-methods).
**Orders endpoint**
* Endpoint `POST {{ endpoint }}/orders` has been added, for more information see page [orders](../api/orders).
## 2021-02-23 [#2021-02-23]
* The `fulfillments` object has now all `parcels` objects. See in the endpoint [orders](../../2021-02-23/endpoints/orders).
* The `fulfillments.order_id` was changed to an `order` object. See in the endpoint [orders](../../2021-02-23/endpoints/orders).
## 2020-01-17 [#2020-01-17]
* The `project_name` parameter has changed to `external_reference` in the endpoint [checkouts](../../2021-02-23/endpoints/orders).
* The `project_name` in the order resource within the endpoints [checkouts](../../2021-02-23/endpoints/orders) and
[orders](../../2021-02-23/endpoints/orders) has changed to `external_reference`.
## 2019-10-01 [#2019-10-01]
* The `payment.amount` parameter must not be passed in the endpoint [checkouts/complete](../../2021-02-23/endpoints/orders).
* The `payment.handle` parameter in endpoint [checkouts/complete](../../2021-02-23/endpoints/orders) now accepts all handles that are listed within endpoint [payment-methods](../../2021-02-23/api/payment-methods).
## 2019-02-28 [#2019-02-28]
* `include` parameter is replaced by the `expand` parameter.
* On the products endpoint the variant resource initially only shows `ids`. You have to use `?expand=variants` to show the complete resource
* Removed `current_state` in `id_tags`
## 2018-12-06 [#2018-12-06]
* The variant resource is not automatically loaded on the products endpoint. You have to you use `?include=variants`
* Pagination simplified.
* Removed `meta.last_page` and `meta.total` attribute.
* `links.last` will always be `null`.
* `shipping_line` attribute removed in orders endpoint and added a `shipping_total` attribute
* Added `state` and `order_id` to `id_tags`
## 2017-09-25 [#2017-09-25]
* Initial Release
# Versioning (/docs/checkout/2022-02-01/references/versioning)
Smake Api uses versioning to roll out backwards-incompatible changes over time.
## Backwards-compatible changes [#backwards-compatible-changes]
Smake considers the following changes to be backwards-compatible:
* Adding new API resources.
* Adding new optional request parameters to existing API methods.
* Adding new attributes to existing API responses.
* Changing the order of attributes in existing API responses.
* Adding new event types.
## About Versioning [#about-versioning]
The API version will control the API and webhook behaviors, such as parameters accepted in requests, and
response properties.
A new version of the API is released when backwards-incompatible changes are made to the API. To avoid
breaking your code, we will never force you to upgrade until you’re ready.
We will be releasing backwards-compatible changes without introducing new versions. Your code will be able
to handle these changes no matter what version it’s on.
## Upgrade your Api Version [#upgrade-your-api-version]
We recommend staying up-to-date with the current API version to take advantage of latest
improvements to the Smake API.
To see your current version and upgrade to the latest, visit the API Page on your app.
Versioning of the Smake API will be released as dates, displayed as: `YYYY-MM-DD`
## Test Before Upgrading [#test-before-upgrading]
To test your code under a different API version before committing the change, you can set the API version
on a specific request by setting a header with the version you are testing. The version will be set for
subsequent requests until it’s changed back.
Users can only upgrade their API to the latest version. Once you’ve upgraded your API version, you cannot
roll back to an earlier version. Please make sure to test thoroughly before doing so.
## Example [#example]
```json
GET /products HTTP/1.1
X-Api-Version: 2018-12-06
```
# Authentication (/docs/checkout/2022-02-01/setup/authentication)
In order to use the API, you must authenticate **each request** by including your API Token as a bearer token value:
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
```
You must replace `API_TOKEN_HERE` with your personal API Token.
# Headers (/docs/checkout/2022-02-01/setup/headers)
The API only supports the data format **JSON**. Therefore, make sure you have the following headers
set on **each request**.
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
Accept: application/json
Content-Type: application/json
```
# Test Mode (/docs/checkout/2022-02-01/setup/test-mode)
First you will receive a test application which works similar to your later live application.
To make the API as explorable as possible, you will receive a test and a live token. There is no **switch** for
changing between them, just use the appropriate token to perform a live or test request.
Requests made within a test application never creates real orders and cause no costs.
| Field | Type | Description |
| -------- | ------- | ------------------------------------------------------------------------------------ |
| is\_test | boolean | Flag indicating whether the resource exists in live application or test application. |
```json
{
"id": 1,
"is_test": true,
"external_identifier": null,
"external_reference": "et",
"state": "delivered",
"customer_locale": "en",
"currency": "EUR",
...
}
```
# Batch-Endpoints (/docs/master/2022-07-01/basic/batch-filtering)
You can search within a collection using the `filter`-field.
## URL Syntax [#url-syntax]
### GET Method [#get-method]
```json
GET /resources?filter[field]=value HTTP/1.1
```
### Other Methods [#other-methods]
```json
POST, UPDATE, PATCH, DELETE /resources HTTP/1.1
```
Request
```json
{
"filter": {
"field": "value",
"nested.filter": "value"
}
}
```
**Not all attributes are searchable**. You will see the actual filterable fields in the endpoint documentation.
# Conditional Request (/docs/master/2022-07-01/basic/conditional-request)
All **successful GET requests** responses return an `ETag` header. You can use the `ETag` value to make
subsequent requests to those resources using the `If-None-Match` header. If the resource has not changed,
the server returns a `304 Not Modified`.
Making a conditional request and receiving a 304 response does not count against your [Rate Limit](./rate-limit),
so we encourage you to use it whenever possible.
## Examples [#examples]
### Without If-None-Match Header [#without-if-none-match-header]
Request
```http request
GET /orders HTTP/1.1
```
Response
```json
GET /orders HTTP/1.1 200 OK
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
***
### With If-None-Match Header [#with-if-none-match-header]
Request
```http request
GET /orders HTTP/1.1
If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
Response
```json
GET /orders HTTP/1.1 304 Not Modified
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
```
# Date and time (/docs/master/2022-07-01/basic/date-time)
In our API, we utilize the Coordinated Universal Time (UTC) system for all date and time-related operations. Therefore, it is crucial to ensure that you provide the accurate UTC date and time values when interacting with those API.
Certain endpoints within the API may require you to input specific dates and times, such as `available_at`,`discontinue_at` etc. It is important to pay close attention to these requirements and provide the appropriate UTC date and time values for seamless integration with the API.
By adhering to the correct UTC date and time format throughout your interactions with the API, you will ensure accurate and consistent data processing. This adherence to UTC helps avoid any discrepancies that may arise from differing time zones or daylight saving time adjustments.
## Example [#example]
```json
{
....
"available_at" : "2023-05-25T10:50:23+00:00"
....
}
```
Format must be like: YYYY-MM-DDTHH:ii:ss+00:00
The time offset must be `+00:00` because it is UTC.
Please do not put your local time difference in the time offset such as `01:00`, `02:00` etc.
# Expanding Objects (/docs/master/2022-07-01/basic/expanding-objects)
Many objects contain the `id` of a related object in their response properties. For example, a Product size labels may
have associated product size ids. Those objects can be expanded inline with the `expand` request parameter.
Objects that can be expanded are noted in this documentation.
You can expand recursively by specifying nested fields after a dot (`.`). For example,
requesting `product_sizes` on an request will expand the product size property into a full product size object.
You can expand multiple objects at once by separating them with a comma.
## Compressed Product sizes [#compressed-product-sizes]
Request
```http request
GET /product-size-labels/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
## Expanded Product sizes [#expanded-product-sizes]
Request
```http request
GET /product-size-labels/1?expand=product_sizes HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
{
"id": 1,
"handle": "herren-hosen-eu-d-40",
"value": "40",
"product_size_scale": {
"id": 1,
"name": "D",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 2,
"handle": "herren-hosen-eu-gr-40",
"value": "40",
"product_size_scale": {
"id": 2,
"name": "GR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 3,
"handle": "herren-hosen-eu-f-46",
"value": "46",
"product_size_scale": {
"id": 3,
"name": "F",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 4,
"handle": "herren-hosen-eu-b-44",
"value": "44",
"product_size_scale": {
"id": 4,
"name": "B",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 5,
"handle": "herren-hosen-eu-i-46",
"value": "46",
"product_size_scale": {
"id": 5,
"name": "I",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 6,
"handle": "herren-hosen-eu-tr-40",
"value": "40",
"product_size_scale": {
"id": 6,
"name": "TR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
# Filtering (/docs/master/2022-07-01/basic/filtering)
You can search within a collection using `?filter[field]`.
## URL Syntax [#url-syntax]
* `/resources?filter[field]=value`
**Not all attributes are searchable**. Some attributes are **computed attributes** and are not physically
so that they are not searchable. In this case, an exception is thrown.
## Example [#example]
Request
```http request
GET /production-methods?filter[handle]=dtg HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "dtg",
"collection_name": "dtg",
"name": {
"ar": "طباعة رقمية",
"de": "Digital-Direktdruck",
"en": "Digital print",
"es": "Impresión digital",
"fr": "Impression numérique",
"it": "Stampa digitale",
"ja": "デジタルプリント",
"ko": "Digital-Direktdruck",
"nl": "Digitaal printen",
"pl": "Druk cyfrowy",
"sv": "Digitalt direkttryck",
"tr": "Dijital baskı"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/production-methods",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
# HTTP Status (/docs/master/2022-07-01/basic/http-status)
Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.
In the case of a problem, the status contains the error code, while the body of the response will usually
contain additional information about the problem that was encountered.
## Successful [#successful]
In general, if the status returned is in the **200** range, it indicates that the request was
fulfilled successfully and that no error was encountered.
## Client error [#client-error]
Return codes in the **400** range typically indicate that there was an issue with the request that was sent. Among
other things, this could mean that you did not authenticate correctly, that you are requesting an action
that you do not have authorization for, that the object you are requesting does not exist, or that your request
is malformed.
## Server Error [#server-error]
If you receive a status in the **500** range, this generally indicates a server-side problem. This means that we
are having an issue on our end and cannot fulfill your request currently. The following table summarizes the
typical status codes:
## Codes [#codes]
| Code | Description |
| --------------------------- | ------------------------------------------------------------ |
| 200 - OK | Everything works as expected. |
| 201 - Created | The resource was created successfully. |
| 202 - Accepted | The request was accepted and is processed in the background. |
| 204 - No Content | The resource was successfully deleted. |
| 400 - Bad Request | Valid data was specified, but the request failed. |
| 401 - Unauthorized | No valid Api Key has been specified. |
| 404 - Not Found | The requested resource does not exist. |
| 422 - Unprocessable Entity | The payload has missing required parameters or invalid data. |
| 429 - Too Many Requests | Too many requests in a short time. |
| 500 - Internal Server Error | Request failed due to an internal error in Smake. |
| 503 - Service Unavailable | Smake is offline for maintenance. |
We recommend writing code that gracefully handles all possible API exceptions.
Please handle the status codes and not the `message` or `errors`. These only contain additional
information for you to analyze the problem.
## Examples [#examples]
Generic Errors
```json
HTTP/1.1 401 Unauthenticated
{
"status_code": 401,
"message": "API Key is invalid.",
"errors": []
}
```
Validation Errors
```json
HTTP/1.1 422 Unprocessable Entity
{
"message": "handle is a required field. (and 1 more error)",
"errors": {
"handle": [
"handle is a required field."
],
"description.de": [
"description.de is a required field."
]
}
}
```
# Pagination (/docs/master/2022-07-01/basic/pagination)
Each collection always has a `meta` and `links` key with information about the pagination.
## Meta [#meta]
`meta` contains the complete information of the paginator, such as the path, next cursor or the number of results.
## Links [#links]
`links` contains the direct URLs for navigating through the result set (`prev` and `next`). Although there will be no page information but information
on `prev` and `next` cursor with full URL.
## Parameters [#parameters]
By default, **15** objects are returned per page.
You can request a different cursor string by appending `?cursor` to the request
with the endcoded string in meta.
You can use the URLs listed under `links` to browse through the pages or directly select a cursor using
the `?cursor` string parameter. With `?cursor=eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjMsIl9w` you can e. g. go directly to specific page which is this encoded string pointing.
```json
...
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/product-option-values?cursor=eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-values",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
...
```
## Example [#example]
Request
```http request
GET /product-option-values
?cursor=eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0 HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 2,
"handle": "S",
"name": {
"de": "S",
"en": "S"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 1,
"handle": "gray",
"name": {
"de": "gray",
"en": "gray"
},
"option_type": 2,
"media": [
144
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": "https://api.smake.io/master-administration/product-option-values?cursor=eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjIsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-values",
"per_page": 15,
"next_cursor": null,
"prev_cursor": "eyJwcm9kdWN0aW9uX29wdGlvbl92YWx1ZXMuaWQiOjIsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
}
}
```
# Rate Limit (/docs/master/2022-07-01/basic/rate-limit)
The number of requests that can be made through the API is currently limited to 5000 requests per hour.
The rate limiting information is contained within the response headers of each request.
If the `X-RateLimit-Remaining` **0** is reached, subsequent requests receive a **429** error code until the
`X-RateLimit-Reset` is reached.
## Headers [#headers]
| Header Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-RateLimit-Limit | The number of requests that can be made per hour. |
| X-RateLimit-Remaining | The number of requests that remain before you hit your request limit. |
| X-RateLimit-Reset | This represents the time when the oldest request will expire. The value is given in [UTC epoch seconds](http://en.wikipedia.org/wiki/Unix_time). |
If you exceed your rate limit, you can likely fix the issue by caching API responses and using [Conditional Request](./conditional-request).
## Examples [#examples]
### Rate Limit not reached [#rate-limit-not-reached]
Request
```http request
GET /production-methods HTTP/1.1
```
Response
```json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4957
{
"data": [
{
"id": 4,
"handle": "manual",
"collection_name": "manual",
"name": {
"ar": "دليل",
"de": "Eigenes Produktionsverfahren",
"en": "Manual",
"es": "Manual",
"fr": "Manuel",
"it": "Manuale",
"ja": "マニュアル",
"ko": "Eigenes Produktionsverfahren",
"nl": "Manueel",
"pl": "Ręcznie",
"sv": "Egen produktionsprocess",
"tr": "El ile"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
........
]
}
```
### Rate Limit reached [#rate-limit-reached]
Request
```http request
GET /production-methods HTTP/1.1
```
Response
```json
GET /production-methods HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "Too many attempts."
}
```
# Request Id (/docs/master/2022-07-01/basic/request-id)
Each API request has an associated request identifier.
You can find this value in the response headers, under `X-Request-Id`.
### Request [#request]
```http request
GET /orders HTTP/1.1
```
### Response [#response]
```json
X-Request-Id: d312517c-7ac9-402d-87c5-0a6b9da92a4d
```
If you need to contact us about a specific request, providing the request identifier will
ensure the fastest possible resolution.
# Request (/docs/master/2022-07-01/basic/request)
Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI.
The interface responds to different methods depending on the action required. The following methods can be used for corresponding URI.
| Method | Use |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | For simple retrieval of information, you should use the GET method. The information you request will be returned to you as a JSON object. Any request using the GET method is read-only and will not affect any of the objects you are querying. |
| POST | To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint. |
| PUT | To update the information about a resource, the PUT method is available. The PUT request contains all attributes that are to be updated for an object. |
| PATCH | To update the partial information about a resource, the PATCH method is available. The PATCH request contains only attributes that are to be updated for an object. |
| DELETE | To destroy a resource, use the DELETE method. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. |
# Response (/docs/master/2022-07-01/basic/response)
When a request is successful, a response body will typically be sent back in the form of a JSON object.
Another exception is when a request is processed asynchronously, it will result in a successful
`HTTP 202 status` and an empty response body.
## Collection [#collection]
A collection of resources will be displayed within the `data` object.
```json
{
"data": [
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
......
}
```
## Resource [#resource]
A resource are presented directly.
```json
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
## Attribute [#attribute]
If an attribute has no value it is presented as `null`.
If an attribute is some kind of list and it is represented by an array, an array will be returned, even if empty.
```json
{
...
"scale_factors": [],
"discontinue_at": null,
...
}
```
## Timestamp [#timestamp]
All time values presented in ISO8601 format: `YYYYY-MM-DDTHH:MM:SSZ`.
# Temporary Upload (/docs/master/2022-07-01/basic/temporary-upload-url)
Temporary upload allows you to upload data to S3 storage and then process it further. This could include CSV data or images.
Most endpoints in the Master API work with CSV data and not with images.
## Get Upload Url [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/plain",
"file_name": "example.csv"
}
```
Response
```json
{
"path": "tmp/a6273055-b7c4-4bed-9955-e41fbe09ce5b-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-local.s3.eu-west-1.amazonaws.com/tmp/a6273055-b7c4-4bed-9955-e41fbe09ce5b-metaZXhhbXBsZS5jc3Y%3D-.csv?X-Amz-Content ....",
"headers": {
"Content-Type": "text/plain"
}
}
```
**Note:** The upload URL is valid for **10 minutes**.
## Upload Content [#upload-content]
Use the URL from the POST response and upload your data there.
Upload the Content
Request
```http request
PUT https://smake-local.s3.eu-west-1.amazonaws.com/tmp/a6273055-b7c4-4bed-9955-e41fbe09ce5b-metaZXhhbXBsZS5jc3Y%3D-.csv?X-Amz-Content .... HTTP/1.1
Content-Type: text/plain
id,handle,locale,name,description,manufacturer,manufacturer_number,brand
361,OTkvY6Q0EPzMbOk4,en,"T-Shirt 6 designable","Iste dolorum cumque ab quas voluptatum.","Kellie Sauer",Zos9y9pfXbhVG3TJ,"Bertram Douglas"
```
Response
```http
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
# Webhooks (/docs/master/2022-07-01/basic/webhooks)
Webhooks are a feature that allows you to have your system receive notifications about a certain event on our site.
When an event happens, the Smake server sends a POST request to your defined endpoint URLS.
This request contains all the relevant information about the Event, including the type and the data
associated with that. You can have Smake send a single event to multiple webhook endpoints.
Webhook data is sent as JSON in the POST request body.
To acknowledge receipt of a event, your endpoint must return a 2xx HTTP status code.
All response codes outside this range indicate to Smake that you did not receive the event.
If you do not acknowledge receipt of a event, Smake will continue to deliver your webhooks with
an exponential backoff for up to one day.
This is similar to [polling](./polling), webhooks provide your application a way of consuming data that
takes longer to proccess, but instead of sending repeated requests for new data, you will be informed per events.
**Webhooks are the prefered way of consuming data that takes longer to proccess, because there are far more efficient.**
## Retry frequency [#retry-frequency]
Smake has implemented a timeout period of 10 seconds and a retry period for webhook subscriptions.
Smake waits for a response to each webhook request for ten seconds. If no response is received or an error is returned, Smake will attempt to establish the connection 50 times within the next 48 hours.
To avoid timeouts and errors, you should consider postponing app processing until the webhook response has been successfully sent.
## Webhooks and API versions [#webhooks-and-api-versions]
The structure of the payload an event sent in a webhook is dictated by the API Version you set in the
app at the time of the event's occurrence. For example, if your app is set to an older
API version, such as `2017-09-25`, and you change the API version for a specific request via versioning,
the payload generated and sent to your endpoint is still based upon the `2017-09-25` API version.
## Signatures [#signatures]
Smake can optionally sign the webhook events it sends to your endpoints. We do so by including a
signature in each event’s `X-Signature` header, when your secret token is set. Smake uses it to create a hash
signature with each payload. This allows you to validate that the events were sent by Smake, not by a third party.
### Validating payloads [#validating-payloads]
Smake uses an HMAC hexdigest to compute the hash, so you could change your server to look a little like this:
```php
class WebhookController extends Controller
{
public function handleVariantDesigned(Request $request)
{
$payload = json_decode($request->getContent(), true);
if (! $this->hasValidSignature($request, $payload)) {
// Handle invalid Signature
return response()->setStatusCode(422);
}
// Handle Payload
return response()->setStatusCode(200);
}
protected function hasValidSignature(Request $request, string $payload): bool
{
$token = config('my-secret-token');
return $request->header('X-Signature') === 'sha1='.hash_hmac('sha1', $payload, $token);
}
}
```
## Best Practice [#best-practice]
### Acknowledge events immediately [#acknowledge-events-immediately]
If your webhook script performs complex logic, or makes network calls, it’s possible that the script would time out
before Smake sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by
returning a `2xx` status code) is separate of any other logic you do for that event.
### Handle duplicate events [#handle-duplicate-events]
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against
duplicated event receipts by making your event processing idempotent. One way of doing this is logging the
events you’ve processed, and then not processing already-logged events.
### Order Events [#order-events]
Smake does not guarantee delivery of events in the order in which they are generated.
You should handle this accordingly.
# Annotation Channel (/docs/master/2022-07-01/endpoints/annotation-channel)
Fetching annotation channel via this endpoints.
## LIST [#list]
Return a collection of annotation channel.
### Example of fetching annotation channel list [#example-of-fetching-annotation-channel-list]
Request
```http request
GET /annotation-channels HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/annotation-channels",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a annotation channel of given `id` = **x**.
### Example of fetching specified annotation channel [#example-of-fetching-specified-annotation-channel]
Request
```http request
GET /annotation-channels/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
```
# Annotation (/docs/master/2022-07-01/endpoints/annotation)
Fetching annotations via this endpoints.
## LIST [#list]
Return a collection of annotation.
### Example of fetching annotation list [#example-of-fetching-annotation-list]
Request
```http request
GET /annotations HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "fuga",
"description": {
"de": "Casey Homenick",
"en": "Herbert Watsica"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 2,
"handle": "doloribus",
"description": {
"de": "Dr. Orin Stiedemann IV",
"en": "Simone Baumbach"
},
"channels": [
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"handle": "unde",
"description": {
"de": "Ellen Altenwerth MD",
"en": "Kendra Hauck IV"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 4,
"handle": "rerum",
"description": {
"de": "Karson Hamill",
"en": "Emelie Crooks"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 5,
"handle": "ipsam",
"description": {
"de": "Joan Quitzon",
"en": "Dorothea Schaefer DDS"
},
"channels": [
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 6,
"handle": "alias",
"description": {
"de": "Prof. Winfield Toy III",
"en": "Adela Feil"
},
"channels": [
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 7,
"handle": "esse",
"description": {
"de": "Helmer Champlin",
"en": "Dr. Fabian Stokes"
},
"channels": [
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 8,
"handle": "natus",
"description": {
"de": "Fay Becker",
"en": "Mrs. Samanta Balistreri IV"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 9,
"handle": "inventore",
"description": {
"de": "Selena Stehr",
"en": "Ursula Kozey"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 10,
"handle": "possimus",
"description": {
"de": "Garett Funk",
"en": "Palma Smith"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/annotations",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a annotation of given `id` = **x**.
### Example of fetching specified annotation [#example-of-fetching-specified-annotation]
Request
```http request
GET /annotations/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "fuga",
"description": {
"de": "Casey Homenick",
"en": "Herbert Watsica"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 3,
"handle": "production",
"name": {
"de": "Produktion"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
```
## CREATE [#create]
Create a new annotation.
### Channel Array [#channel-array]
Array of annotation channel id's. Minimum 1 id is required.
List of annotation channel can be found here. see [Annotation Channel](./annotation-channel)
### Example of creating a new annotation [#example-of-creating-a-new-annotation]
Request
```http request
POST /annotations HTTP/1.1
{
"description": {
"de": "Hinweistext eins",
"en": "Annotation Text"
},
"handle": "annotation-1",
"channels": [
2,
1
]
}
```
Response
```json
{
"id": 11,
"handle": "annotation-1",
"description": {
"de": "Hinweistext eins",
"en": "Annotation Text"
},
"channels": [
{
"id": 2,
"handle": "agent",
"name": {
"de": "Kundenbetreuer"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
},
{
"id": 1,
"handle": "customer",
"name": {
"de": "Endkunde"
},
"created_at": "2022-12-20T08:14:02+00:00",
"updated_at": "2022-12-20T08:14:02+00:00"
}
],
"created_at": "2023-01-16T14:21:11+00:00",
"updated_at": "2023-01-16T14:21:11+00:00"
}
```
# Disposition Order (/docs/master/2022-07-01/endpoints/disposition-order)
Fetching list of disposition order.
## LIST [#list]
Return a collection of disposition order.
### Example of fetching disposition order list [#example-of-fetching-disposition-order-list]
Request
```http request
GET /disposition-orders HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 181,
"order": 191,
"state": "manual_assignment_process",
"cancelled_at": null,
"created_at": "2024-07-19T09:00:29+00:00",
"updated_at": "2024-07-19T09:00:31+00:00"
},
{
"id": 180,
"order": 190,
"state": "delivered",
"cancelled_at": null,
"created_at": "2024-07-19T08:52:36+00:00",
"updated_at": "2024-07-19T08:52:36+00:00"
},
{
"id": 179,
"order": 189,
"state": "delivered",
"cancelled_at": null,
"created_at": "2024-07-19T08:52:36+00:00",
"updated_at": "2024-07-19T08:52:36+00:00"
},
....
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/disposition-orders?cursor=eyJkaXNwb3NpdGlvbl9vcmRlcnMuaWQiOjE2NywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
},
"meta": {
"path": "https://api.smake.io/master-administration/disposition-orders",
"per_page": 15,
"next_cursor": "eyJkaXNwb3NpdGlvbl9vcmRlcnMuaWQiOjE2NywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
"prev_cursor": null
}
}
```
### Example of fetching disposition order list with expand [#example-of-fetching-disposition-order-list-with-expand]
Request
```http request
GET /disposition-orders?expand=order HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 181,
"order": {
"id": 191,
"order_type": 6,
"external_identifier": null,
"external_reference": null,
"merchant": 2,
"cost_centre": null,
"state": "preparing",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 78.23,
"subtotal": 73.112149532711,
"total_tax": 5.11785046728981,
"total_items_price": 75.88,
"shipping_total": 2.35,
"discount_total": 0,
"promotion_codes": [],
"items": [
311
],
"disposition_order": 181,
"customer": 179,
"shipping_address": 356,
"billing_address": 355,
"whitelabel_address": null,
"payment": null,
"shipments": [
191
],
"created_at": "2024-07-19T09:00:09+00:00",
"updated_at": "2024-07-19T09:00:29+00:00",
"cancelled_at": null,
"ordered_at": "2024-07-19T09:00:29+00:00"
},
"state": "manual_assignment_process",
"cancelled_at": null,
"created_at": "2024-07-19T09:00:29+00:00",
"updated_at": "2024-07-19T09:00:31+00:00"
},
{
"id": 180,
"order": {
"id": 190,
"order_type": 6,
"external_identifier": null,
"external_reference": null,
"merchant": 2,
"cost_centre": null,
"state": "completed",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 64.69,
"subtotal": 60.041820841121,
"total_tax": 4.6472964588785,
"total_items_price": 59.49,
"shipping_total": 5.2,
"discount_total": 0,
"promotion_codes": [],
"items": [
310
],
"disposition_order": 180,
"customer": 178,
"shipping_address": 344,
"billing_address": 343,
"whitelabel_address": null,
"payment": null,
"shipments": [
190
],
"created_at": "2024-07-19T08:52:29+00:00",
"updated_at": "2024-07-19T08:52:29+00:00",
"cancelled_at": null,
"ordered_at": "2024-07-19T08:52:29+00:00"
},
"state": "delivered",
"cancelled_at": null,
"created_at": "2024-07-19T08:52:36+00:00",
"updated_at": "2024-07-19T08:52:36+00:00"
},
{
"id": 179,
"order": {
"id": 189,
"order_type": 6,
"external_identifier": null,
"external_reference": null,
"merchant": 2,
"cost_centre": null,
"state": "completed",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 105.37,
"subtotal": 89.40865210084,
"total_tax": 15.96537189916,
"total_items_price": 91.19,
"shipping_total": 14.18,
"discount_total": 0,
"promotion_codes": [],
"items": [
309
],
"disposition_order": 179,
"customer": 177,
"shipping_address": 342,
"billing_address": 341,
"whitelabel_address": null,
"payment": null,
"shipments": [
189
],
"created_at": "2024-07-19T08:52:28+00:00",
"updated_at": "2024-07-19T08:52:29+00:00",
"cancelled_at": null,
"ordered_at": "2024-07-19T08:52:29+00:00"
},
"state": "delivered",
"cancelled_at": null,
"created_at": "2024-07-19T08:52:36+00:00",
"updated_at": "2024-07-19T08:52:36+00:00"
},
....
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/disposition-orders?cursor=eyJkaXNwb3NpdGlvbl9vcmRlcnMuaWQiOjE2NywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"
},
"meta": {
"path": "https://api.smake.io/master-administration/disposition-orders",
"per_page": 15,
"next_cursor": "eyJkaXNwb3NpdGlvbl9vcmRlcnMuaWQiOjE2NywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
"prev_cursor": null
}
}
```
#### Available expandable attributes [#available-expandable-attributes]
* order
* order.order\_type
* order.items
* order.disposition\_order
* order.customer
* order.shipping\_address
* order.billing\_address
* order.whitelabel\_address
* order.shipments
* order.merchant
* order.payment
* order.payment.payment\_method
* order.promotion\_codes
## GET [#get]
Return a disposition order of given `order id` = **x**.
Expand can be used here as mentioned before.
### Example of fetching specified disposition order information [#example-of-fetching-specified-disposition-order-information]
Request
```http request
GET /disposition-orders/by-order/191 HTTP/1.1
```
Response
```json
{
"id": 181,
"order": 191,
"state": "manual_assignment_process",
"cancelled_at": null,
"created_at": "2024-07-19T09:00:29+00:00",
"updated_at": "2024-07-19T09:00:31+00:00"
}
```
## POST [#post]
Assign a disposition order of given `order id` = **x** to a production.
### Example of assigning disposition order completely [#example-of-assigning-disposition-order-completely]
Request
```http request
POST /disposition-orders/by-order/191/production-orders HTTP/1.1
{
"productions": [
{
"handle": "production-2"
}
]
}
```
Response
```json
{
"id": 181,
"order": 191,
"state": "assigned",
"cancelled_at": null,
"created_at": "2024-07-19T09:00:29+00:00",
"updated_at": "2024-07-19T09:09:07+00:00"
}
```
### Example of assigning disposition order in detail [#example-of-assigning-disposition-order-in-detail]
Request
```http request
POST /disposition-orders/by-order/191/production-orders HTTP/1.1
{
"productions": [
{
"handle": "production-2",
"order_items": [
{
"external_identifier": "item-1"
}
]
},
{
"handle": "production-3",
"order_items": [
{
"external_identifier": "item-2"
}
]
}
]
}
```
Response
```json
{
"id": 181,
"order": 191,
"state": "partly_assigned",
"cancelled_at": null,
"created_at": "2024-07-19T09:00:29+00:00",
"updated_at": "2024-07-19T09:09:07+00:00"
}
```
# Draft Order Complete (/docs/master/2022-07-01/endpoints/draft-order-complete)
Complete a draft order.
## UPDATE [#update]
### Example of complte a draft order [#example-of-complte-a-draft-order]
Request
```http request
PATCH /draft-orders/1/complete HTTP/1.1
```
Response
```json
HTTP/1.1 202 Accepted
```
Validation Errors
**400 Bad Request**
```text
"Draft order cannot be completed. Unknown error."
```
**Possible causes:**
* An unknown error has occurred, please try again later.
***
**400 Bad Request**
```text
Draft order cannot be completed. Only 'draft' and 'checked' are allowed.
```
**Possible causes:**
* It is not permitted to mark the order as complete, the order status does not allow this.
***
**400 Bad Request**
```text
Conflict: This draft is currently in use and is being imported by another process. Please ensure that you do not import drafts multiple times and wait for the import process to complete until you receive a success or error message.
```
***
**400 Bad Request**
```text
The master has no active productions. Please contact the master to activate the productions.
```
# Good Transfer by Parcel Number (/docs/master/2022-07-01/endpoints/good-transfer-by-parcel-number)
## CREATE BY PARCEL NUMBER [#create-by-parcel-number]
Create a new good transfer by parcel number.
### Request [#request]
| Field | Type | Required |
| --------------------------------- | ------------------------------------------------ | -------- |
| origin | object | yes |
| destination | object | yes |
| creator | object | yes |
| external\_identifier | string | yes |
| estimated\_arrival\_at | date | no |
| goods\_transfer\_parcels\_numbers | array of order\_item\_units.external\_identifier | no |
### Example of creating a new good transfer by parcel number [#example-of-creating-a-new-good-transfer-by-parcel-number]
Request
```http request
POST /goods-transfers/store-with-parcel-numbers HTTP/1.1
{
"origin": {
"resource_type": "tenant-supplier",
"resource": 1
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "staff",
"resource": 1
},
"external_identifier": "WT-123",
"estimated_arrival_at": "2022-12-24",
"goods_transfer_parcel_numbers": [
"P-123"
]
}
```
Response
```json
{
"id": 4,
"state": "pending",
"external_identifier": "WT-123",
"origin": {
"resource_type": "tenant-supplier",
"resource": 1
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "client",
"resource": 1
},
"estimated_arrival_at": "2022-11-22T00:00:00.000000Z",
"parcels": [
{
"id": 5,
"state": "pending",
"tracking_number": "P-123",
"external_identifier": null,
"goods_transfer_items": [
{
"id": 1,
"state": "pending",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-17T10:55:09+00:00",
"updated_at": "2023-01-17T10:55:09+00:00"
}
],
"created_at": "2023-01-22T14:50:39+00:00",
"updated_at": "2023-01-22T14:50:39+00:00"
}
],
"created_at": "2023-01-22T14:50:39+00:00",
"updated_at": "2023-01-22T14:50:39+00:00"
}
```
# Good Transfer (/docs/master/2022-07-01/endpoints/good-transfer)
Fetching list of good transfer list.
## LIST [#list]
Return a collection of good transfer.
### Example of fetching good transfer list [#example-of-fetching-good-transfer-list]
Request
```http request
GET /goods-transfers HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"state": "pending",
"external_identifier": "GT1-1",
"origin": {
"resource_type": "tenant-supplier",
"resource": 4
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "staff",
"resource": 1
},
"estimated_arrival_at": "2023-01-12T00:00:00.000000Z",
"parcels": [
{
"id": 1,
"state": "pending",
"tracking_number": "623",
"external_identifier": "GTP1-1",
"goods_transfer_items": [
{
"id": 1,
"state": "pending",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 2,
"state": "pending",
"resource_type": "stock-item",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"state": "pending",
"resource_type": "production-variant",
"resource": 10,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 2,
"state": "pending",
"external_identifier": "GT1-2",
"origin": {
"resource_type": "tenant-supplier",
"resource": 4
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "staff",
"resource": 1
},
"estimated_arrival_at": "2023-01-14T00:00:00.000000Z",
"parcels": [
{
"id": 2,
"state": "partially-received",
"tracking_number": "932",
"external_identifier": "GTP2-2",
"goods_transfer_items": [
{
"id": 4,
"state": "accepted",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 5,
"state": "pending",
"resource_type": "stock-item",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 6,
"state": "rejected",
"resource_type": "production-variant",
"resource": 10,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"state": "pending",
"tracking_number": "173",
"external_identifier": "GTP3-3",
"goods_transfer_items": [
{
"id": 7,
"state": "pending",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 4,
"state": "received",
"tracking_number": "808",
"external_identifier": "GTP3-4",
"goods_transfer_items": [
{
"id": 8,
"state": "accepted",
"resource_type": "stock-item",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 9,
"state": "rejected",
"resource_type": "production-variant",
"resource": 10,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"state": "partially-received",
"external_identifier": "GT1-3",
"origin": {
"resource_type": "tenant-supplier",
"resource": 4
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "staff",
"resource": 1
},
"estimated_arrival_at": "2023-01-11T00:00:00.000000Z",
"parcels": [],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/goods-transfers",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a good transfer of given `id` = **x**.
### Example of fetching specified good transfer information [#example-of-fetching-specified-good-transfer-information]
Request
```http request
GET /good-transfers/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"state": "pending",
"external_identifier": "GT1-1",
"origin": {
"resource_type": "tenant-supplier",
"resource": 4
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "staff",
"resource": 1
},
"estimated_arrival_at": "2023-01-12T00:00:00.000000Z",
"parcels": [
{
"id": 1,
"state": "pending",
"tracking_number": "623",
"external_identifier": "GTP1-1",
"goods_transfer_items": [
{
"id": 1,
"state": "pending",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 2,
"state": "pending",
"resource_type": "stock-item",
"resource": 1,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"state": "pending",
"resource_type": "production-variant",
"resource": 10,
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
```
## CREATE [#create]
Create a new good transfer.
### States [#states]
The current state of the asynchronous process is represented due following states:
| State | Meaning |
| ------------------- | ---------------------------------------------- |
| `Pending` | The initial state of a new good transfer data. |
| `PartiallyReceived` | Partial goods are recieved recieved |
| `Received` | All good are recieved. |
### Request [#request]
| Field | Type | Required |
| ------------------------ | ----------------- | -------- |
| origin | object | yes |
| destination | object | yes |
| creator | object | yes |
| external\_identifier | string | yes |
| estimated\_arrival\_at | date | no |
| goods\_transfer\_parcels | object collection | no |
### Example of creating a new good transfer [#example-of-creating-a-new-good-transfer]
Request
```http request
POST /good-transfers HTTP/1.1
{
"external_identifier": "WT-123",
"origin": {
"resource_type": "tenant-supplier",
"resource": 1,
},
"destination": {
"resource_type": "production",
"resource": 1,
},
"creator": {
"resource_type": "client",
"resource": 1,
},
"estimated_arrival_at": "2022-11-22",
"goods_transfer_parcels": [
{
"tracking_number": "P-123",
"goods_transfer_items": [
{
"resource_type": "id-tag",
"resource": {
"id": 1
}
}
...
]
}
]
}
```
Response
```json
{
"id": 4,
"state": "pending",
"external_identifier": "WT-123",
"origin": {
"resource_type": "tenant-supplier",
"resource": 1
},
"destination": {
"resource_type": "production",
"resource": 1
},
"creator": {
"resource_type": "client",
"resource": 1
},
"estimated_arrival_at": "2022-11-22T00:00:00.000000Z",
"parcels": [
{
"id": 1,
"state": "pending",
"tracking_number": "P-123",
"external_identifier": null,
"goods_transfer_items": [
{
"id": 1,
"state": "pending",
"resource_type": "id-tag",
"resource": 1,
"created_at": "2023-01-17T10:55:09+00:00",
"updated_at": "2023-01-17T10:55:09+00:00"
}
],
"created_at": "2023-01-22T14:50:39+00:00",
"updated_at": "2023-01-22T14:50:39+00:00"
}
],
"created_at": "2023-01-22T14:50:39+00:00",
"updated_at": "2023-01-22T14:50:39+00:00"
}
```
# Id Tags (/docs/master/2022-07-01/endpoints/id-tag)
Fetching list of id tags.
## LIST [#list]
Returns a collection of id tags.
### Example of fetching id tag list [#example-of-fetching-id-tag-list]
Request
```http request
GET /id-tags HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"order_item_unit": 1,
"media": [
1,
],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
},
{
"id": 2,
"order_item_unit": 2,
"media": [
2,
],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/id-tags?cursor=eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/id-tags",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
}
```
### Filtering [#filtering]
You can filter your results as follows:
#### List id tags for specified external reference of order item unit [#list-id-tags-for-specified-external-reference-of-order-item-unit]
* `/id-tags?filter[order_item_unit.external_reference]=P-123`
### Expand relation [#expand-relation]
To get a expanded relations please take a look into [Expanding objects](../basic/expanding-objects).
Allowed expansion `order_item_unit`, `media`
### Example of expanded relation [#example-of-expanded-relation]
Request
```http request
GET /id-tags?expand=order_item_unit HTTP/1.1
```
Response
```json
{
data: [
{
"id": 1,
"order_item_unit": {
"id": 1,
"external_reference": "P-123",
"merchant": 1,
"order": 1,
"order_item": 1,
"merchant_variant": 100,
"id_tag": 1,
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:33+00:00"
},
"media": [],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
},
{
"id": 2,
"order_item_unit": {
"id": 2,
"external_reference": "P-456",
"merchant": 1,
"order": 2,
"order_item": 2,
"merchant_variant": 200,
"id_tag": 2,
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:33+00:00"
},
"media": [],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/id-tags?cursor=eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/id-tags",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
}
```
## GET [#get]
Return a id tag of given `id` = **x**.
### Example of fetching specified id tag information [#example-of-fetching-specified-id-tag-information]
Request
```http request
GET /id-tags/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"order_item_unit": 1,
"media": [],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
```
## Mark as printed [#mark-as-printed]
To mark an id tag as printed. This can be used if the id tag is printed outside of the smake production.
### Example of marking an id tag as printed [#example-of-marking-an-id-tag-as-printed]
Request
```http request
PATCH /id-tags/1/printed HTTP/1.1
{}
```
Response
```http response
HTTP/1.1 200 OK
{
"id": 1,
"order_item_unit": 1,
"media": [],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
```
Validation Errors
If an id tag has already been printed, a validation error is returned:
```http response
HTTP/1.1 422 Unprocessable Entity
{
"message": "The id tag has already been printed.",
}
```
# Job Statuses (/docs/master/2022-07-01/endpoints/job)
Fetching list of master job statuses.
## LIST [#list]
Return a collection of master job statuses.
### Example of fetching master job statuses list [#example-of-fetching-master-job-statuses-list]
Request
```http request
GET /jobs HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"type": "calculate-shipping-rates",
"status": "finished",
"started_at": "2026-02-26 16:22:08",
"finished_at": "2026-02-26 16:22:08",
"created_at": "2026-02-26 16:22:05"
},
{
"id": 2,
"type": "calculate-shipping-rates",
"status": "failed",
"started_at": "2026-02-24 16:43:09",
"finished_at": "2026-02-24 16:43:09",
"created_at": "2026-02-24 16:43:04"
}
],
"links": [],
"meta": {
"path": "https://api.smake.io/master-administration/jobs",
"per_page": 15,
"next_cursor": null,
"next_page_url": null,
"prev_cursor": null,
"prev_page_url": null
}
}
```
## GET [#get]
Returns a master job of given `id` = **x**.
### Example of fetching specified master job statuse information [#example-of-fetching-specified-master-job-statuse-information]
Request
```http request
GET /jobs/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"type": "calculate-shipping-rates",
"status": "finished",
"started_at": "2026-02-26 16:22:08",
"finished_at": "2026-02-26 16:22:08",
"created_at": "2026-02-26 16:22:05"
}
```
# Logo Color (/docs/master/2022-07-01/endpoints/logo-color)
Fetching list of logo color data.
## LIST [#list]
Return a collection of logo color.
### Filtering [#filtering]
You can filter your results as follows:
##### List of logo colors for specific id(s) [#list-of-logo-colors-for-specific-ids]
* `/logo-colors?filter[id]=1`
* `/logo-colors?filter[id]=1,2,3`
##### List of logo colors for specific handle(s) [#list-of-logo-colors-for-specific-handles]
* `/logo-colors?filter[handle]=B`
* `/logo-colors?filter[handle]=B,I`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
##### Expand logo-colors [#expand-logo-colors]
You can show the content of the logo colors instead of the `id`.
* `/logo-colors?expand=color_type`
### Available expandable attributes [#available-expandable-attributes]
* color\_type
* color\_details
* manufacturer
### Example of fetching logo color list [#example-of-fetching-logo-color-list]
Request
```http request
GET /logo-colors HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 52,
"handle": "DarkSlateBlue",
"collection_name": "thread",
"name": {
"de": "DarkBlue",
"en": "AntiqueWhite"
},
"production_name": null,
"hex": "FF0000",
"pantone": null,
"ral": null,
"hks": null,
"hks_percent": null,
"red": 255,
"green": 0,
"blue": 0,
"cyan": null,
"magenta": null,
"yellow": null,
"black": null,
"color_type": {
"id": 1,
"handle": "thread",
"collection_name": "embroidery",
"name": {
"ar": "الخيط",
"de": "Garn",
"en": "Thread",
"es": "Hilo",
"fr": "Fil",
"it": "Filato",
"ja": "糸",
"ko": "광택사",
"nl": "Garen",
"pl": "Sieć",
"sv": "Garn",
"tr": "İplik"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"color_details": 18,
"manufacturer": null,
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
},
{
"id": 51,
"handle": "Black",
"collection_name": "print_color",
"name": {
"de": "Mandarine"
},
"production_name": null,
"hex": "ce5c19",
"pantone": "159",
"ral": "8001",
"hks": "8",
"hks_percent": 100,
"red": 206,
"green": 92,
"blue": 25,
"cyan": 0,
"magenta": 56,
"yellow": 88,
"black": 19,
"color_type": {
"id": 2,
"handle": "print_color",
"collection_name": "kornit",
"name": {
"ar": "طباعة",
"de": "Druck",
"en": "Print",
"es": "Presión",
"fr": "Imprimer",
"it": "Stampa",
"ja": "プリント",
"ko": "인쇄",
"nl": "Druk",
"pl": "Drukuj",
"sv": "Tryck",
"tr": "Baskı"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"color_details": null,
"manufacturer": null,
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
.......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/logo-colors?cursor=eyJ0ZW5hbnRfbG9nb19jb2xvcnMuaWQiOjM4LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://api.smake.io/master-administration/logo-colors",
"per_page": 15,
"next_cursor": "eyJ0ZW5hbnRfbG9nb19jb2xvcnMuaWQiOjM4LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
```
## GET [#get]
Return a logo color of given `id` = **x**.
### Expanding relationships [#expanding-relationships-1]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
##### Expand logo-colors [#expand-logo-colors-1]
You can show the content of the logo colors instead of the `id`.
* `/logo-colors?expand=color_type`
#### Available expandable attributes [#available-expandable-attributes-1]
* color\_type
* color\_details
* manufacturer
### Example of fetching specified logo color information [#example-of-fetching-specified-logo-color-information]
Request
```http request
GET /logo-colors/52 HTTP/1.1
```
Response
```json
{
"id": 52,
"handle": "DarkSlateBlue",
"collection_name": "thread",
"name": {
"de": "DarkBlue",
"en": "AntiqueWhite"
},
"production_name": null,
"hex": "FF0000",
"pantone": null,
"ral": null,
"hks": null,
"hks_percent": null,
"red": 255,
"green": 0,
"blue": 0,
"cyan": null,
"magenta": null,
"yellow": null,
"black": null,
"color_type": {
"id": 1,
"handle": "thread",
"collection_name": "embroidery",
"name": {
"ar": "الخيط",
"de": "Garn",
"en": "Thread",
"es": "Hilo",
"fr": "Fil",
"it": "Filato",
"ja": "糸",
"ko": "광택사",
"nl": "Garen",
"pl": "Sieć",
"sv": "Garn",
"tr": "İplik"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"color_details": 18,
"manufacturer": null,
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
}
```
# Media (/docs/master/2022-07-01/endpoints/media)
If a media could not be processed, the order may not be produced. Individual media items can be reprocessed via this update endpoint.
One possible reason why the media could not be processed is that it could not be read from the URL because the server was or is unreachable.
## UPDATE MEDIA [#update-media]
Update media files
### Example of update media file [#example-of-update-media-file]
Request
```http request
PUT /async/media/update
{
"media": [
{
"id": 1,
"requested":
{
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/testfiles/logo.png",
"collection": "view-image"
}
}
]
}
```
Response
```json
{
"successful": {
"message": "The following media entries have been successfully adjusted",
"successful_entries": [
1
]
}
}
```
Validation Errors
**200 OK – Some Media could not be updated**
```json
{
"message": "Some Media could not be updated",
"failed_entries": {
"Media has not valid state (failed or ready)": [
1
]
}
}
```
**Possible causes:**
* See message in failed entries.
***
**400 Bad Request – Media Models Not Found**
```json
{
"message": "No results found for Media"
}
```
**Possible causes:**
* The id value in body does not point to a valid Media entry or is invalid.
***
**500 Internal Server Error – Media could not be updated**
```json
{
"message": "Media could not be updated"
}
```
**Possible causes:**
* Internal server error
* Faulty system dependency
* Database or service outage
> Note: The error is automatically recorded and reported on the server side.
# Merchant Product Import (/docs/master/2022-07-01/endpoints/merchant-product-importer)
This documentation describes the technical process for importing merchant product data using the API.
## Step-by-Step Process [#step-by-step-process]
Generate Signed Upload URL
### Get Upload URL [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/csv",
"file_name": "example.csv"
}
```
Response - 201 Created
```json
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/tmp/d24c7338-5e ...",
"headers": {
"Content-Type": "text/csv"
}
}
```
**Note:** The upload URL is valid for **10 minutes**. Save the **path** value from the response – you will need it when creating the import.
### Upload Content [#upload-content]
Upload the Content
Request
```http request
PUT /temporary-upload-url?... HTTP/1.1
Content-Type: text/plain
merchant_handle,master_variant_sku,external_identifier,merchant_product_handle,published,is_master,price,tax_rate,name,locale
normal-shop,production-variant-360,7600532#1517120-2-0,47110815,yes,yes,13.00,19.00,Rudi das Pferd,de
```
Response
```http
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
### Create a new import [#create-a-new-import]
Creates a new asynchronous import of merchant products based on a CSV file uploaded to S3.
##### Parameters for creating a product import [#parameters-for-creating-a-product-import]
| Field | Type | Description | Required |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | -------- |
| path | string | A path of csv file uploaded to S3 | Yes |
| should\_preserve\_published | boolean | If the switch is set to true, the publishing settings for existing articles from the CSV file will be ignored. | No |
Request
```http request
POST /merchant-product-imports HTTP/1.1
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"should_preserve_published": false
}
```
Response
```http response
HTTP/1.1 202 Accepted
Location: /merchant-product-imports/1
```
**Note:** The import runs asynchronously. Use the Location header to poll the import status.
### Check Import Status [#check-import-status]
Returns a result of product import with the given `id` = **x**.
Request
```http request
GET /merchant-product-imports/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"options": {
"should_preserve_published": false
},
"state": "finished",
"failure_message": null,
"total_rows": 24,
"failed_rows": 0,
"processed_rows": 24,
"ignored_rows": 0,
"started_at": "2026-02-18T10:35:32+00:00",
"finished_at": "2026-02-18T10:36:15+00:00",
"source_file": {
"id": 5416,
"collection_name": "source-file",
"file_name": "product-import-example.csv",
"size": 14397,
"mime_type": "text/plain",
"download_url": "https://api.smake.io/storage/files/fb9c8ddc270843c7aaadcbd383fbaa2c/example.csv?expires=1768396599&signature=ed46888300b586baa5f31835b8a44ddddaf36cfc9ac22a42f38cf7b9fe0c09c3",
"state": null,
"requested": null,
"failure_message": null,
"created_at": "2026-02-18T10:35:29+00:00",
"updated_at": "2026-02-18T10:35:29+00:00"
},
"failed_report_file": null,
"created_at": "2026-02-18T10:35:29+00:00",
"updated_at": "2026-02-18T10:36:15+00:00"
}
```
**Note:** If not all data was processed successfully, the field `failed_report_file` will be filled and you can download an error report to check where the error lies.
### Example Import File [#example-import-file]
```csv
merchant_handle,master_variant_sku,external_identifier,merchant_product_handle,published,is_master,price,tax_rate,name,locale
normal-shop,production-variant-360,7600532#1517120-2-0,47110815,yes,yes,13.00,19.00,Rudi das Pferd,de
normal-shop,production-variant-360,7600532#1517120-2-0,47110815,yes,yes,13.00,19.00,Rudi the Horse,en
normal-shop,production-variant-360,7600532#1517120-2-0,47110815,yes,yes,13.00,19.00,Rudi le cheval,fr
normal-shop,production-variant-360,7600532#1517120-2-1,47110816,yes,yes,25.00,19.00,Otto die Katze,de
normal-shop,production-variant-360,7600532#1517120-2-1,47110816,yes,yes,25.00,19.00,Otto the Cat,en
normal-shop,production-variant-360,7600532#1517120-2-3,47110817,yes,yes,25.00,19.00,Garfield the Cat,en
normal-shop,production-variant-360,7600532#1517120-2-4,47110818,yes,yes,25.00,19.00,Simon die Armeise,de
normal-shop,production-variant-405,merchant-product-6-red-XXXL,08154711,yes,no,25.00,19.00,Simon die Maus,de
normal-shop,production-variant-360,7600532#1517120-2-5,47110819,yes,yes,25.00,19.00,Peter der Hosh,de
```
# Merchant Product (/docs/master/2022-07-01/endpoints/merchant-product)
Fetching list of merchant products.
## LIST [#list]
Returns a collection of merchant products.
### Filtering [#filtering]
You can filter your results as follows:
##### List of merchant products for specific id(s) [#list-of-merchant-products-for-specific-ids]
* `/merchant-products?filter[id]=1`
* `/merchant-products?filter[id]=1,2,3`
##### List of merchant products for specific merchant(s) [#list-of-merchant-products-for-specific-merchants]
* `/merchant-products?filter[merchant]=1`
* `/merchant-products?filter[merchant]=1,2`
##### List of merchant products for specific master product handle(s) [#list-of-merchant-products-for-specific-master-product-handles]
* `/merchant-products?filter[master_product.handle]=B`
* `/merchant-products?filter[master_product.handle]=B,I`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
##### Expand merchant product [#expand-merchant-product]
You can show the content of the merchant for a product instead of the `id`.
* `/merchant-products?expand=merchant`
### Available expandable attributes [#available-expandable-attributes]
* merchant
* scale\_factors
* production\_areas
* positioning\_areas
* merchant\_variants
* master\_product
### Example of fetching merchant product list [#example-of-fetching-merchant-product-list]
Request
```http request
GET /merchant-products HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"merchant": 1,
"title": {
"de": "T-Shirt 1",
"en": "T-Shirt 1"
},
"is_available": false,
"available_at": "2023-03-06T07:09:42+00:00",
"discontinue_at": null,
"master_product": 7,
"designer": null,
"scale_factors": [],
"production_areas": [],
"positioning_areas": [],
"merchant_variants": [
1,
2
],
"created_at": "2023-03-06T07:09:42+00:00",
"updated_at": "2023-03-06T07:09:42+00:00"
},
{
"id": 2,
"merchant": 1,
"title": {
"de": "T-Shirt 2",
"en": "T-Shirt 2"
},
"is_available": false,
"available_at": "2023-03-06T07:09:42+00:00",
"discontinue_at": null,
"master_product": 7,
"designer": null,
"scale_factors": [],
"production_areas": [],
"positioning_areas": [],
"merchant_variants": [
3,
4
],
"created_at": "2023-03-06T07:09:42+00:00",
"updated_at": "2023-03-06T07:09:42+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/merchant-products?cursor=eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/merchant-products",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
}
```
## GET [#get]
Returns a merchant product of given `id` = **x**.
### Example of fetching specified merchant product information [#example-of-fetching-specified-merchant-product-information]
Request
```http request
GET /merchant-products/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"merchant": 1,
"title": {
"de": "T-Shirt 1",
"en": "T-Shirt 1"
},
"is_available": false,
"available_at": "2023-03-06T07:09:42+00:00",
"discontinue_at": null,
"master_product": 7,
"designer": null,
"scale_factors": [],
"production_areas": [],
"positioning_areas": [],
"merchant_variants": [
1,
2,
],
"created_at": "2023-03-06T07:09:42+00:00",
"updated_at": "2023-03-06T07:09:42+00:00"
}
```
### Expanding relationships [#expanding-relationships-1]
To get a expanded relations please take a look into [Expanding objects](../basic/expanding-objects).
Allowed expansion `merchant`, `scale_factors`, `merchant_variants`, `production_areas`, `positioning_areas` and `master_product`.
### Example of expanded relation [#example-of-expanded-relation]
Request
```http request
GET /merchant-products/1?expand=merchant HTTP/1.1
```
Response
```json
{
"id": 1,
"merchant": {
"id": 1,
"name": "earum",
"created_at": "2023-03-06T07:09:12+00:00",
"updated_at": "2023-03-06T07:09:44+00:00"
},
"title": {
"de": "T-Shirt 13 pattern boxed",
"en": "T-Shirt 13 pattern boxed"
},
...
}
```
## CREATE [#create]
Create a new Merchant Product.
### Attributes [#attributes]
| Field | Type | Description | Required |
| ------------------ | -------- | -------------------------------------------------------------------------- | -------- |
| title | json | A json object of localized title. | No |
| description | json | A json object of localized description. | No |
| available\_at | datetime | UTC Datetime format | No |
| discontinue\_at | datetime | UTC Datetime format | No |
| merchant | array | An array of [Merchant Object](#content-merchant-object). | No |
| master\_product | array | An array of [Master Product Object](#content-master-product-object). | No |
| merchant\_variants | array | An array of [Merchant Variants Object](#content-merchant-variants-object). | No |
### Merchant Object [#merchant-object]
[Back to Attributes](#content-attributes)
| Field | Type | Description | Required |
| ----- | ------- | ----------------------------------------------------------------- | -------- |
| id | integer | The merchant id to which the merchant product should be assigned. | Yes |
### Master Product Object [#master-product-object]
[Back to Attributes](#content-attributes)
| Field | Type | Description | Required |
| ----- | ------- | ---------------------------------------------------------- | -------- |
| id | integer | The master product id from which the data should be taken. | Yes |
[Back to Attributes](#content-attributes)
### Merchant Variants Object [#merchant-variants-object]
| Field | Type | Description | Required |
| -------------------- | ------ | -------------------------------------------------------------------- | -------- |
| external\_identifier | string | A string for external identifier | No |
| master\_variant | array | An array of [Master Variant Object](#content-master-variant-object). | Yes |
[Back to Attributes](#content-attributes)
### Master Variant Object [#master-variant-object]
| Field | Type | Description | Required |
| ----- | ------- | ------------------- | -------- |
| id | integer | Master Variant `id` | No |
| sku | string | A string for SKU | No |
[Back to Attributes](#content-attributes)
### Example of creating a new merchant product [#example-of-creating-a-new-merchant-product]
Request
```http request
POST /merchant-products HTTP/1.1
{
"merchant": {
"id": 1
},
"master_product": {
"id": 8
},
"merchant_variants": [
{
"external_identifier": "2026-X-0001",
"master_variant": {
"id": 1
}
},
{
"external_identifier": "2026-X-0002",
"master_variant": {
"id": 2
}
}
]
}
```
Response
```json
{
"id": 1,
"merchant": 1,
"title": {
"de": "T-Shirt designbar",
"en": "T-Shirt designable"
},
"is_available": false,
"available_at": null,
"discontinue_at": null,
"master_product": 1,
"designer": null,
"scale_factors": [
1
],
"production_areas": [
1,
2,
3,
4,
5
],
"positioning_areas": [
1,
2,
3,
4,
5
],
"merchant_variants": [
2,
3
],
"created_at": "2026-02-04T12:40:07+00:00",
"updated_at": "2026-02-04T12:40:07+00:00"
}
```
## UPDATE [#update]
Update an existing Merchant Product.
### Attributes [#attributes-1]
| Field | Type | Description | Required |
| --------------- | -------- | -------------------------------------------------------- | -------- |
| title | json | A json object of localized title. | No |
| description | json | A json object of localized description. | No |
| available\_at | datetime | UTC Datetime format | No |
| discontinue\_at | datetime | UTC Datetime format | No |
| designer | array | An array of [Designer Object](#content-designer-object). | No |
### Designer Object [#designer-object]
[Back to Attributes](#content-attributes)
| Field | Type | Description | Required |
| --------------------------- | ------- | ---------------------------------------------- | -------- |
| type | string | Allowed types `none`, `default`, `detail-page` | Yes |
| only\_customized\_orderable | boolean | Is merchant product only customized orderable | Yes |
### Example of updating an existing merchant product [#example-of-updating-an-existing-merchant-product]
Request
```http request
PATCH /merchant-products/1 HTTP/1.1
{
"title": {
"de": "T-Shirt",
"en": "T-Shirt"
},
"description": {
"de": "T-Shirt",
"en": "T-Shirt"
},
"available_at": "2026-02-04 11:00:00",
"discontinue_at": "2026-02-04 13:00:00",
"designer": {
"type": "none",
"only_customized_orderable": false
}
}
```
Response
```json
{
"id": 1,
"merchant": 1,
"title": {
"de": "T-Shirt",
"en": "T-Shirt"
},
"is_available": false,
"available_at": null,
"discontinue_at": null,
"master_product": 1,
"designer": null,
"scale_factors": [
1
],
"production_areas": [
1,
2,
3,
4,
5
],
"positioning_areas": [
1,
2,
3,
4,
5
],
"merchant_variants": [
2,
3
],
"created_at": "2026-02-04T12:00:00+01:00",
"updated_at": "2026-02-04T14:00:00+01:00"
}
```
# Merchant Variant (/docs/master/2022-07-01/endpoints/merchant-variant)
Fetching list of merchant variants.
## LIST [#list]
Returns a collection of merchant variant.
### Filtering [#filtering]
You can filter your results as follows:
##### List of merchant variant for specific id(s) [#list-of-merchant-variant-for-specific-ids]
* `/merchant-variants?filter[id]=1`
* `/merchant-variants?filter[id]=1,2,3`
##### List of merchant variant for specific collection(s) [#list-of-merchant-variant-for-specific-collections]
* `/merchant-variants?filter[collection_name]=catalogue`
* `/merchant-variants?filter[collection_name]=catalogue,custom,ordered`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
##### Expand merchant variant [#expand-merchant-variant]
You can show the content of the merchant for a variant instead of the `id`.
* `/merchant-variants?expand=merchant`
### Available expandable attributes [#available-expandable-attributes]
* merchant
* master\_variant
### Example of fetching merchant variant list [#example-of-fetching-merchant-variant-list]
Request
```http request
GET /merchant-variants HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"merchant": 1,
"external_identifier": null,
"is_available": false,
"discontinue_at": null,
"merchant_product": 1,
"master_variant": 1,
"option_values": [
{
"id": 1,
"handle": "lime",
"name": {
"de": "Limette",
"en": "lime"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "Farbe",
"en": "Color"
},
"created_at": "2023-03-06T07:09:12+00:00",
"updated_at": "2023-03-06T07:09:12+00:00"
},
"media": [],
"created_at": "2023-03-06T07:09:20+00:00",
"updated_at": "2023-03-06T07:09:20+00:00"
},
{
"id": 2,
"handle": "58",
"name": {
"de": "58",
"en": "58"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "Größe",
"en": "Size"
},
"created_at": "2023-03-06T07:09:12+00:00",
"updated_at": "2023-03-06T07:09:12+00:00"
},
"media": [],
"created_at": "2023-03-06T07:09:43+00:00",
"updated_at": "2023-03-06T07:09:43+00:00"
}
],
"designer": {
"type": "none",
"modes": {
"free": true,
"positioning": true,
"production": false
},
"only_customized_orderable": false
},
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 1,
"collection_name": "view-image",
"file_name": "view-image-front-lime.png",
"size": 66200,
"mime_type": "image/png",
"download_url": "https://cdn.url/image-front-lime.png",
"state": "ready",
"requested": null,
"failure_message": null,
"created_at": "2023-03-06T07:09:42+00:00",
"updated_at": "2023-03-06T07:09:42+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Ansicht hinten",
"media": [],
"customizations": []
},
{
"handle": "left",
"name": "Ansicht links",
"media": [],
"customizations": []
},
{
"handle": "right",
"name": "Ansicht rechts",
"media": [],
"customizations": []
}
],
"created_at": "2023-03-06T07:09:44+00:00",
"updated_at": "2023-03-06T07:09:44+00:00"
},
{
"id": 2,
...
},
{
"id": 3,
...
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/merchant-variants?cursor=eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/merchant-variants",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
}
```
## GET [#get]
Returns a merchant variant of given `id` = **x**.
### Example of fetching specified merchant variant information [#example-of-fetching-specified-merchant-variant-information]
Request
```http request
GET /merchant-variants/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"merchant": 1,
"external_identifier": null,
"is_available": false,
"discontinue_at": null,
"merchant_product": 1,
"master_variant": 1,
"option_values": [
{
"id": 1,
"handle": "lime",
"name": {
"de": "Limette",
"en": "lime"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "Farbe",
"en": "Color"
},
"created_at": "2023-03-06T07:09:12+00:00",
"updated_at": "2023-03-06T07:09:12+00:00"
},
"media": [],
"created_at": "2023-03-06T07:09:20+00:00",
"updated_at": "2023-03-06T07:09:20+00:00"
},
{
"id": 2,
"handle": "58",
"name": {
"de": "58",
"en": "58"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "Größe",
"en": "Size"
},
"created_at": "2023-03-06T07:09:12+00:00",
"updated_at": "2023-03-06T07:09:12+00:00"
},
"media": [],
"created_at": "2023-03-06T07:09:43+00:00",
"updated_at": "2023-03-06T07:09:43+00:00"
}
],
"designer": {
"type": "none",
"modes": {
"free": true,
"positioning": true,
"production": false
},
"only_customized_orderable": false
},
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 1,
"collection_name": "view-image",
"file_name": "view-image-front-lime.png",
"size": 66200,
"mime_type": "image/png",
"download_url": "https://cdn.url/image-front-lime.png",
"state": "ready",
"requested": null,
"failure_message": null,
"created_at": "2023-03-06T07:09:42+00:00",
"updated_at": "2023-03-06T07:09:42+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Ansicht hinten",
"media": [],
"customizations": []
},
{
"handle": "left",
"name": "Ansicht links",
"media": [],
"customizations": []
},
{
"handle": "right",
"name": "Ansicht rechts",
"media": [],
"customizations": []
}
],
"created_at": "2023-03-06T07:09:44+00:00",
"updated_at": "2023-03-06T07:09:44+00:00"
}
```
### Expanding relationships [#expanding-relationships-1]
To get a expanded relations please take a look into [Expanding objects](../basic/expanding-objects).
Allowed expansion `merchant` and `master_variant`.
### Example of expanded relation [#example-of-expanded-relation]
Request
```http request
GET /merchant-variants/1?expand=merchant HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"merchant": {
"id": 1,
"name": "Shop",
"created_at": "2026-02-19T08:47:43+00:00",
"updated_at": "2026-02-19T08:48:57+00:00"
},
"external_identifier": "merchant-product-1-yellow-XS",
"is_available": true,
"discontinue_at": null,
...
}
]
}
```
## UPDATE [#update]
Update an existing Merchant Variant.
### Attributes [#attributes]
| Field | Type | Description | Required |
| -------------------- | -------- | --------------------------------------- | -------- |
| external\_identifier | string | Unique identifier for the intended use. | No |
| discontinue\_at | datetime | UTC Datetime format | No |
### Example of updating an existing merchant variant [#example-of-updating-an-existing-merchant-variant]
Request
```http request
PATCH /merchant-variants/1 HTTP/1.1
{
"external_identifier": "1234567890",
"available_at": "2026-02-04 11:00:00",
}
```
Response
```json
{
"id": 1,
"merchant": 1,
"external_identifier": "test-1234",
"is_available": false,
"discontinue_at": null,
"merchant_product": 33,
"master_variant": 1023,
"option_values": [
{
"id": 11,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "Farbe",
"en": "Color"
},
"created_at": "2026-02-20T08:15:38+00:00",
"updated_at": "2026-02-20T08:15:38+00:00"
},
"media": [
658
],
"created_at": "2026-02-20T08:15:45+00:00",
"updated_at": "2026-02-20T08:15:45+00:00"
},
{
"id": 73,
"handle": "58N",
"name": {
"de": "58N",
"en": "58N"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "Größe",
"en": "Size"
},
"created_at": "2026-02-20T08:15:38+00:00",
"updated_at": "2026-02-20T08:15:38+00:00"
},
"media": [],
"created_at": "2026-02-20T08:17:42+00:00",
"updated_at": "2026-02-20T08:17:42+00:00"
}
],
"designer": {
"type": "none",
"modes": {
"free": false,
"positioning": false,
"production": false
},
"only_customized_orderable": false
},
"views": [
{
"handle": "front",
"name": "Ansicht vorne",
"media": [
{
"id": 5167,
"collection_name": "view-image",
"file_name": "view-image-front-white.png",
"size": 29497,
"mime_type": "image/png",
"download_url": "https://api.smake.test/storage/files/2b7316ffed3a44898fa8fef6ebd89c76/view-image-front-white.png?expires=1772187214&signature=436d16313f880a9ba5a7692501dcebf819e4365185dc62bfceda23d9c7208dc6",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2026-02-20T08:17:29+00:00",
"updated_at": "2026-02-20T08:17:29+00:00"
}
],
"customizations": []
},
{
"handle": "back",
"name": "Ansicht hinten",
"media": [
{
"id": 5168,
"collection_name": "view-image",
"file_name": "view-image-back-white.png",
"size": 22290,
"mime_type": "image/png",
"download_url": "https://api.smake.test/storage/files/13a9746da9b4489ba362a48769ad5161/view-image-back-white.png?expires=1772187214&signature=db48ac1e05b490fe3d8bdcb5069f93aa70666d49917d7862be7efcdb85da33a9",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2026-02-20T08:17:29+00:00",
"updated_at": "2026-02-20T08:17:29+00:00"
}
],
"customizations": []
},
{
"handle": "left",
"name": "Ansicht links",
"media": [
{
"id": 5169,
"collection_name": "view-image",
"file_name": "view-image-left-white.png",
"size": 16584,
"mime_type": "image/png",
"download_url": "https://api.smake.io/storage/files/79dd568d05ed41058f857c2d4506cfb2/view-image-left-white.png?expires=1772187214&signature=fef93f6345c1fa3e508e4794cb6df17dc08e5c85054f7bd5e936141ae3be05b8",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2026-02-20T08:17:29+00:00",
"updated_at": "2026-02-20T08:17:29+00:00"
}
],
"customizations": []
},
{
"handle": "right",
"name": "Ansicht rechts",
"media": [
{
"id": 5170,
"collection_name": "view-image",
"file_name": "view-image-right-white.png",
"size": 17038,
"mime_type": "image/png",
"download_url": "https://api.smake.io/storage/files/d8001089a68c4e34b25f18ae47a95217/view-image-right-white.png?expires=1772187214&signature=4c029424b81d0136fada2474bd0c189b666979f8dd46a67dfc7d43bb7a765e83",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2026-02-20T08:17:29+00:00",
"updated_at": "2026-02-20T08:17:29+00:00"
}
],
"customizations": []
}
],
"collection_name": "catalogue",
"created_at": "2026-02-20T08:17:42+00:00",
"updated_at": "2026-02-20T10:13:34+00:00"
}
```
# Merchant (/docs/master/2022-07-01/endpoints/merchant)
Fetching list of merchants.
## LIST [#list]
Returns a collection of merchants.
### Example of fetching merchants list [#example-of-fetching-merchants-list]
Request
```http request
GET /merchants HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"name": "Demo Shop",
"created_at": "2026-01-28T12:00:11+00:00",
"updated_at": "2026-01-28T12:01:04+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/merchants",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Returns a merchant of given `id` = **x**.
### Example of fetching specified merchant information [#example-of-fetching-specified-merchant-information]
Request
```http request
GET /merchants/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"name": "Demo Shop",
"created_at": "2026-01-28T12:00:11+00:00",
"updated_at": "2026-01-28T12:01:04+00:00"
}
```
# Order Item Units (/docs/master/2022-07-01/endpoints/order-item-unit)
Fetching list of order item units.
## LIST [#list]
Return a collection of order item units.
### Example of fetching order item units list [#example-of-fetching-order-item-units-list]
Request
```http request
GET /order-item-units HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"external_identifier": "P-123",
"external_reference": "P-123",
"merchant": 1,
"order": 1,
"order_item": 1,
"merchant_variant": 100,
"id_tag": 1,
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
},
{
"id": 2,
"external_identifier": null,
"external_reference": null,
"merchant": 1,
"order": 2,
"order_item": 2,
"merchant_variant": 200,
"id_tag": 2,
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
},
.......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/order-item-units?cursor=eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://api.smake.io/master-administration/order-item-units",
"per_page": 15,
"next_cursor": "eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
```
## GET [#get]
Returns a order item unit of given `id` = **x**.
### Example of fetching specified order item unit information [#example-of-fetching-specified-order-item-unit-information]
Request
```http request
GET /order-item-units/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"external_identifier": "P-123",
"external_reference": "P-123",
"merchant": 1,
"order": 1,
"order_item": 1,
"merchant_variant": 100,
"id_tag": 1,
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
```
### Filtering [#filtering]
You can filter your results as follows:
#### List order item units for specified external reference [#list-order-item-units-for-specified-external-reference]
* `/order-item-units?filter[external_reference]=P-123`
#### List order item units for order item id [#list-order-item-units-for-order-item-id]
* `/order-item-units?filter[order_item]=1`
#### List order item units for order item external identifier [#list-order-item-units-for-order-item-external-identifier]
* `/order-item-units?filter[order_item.external_identifier]=P-123`
#### List order item units for order id [#list-order-item-units-for-order-id]
* `/order-item-units?filter[order]=1`
#### List order item units for state [#list-order-item-units-for-state]
* `/order-item-units?filter[state]=confirmed`
### Expand relation [#expand-relation]
To get a expanded relations please take a look into [Expanding objects](../basic/expanding-objects).
Allowed expansion `merchant_variant`, `merchant_variant.master_variant`, `id_tag`
### Example of expanded relation [#example-of-expanded-relation]
Request
```http request
GET /order-item-units/1?expand=id_tag HTTP/1.1
```
Response
```json
{
"id": 1,
"external_reference": "P-123",
"merchant": 1,
"order": 1,
"order_item": 1,
"merchant_variant": 100,
"id_tag": {
"id": 1,
"order_item_unit": 1,
"media": [],
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
},
"state": "pending",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
```
## Cancel [#cancel]
Cancels a order item unit of given `id` = **x**.
### Example of canceling order item units [#example-of-canceling-order-item-units]
Request
```http request
PUT /order-item-units/1/cancel HTTP/1.1
```
Response
```json
{
"id": 1,
"external_identifier": "P-123",
"external_reference": "P-123",
"merchant": 1,
"order": 1,
"order_item": 1,
"merchant_variant": 100,
"id_tag": 1,
"state": "cancelled",
"created_at": "2023-02-07T13:17:06+00:00",
"updated_at": "2023-02-07T13:17:06+00:00"
}
```
# Order Patch Parcel Number (/docs/master/2022-07-01/endpoints/order-patch-parcel)
Patch orders order item units external reference as parcel number.
## PATCH PARCEL NUMBER [#patch-parcel-number]
```http request
PATCH /orders/1/patch-parcel-number HTTP/1.1
{
"merchant_variants": [
{
"id": 100,
"parcel_number": "P-123",
"quantity": 1
}
]
}
```
Response
```http response
HTTP/1.1 200 OK
```
Validation Errors
**Case 1**
If a merchant\_variant is requested that doesn't belong to the order or no matching order item unit with empty external\_reference was found, you will receive an error.
```http response
HTTP/1.1 422 Unprocessable Entity
{
"message": "No order item units found for merchant variant 650.",
}
```
**Case 2**
If a merchant\_variant is requested and not enough matching order item units with empty external\_reference could be found, you will receive an error.
```http response
HTTP/1.1 422 Unprocessable Entity
{
"message": "Not enough order item units left for merchant variant 650.",
}
```
# Order (/docs/master/2022-07-01/endpoints/order)
Fetching list of order.
## LIST [#list]
Return a collection of order.
### Filtering [#filtering]
You can filter your results as follows:
##### List of orders for specific id(s) [#list-of-orders-for-specific-ids]
* `/orders?filter[id]=1`
* `/orders?filter[id]=1,2,3`
##### List of orders for specific external identifier(s) [#list-of-orders-for-specific-external-identifiers]
* `/orders?filter[external_identifier]=12345`
* `/orders?filter[external_identifier]=12345,67890`
##### List of orders for specific external reference(s) [#list-of-orders-for-specific-external-references]
* `/orders?filter[external_reference]=12345`
* `/orders?filter[external_reference]=12345,67890`
##### List of orders for specific state(s) [#list-of-orders-for-specific-states]
* `/orders?filter[state]=cancelled`
* `/orders?filter[state]=cancelled,delivered`
##### List of orders for specific merchant(s) [#list-of-orders-for-specific-merchants]
* `/orders?filter[merchant]=1`
* `/orders?filter[merchant]=1,4`
##### List of orders for specific payment payment method handle(s) [#list-of-orders-for-specific-payment-payment-method-handles]
* `/orders?filter[payment.payment_method.handle]=paypal`
* `/orders?filter[payment.payment_method.handle]=paypal,ideal`
##### List of orders for specific payment transaction reference(s) [#list-of-orders-for-specific-payment-transaction-references]
* `/orders?filter[payment.transaction_reference]=1258746321458`
* `/orders?filter[payment.transaction_reference]=1258746321458,9457785213654`
##### List of orders for specific created at min [#list-of-orders-for-specific-created-at-min]
* `/orders?filter[created_at_min]=2026-01-16`
##### List of orders for specific created at max [#list-of-orders-for-specific-created-at-max]
* `/orders?filter[created_at_max]=2026-01-16`
##### List of orders for specific created at equals [#list-of-orders-for-specific-created-at-equals]
* `/orders?filter[created_at_equals]=2026-01-16`
##### List of orders for specific updated at min [#list-of-orders-for-specific-updated-at-min]
* `/orders?filter[updated_at_min]=2026-01-16`
##### List of orders for specific updated at max [#list-of-orders-for-specific-updated-at-max]
* `/orders?filter[updated_at_max]=2026-01-16`
##### List of orders for specific updated at equals [#list-of-orders-for-specific-updated-at-equals]
* `/orders?filter[updated_at_equals]=2026-01-16`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
### Example of fetching order list [#example-of-fetching-order-list]
Request
```http request
GET /orders HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 60,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "checking",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 535.68,
"subtotal": 477.70462881489,
"total_tax": 57.97477318511,
"total_items_price": 495.72,
"shipping_total": 39.96,
"discount_total": 0,
"promotion_codes": [
173,
174,
],
"items": [
{
"id": 118,
"quantity": 1,
"total": 206.37,
"price": 173.42016806723,
"total_tax": 32.949831932774,
"tax_rate": 19,
"id_tags": [
118
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00"
},
{
"id": 119,
"quantity": 1,
"total": 176.56,
"price": 165.00934579439,
"total_tax": 11.550654205607,
"tax_rate": 7,
"id_tags": [
119
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00"
},
{
"id": 120,
"quantity": 1,
"total": 112.79,
"price": 105.41121495327,
"total_tax": 7.3787850467289,
"tax_rate": 7,
"id_tags": [
120
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00"
}
],
"disposition_order": null,
"customer": 64,
"shipping_address": 122,
"billing_address": 121,
"whitelabel_address": null,
"payment": null,
"shipments": [
60
],
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00",
"cancelled_at": null,
"ordered_at": "2023-01-10T10:11:41+00:00"
},
{
"id": 59,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "checking",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 285.28,
"subtotal": 257.14386594715,
"total_tax": 28.139205502855,
"total_items_price": 290.16,
"shipping_total": -4.88,
"discount_total": 0,
"items": [
{
"id": 115,
"quantity": 1,
"total": 37.67,
"price": 35.205607476636,
"total_tax": 2.4643925233645,
"tax_rate": 7,
"id_tags": [
115
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
{
"id": 116,
"quantity": 1,
"total": 147.81,
"price": 138.14018691589,
"total_tax": 9.6698130841123,
"tax_rate": 7,
"id_tags": [
116
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
{
"id": 117,
"quantity": 1,
"total": 104.68,
"price": 87.966386554622,
"total_tax": 16.713613445378,
"tax_rate": 19,
"id_tags": [
117
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
}
],
"disposition_order": 93,
"customer": 63,
"shipping_address": 120,
"billing_address": 119,
"whitelabel_address": null,
"payment": null,
"shipments": [
59
],
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00",
"cancelled_at": null,
"ordered_at": "2023-01-10T10:11:40+00:00"
},
{
"id": 58,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "delivered",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 285.28,
"subtotal": 257.14386594715,
"total_tax": 28.139205502855,
"total_items_price": 290.16,
"shipping_total": -4.88,
"discount_total": 0,
"items": [
{
"id": 115,
"quantity": 1,
"total": 37.67,
"price": 35.205607476636,
"total_tax": 2.4643925233645,
"tax_rate": 7,
"id_tags": [
115
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
{
"id": 116,
"quantity": 1,
"total": 147.81,
"price": 138.14018691589,
"total_tax": 9.6698130841123,
"tax_rate": 7,
"id_tags": [
116
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
{
"id": 117,
"quantity": 1,
"total": 104.68,
"price": 87.966386554622,
"total_tax": 16.713613445378,
"tax_rate": 19,
"id_tags": [
117
],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
}
],
"disposition_order": {
"id": 93,
"state": "completed",
"production_orders": [
{
"id": 1,
"state": "completed",
"production" : {
"id": 1,
"name": "Production 1",
"handle": "production-1",
"timezone": "Europe/Berlin",
"is_active": true,
},
"created_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
...
],
"created_at": null,
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00"
},
"customer": 63,
"shipping_address": 120,
"billing_address": 119,
"whitelabel_address": null,
"payment": null,
"shipments": [
59
],
"created_at": "2023-01-10T10:11:40+00:00",
"updated_at": "2023-01-10T10:11:40+00:00",
"cancelled_at": null,
"ordered_at": "2023-01-10T10:11:40+00:00"
},
.......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/orders?cursor=eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://api.smake.io/master-administration/orders",
"per_page": 15,
"next_cursor": "eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
```
### Example of fetching order list with expand [#example-of-fetching-order-list-with-expand]
Request
```http request
GET /orders?expand=promotion_codes HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 60,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "checking",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 535.68,
"subtotal": 477.70462881489,
"total_tax": 57.97477318511,
"total_items_price": 495.72,
"shipping_total": 39.96,
"discount_total": 0,
"promotion_codes": [
{
"id": 173,
"code": "Bestellung50Prozent",
"amount": -69.21
},
{
"id": 174,
"code": "Bestellung20Prozent",
"amount": -27.68
}
],
.........
}
.......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/orders?cursor=eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://api.smake.io/master-administration/orders",
"per_page": 15,
"next_cursor": "eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
```
### Available expandable attributes: [#available-expandable-attributes]
* order\_type
* items
* items.id\_tags
* items.merchant\_variant
* items.units
* disposition\_order
* disposition\_order.production\_orders
* disposition\_order.production\_orders.production
* customer
* shipping\_address
* billing\_address
* whitelabel\_address
* payment
* payment.payment\_method
* shipments
* promotion\_codes
* merchant
## GET [#get]
Return a order of given `id` = **x**.
Expand can be used here as mentioned before.
### Example of fetching specified order information [#example-of-fetching-specified-order-information]
Request
```http request
GET /orders/65 HTTP/1.1
```
Response
```json
{
"id": 65,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "draft",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 110.52,
"subtotal": 103.28971962617,
"total_tax": 7.2302803738319,
"total_items_price": 110.52,
"shipping_total": 0,
"discount_total": 0,
"promotion_codes": [
173,
174
],
"items": [
{
"id": 125,
"quantity": 1,
"total": 110.52,
"price": 103.28971962617,
"total_tax": 7.2302803738319,
"tax_rate": 7,
"id_tags": [],
"cancelled_at": null,
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00"
}
],
"disposition_order": null,
"customer": null,
"shipping_address": null,
"billing_address": null,
"whitelabel_address": null,
"payment": null,
"shipments": [
65
],
"created_at": "2023-01-10T10:11:41+00:00",
"updated_at": "2023-01-10T10:11:41+00:00",
"cancelled_at": null,
"ordered_at": null
}
```
### Example of fetching specified order information [#example-of-fetching-specified-order-information-1]
Request
```http request
GET /orders?expand=promotion_codes HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 60,
"order_type": 1,
"external_identifier": null,
"external_reference": null,
"cost_centre": null,
"state": "checking",
"failure_message": null,
"customer_locale": "de",
"currency": "EUR",
"total": 535.68,
"subtotal": 477.70462881489,
"total_tax": 57.97477318511,
"total_items_price": 495.72,
"shipping_total": 39.96,
"discount_total": 0,
"promotion_codes": [
{
"id": 173,
"code": "Bestellung50Prozent",
"amount": -69.21
},
{
"id": 174,
"code": "Bestellung20Prozent",
"amount": -27.68
}
],
.........
}
.......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/orders?cursor=eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://api.smake.io/master-administration/orders",
"per_page": 15,
"next_cursor": "eyJvcmRlcnMuaWQiOjQ2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
```
### Available expandable attributes: [#available-expandable-attributes-1]
* order\_type
* items
* items.id\_tags
* items.merchant\_variant
* items.units
* disposition\_order
* disposition\_order.production\_orders
* disposition\_order.production\_orders.production
* customer
* shipping\_address
* billing\_address
* whitelabel\_address
* payment
* payment.payment\_method
* shipments
* promotion\_codes
* merchant
## List Available Productions [#list-available-productions]
Fetching list of available productions for this order.
### Example of fetching available productions [#example-of-fetching-available-productions]
Request
```http request
GET /orders/1/available-productions HTTP/1.1
```
Response
```json
{
"productions": [
{
"id": 1,
"handle": "production-1"
},
{
"id": 2,
"handle": "production-2"
}
]
}
```
## Cancel Order [#cancel-order]
Cancels a order of given `id` = **x**.
### Example of cancel a order [#example-of-cancel-a-order]
Request
```http request
GET orders/1/cancel HTTP/1.1
```
Response
```json
{
"id": 1,
"order_type": 1,
"is_test": false,
"external_identifier": null,
"external_reference": null,
"number": null,
"cost_centre": null,
"state": "cancelled",
"failure_message": null,
"customer_locale": "en",
"currency": "EUR",
"total": 130.9,
"subtotal": 122.34,
"total_tax": 8.56,
"total_items_price": 130.9,
"shipping_total": 0,
"discount_total": 0,
"created_at": "2026-02-23T11:51:37+00:00",
"updated_at": "2026-02-25T13:44:40+00:00",
"cancelled_at": "2026-02-25T13:44:40+00:00",
"ordered_at": "2026-02-23T11:53:21+00:00",
"items": [
{
"id": 2,
"is_test": 0,
"external_identifier": null,
"quantity": 1,
"total": 130.9,
"price": 122.34,
"total_tax": 8.56,
"tax_rate": 7,
"variant": 695586,
"created_at": "2026-02-23T11:51:37+00:00",
"updated_at": "2026-02-25T13:44:40+00:00",
"cancelled_at": "2026-02-25T13:44:40+00:00",
"id_tags": [],
"units": []
}
],
....
}
```
Validation Errors
**422 Unprocessable Entity – Cancellation not allow**
```json
{
"message": "The system settings do not allow the cancellation of an order."
}
```
**Possible causes:**
* Allow the system the cancellation of an order.
***
**422 Unprocessable Entity – Order is already cancelled**
```json
{
"message": "The order can no longer be canceled because it is already cancelled."
}
```
***
**422 Unprocessable Entity – Goods have already been ordered**
```json
{
"message": "The order can no longer be canceled because goods have already been ordered."
}
```
**Possible causes:**
* Allow the system the cancellation of an order even though the goods have already been ordered.
***
**422 Unprocessable Entity – Goods have already arrived in production**
```json
{
"message": "The order can no longer be canceled because the goods have already arrived in production."
}
```
**Possible causes:**
* Allow the system the cancellation of an order even though the goods have already arrived in production.
***
**422 Unprocessable Entity – Order is already in production**
```json
{
"message": "The order can no longer be canceled because it is already in production."
}
```
**Possible causes:**
* Allow the system the cancellation of an order even though the order is in production.
***
**422 Unprocessable Entity – Goods are already ready for dispatch**
```json
{
"message": "The order can no longer be canceled as the goods are already ready for dispatch."
}
```
**Possible causes:**
* Allow the system the cancellation of an order even though the goods are already ready for dispatch.
***
**422 Unprocessable Entity – goods have already been shipped**
```json
{
"message": "The order can no longer be canceled because the goods have already been shipped."
}
```
## Cancel Order Item Units [#cancel-order-item-units]
Cancels all order item units from order of given `id` = **x**.
### Example of canceling order item units [#example-of-canceling-order-item-units]
Request
```http request
POST /orders/1/order-item-units/cancel HTTP/1.1
```
Response
```json
{
"canceled": [
{
"id": 1,
"external_reference": null,
"merchant": 1,
"order": 42,
"order_item": 122,
"merchant_variant": 12345,
"id_tag": 1,
"state": "cancelled",
"created_at": "2026-02-23T11:48:03+00:00",
"updated_at": "2026-02-25T13:57:17+00:00"
}
],
"not_canceled": []
}
```
Validation Errors
**404 Not Found – Order Not Found**
```json
{
"message": "No results found for Order"
}
```
**Possible causes:**
* The value in the URL (`{orderId}`) does not point to a valid Order or is invalid.
***
**409 Conflict – Concurrent process disallowed**
```json
{
"message": "Another process is already running. Please try again later."
}
```
**Possible causes:**
* The server disallows two concurrent process from running and returns a 409.
***
**500 Internal Server Error – Unexpected Error**
```json
{
"message": "An unknown error occurred."
}
```
**Possible causes:**
* Internal server error
* Faulty system dependency
* Database or service outage
> Note: The error is automatically recorded and reported on the server side.
***
The Canceling settings find in your Master Backend - Settings - Order management
# Positioning Area Identifier (/docs/master/2022-07-01/endpoints/positioning-area-identifier)
Fetching list of positioning area identifier.
## LIST [#list]
Return a collection of positioning area identifier.
### Filtering [#filtering]
You can filter your results as follows:
##### List of positioning area identifiers for specific id(s) [#list-of-positioning-area-identifiers-for-specific-ids]
* `/positioning-area-identifiers?filter[id]=1`
* `/positioning-area-identifiers?filter[id]=1,2,3`
##### List of positioning area identifiers for specific handle(s) [#list-of-positioning-area-identifiers-for-specific-handles]
* `/positioning-area-identifiers?filter[handle]=B`
* `/positioning-area-identifiers?filter[handle]=B,I`
### Example of fetching positioning area identifier list [#example-of-fetching-positioning-area-identifier-list]
Request
```http request
GET /positioning-area-identifiers HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 10,
"handle": "perferendis",
"name": {
"de": "et iusto",
"en": "non"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 9,
"handle": "quia",
"name": {
"de": "quod ut commodi",
"en": "blanditiis esse minima"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
.....
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/positioning-area-identifiers",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a positioning area identifier of given `id` = **x**.
### Example of fetching specified positioning area identifier information [#example-of-fetching-specified-positioning-area-identifier-information]
Request
```http request
GET /positioning-area-identifiers/2 HTTP/1.1
```
Response
```json
{
"id": 2,
"handle": "magni",
"name": {
"de": "nostrum non nam",
"en": "et rerum molestias"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
# Product Import (/docs/master/2022-07-01/endpoints/product-import)
This documentation describes the technical process for importing product data using the API.
## Step-by-Step Process [#step-by-step-process]
Generate Signed Upload URL
### Get Upload URL [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/csv",
"file_name": "example.csv"
}
```
Response
```json
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/tmp/d24c7338-5e ...",
"headers": {
"Content-Type": "text/csv"
}
}
```
**Note:** The upload URL is valid for **10 minutes**. Save the **path** value from the response – you will need it when creating the import.
### Upload Content [#upload-content]
Upload the Content
Request
```http request
PUT /temporary-upload-url?... HTTP/1.1
Content-Type: text/plain
handle;locale;name;description;manufacturer;manufacturer_number;brand;color_handle;color_name;size_handle;size_name;code;weight;country_of_origin;hs_tariff_code;cost_price;price;tax_rate;image_front_url;image_back_url;image_left_url;image_right_url;published;is_master;external_identifier;track_inventory;sale_continue;command
HoodedSweat1;de;"DUMMY - Hooded Sweat";"DUMMY - Hooded Sweat";Dummy;DUMMY-02;Dummy;white;White;s;S;DUMMY-02-3;0,12;DE;6101209000;0;0;19;https://cdn.smake.com/kXbGm6L1aP2/signed?signature=708c970b6f1c2e5e238c7f1d2a91aee01fe46656728ff4073e6a8e444dbd2b8a;https://cdn.smake.com/L9wU7hF0L5I/signed?signature=3c1d251268cb397d34a9f8f9e0978428b8b057706be29b48ab28ab2d3b2f8e8b;https://cdn.smake.com/J3zT0Rz5U4X/signed?signature=ed2a0cb4c0e8b59dbd1ca6353b6fc9d4b3805ec51b19d72f0a85bc9c726ca514;https://cdn.smake.com/d7zHwK1p5N7/signed?signature=e77b2fb17a2c742451e4582d91c0702df159bb2d8593e16ef9f08efbfa07d03f;yes;no;;yes;yes;
```
Response — 201 Created
```http
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
### Create a new import [#create-a-new-import]
Creates a new asynchronous import of products based on a CSV file uploaded to S3.
##### Parameters for creating a product import [#parameters-for-creating-a-product-import]
| Field | Type | Description | Required |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | -------- |
| path | string | A path of csv file uploaded to S3 | Yes |
| overwrite\_existing | boolean | If the switch is set to true, the existing data will be overwritten. | No |
| should\_preserve\_published | boolean | If the switch is set to true, the publishing settings for existing articles from the CSV file will be ignored. | No |
Request
```http request
POST /product-imports HTTP/1.1
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"overwrite_existing": true,
"should_preserve_published": false
}
```
Response
```http response
HTTP/1.1 202 Accepted
Location: /product-imports/1
```
**Note:** The import runs asynchronously. Use the Location header to poll the import status.
### Check Import Status [#check-import-status]
Returns a result of product import with the given `id` = **x**.
Request
```http request
GET /product-imports/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"options": {
"overwrite_existing": true,
"should_preserve_published": false
},
"state": "finished",
"failure_message": null,
"total_rows": 24,
"failed_rows": 0,
"processed_rows": 24,
"ignored_rows": 0,
"started_at": "2026-02-18T10:35:32+00:00",
"finished_at": "2026-02-18T10:36:15+00:00",
"source_file": {
"id": 5416,
"collection_name": "source-file",
"file_name": "product-import-example.csv",
"size": 14397,
"mime_type": "text/plain",
"download_url": "https://api.smake.test/storage/files/fb9c8ddc270843c7aaadcbd383fbaa2c/example.csv?expires=1768396599&signature=ed46888300b586baa5f31835b8a44ddddaf36cfc9ac22a42f38cf7b9fe0c09c3",
"state": null,
"requested": null,
"failure_message": null,
"created_at": "2026-02-18T10:35:29+00:00",
"updated_at": "2026-02-18T10:35:29+00:00"
},
"failed_report_file": null,
"created_at": "2026-02-18T10:35:29+00:00",
"updated_at": "2026-02-18T10:36:15+00:00"
}
```
**Note:** If not all data was processed successfully, the field `failed_report_file` will be filled and you can download an error report to check where the error lies.
### Example Import File [#example-import-file]
```csv
handle;locale;name;description;manufacturer;manufacturer_number;brand;color_handle;color_name;size_handle;size_name;code;weight;country_of_origin;hs_tariff_code;cost_price;price;tax_rate;image_front_url;image_back_url;image_left_url;image_right_url;published;is_master;external_identifier;track_inventory;sale_continue;command
HoodedSweat1;de;"DUMMY - Hooded Sweat";"DUMMY - Hooded Sweat";Dummy;DUMMY-02;Dummy;white;White;s;S;DUMMY-02-3;0,12;DE;6101209000;0;0;19;https://cdn.smake.com/kXbGm6L1aP2/signed?signature=708c970b6f1c2e5e238c7f1d2a91aee01fe46656728ff4073e6a8e444dbd2b8a;https://cdn.smake.com/L9wU7hF0L5I/signed?signature=3c1d251268cb397d34a9f8f9e0978428b8b057706be29b48ab28ab2d3b2f8e8b;https://cdn.smake.com/J3zT0Rz5U4X/signed?signature=ed2a0cb4c0e8b59dbd1ca6353b6fc9d4b3805ec51b19d72f0a85bc9c726ca514;https://cdn.smake.com/d7zHwK1p5N7/signed?signature=e77b2fb17a2c742451e4582d91c0702df159bb2d8593e16ef9f08efbfa07d03f;yes;no;;yes;yes;
HoodedSweat1;de;"DUMMY - Hooded Sweat";"DUMMY - Hooded Sweat";Dummy;DUMMY-02;Dummy;white;White;m;M;DUMMY-02-4;0,12;DE;6101209000;0;0;19;https://cdn.smake.com/kXbGm6L1aP2/signed?signature=708c970b6f1c2e5e238c7f1d2a91aee01fe46656728ff4073e6a8e444dbd2b8a;https://cdn.smake.com/L9wU7hF0L5I/signed?signature=3c1d251268cb397d34a9f8f9e0978428b8b057706be29b48ab28ab2d3b2f8e8b;https://cdn.smake.com/J3zT0Rz5U4X/signed?signature=ed2a0cb4c0e8b59dbd1ca6353b6fc9d4b3805ec51b19d72f0a85bc9c726ca514;https://cdn.smake.com/d7zHwK1p5N7/signed?signature=e77b2fb17a2c742451e4582d91c0702df159bb2d8593e16ef9f08efbfa07d03f;yes;no;;yes;yes;
HoodedSweat1;de;"DUMMY - Hooded Sweat";"DUMMY - Hooded Sweat";Dummy;DUMMY-02;Dummy;white;White;l;L;DUMMY-02-5;0,12;DE;6101209000;0;0;19;https://cdn.smake.com/kXbGm6L1aP2/signed?signature=708c970b6f1c2e5e238c7f1d2a91aee01fe46656728ff4073e6a8e444dbd2b8a;https://cdn.smake.com/L9wU7hF0L5I/signed?signature=3c1d251268cb397d34a9f8f9e0978428b8b057706be29b48ab28ab2d3b2f8e8b;https://cdn.smake.com/J3zT0Rz5U4X/signed?signature=ed2a0cb4c0e8b59dbd1ca6353b6fc9d4b3805ec51b19d72f0a85bc9c726ca514;https://cdn.smake.com/d7zHwK1p5N7/signed?signature=e77b2fb17a2c742451e4582d91c0702df159bb2d8593e16ef9f08efbfa07d03f;yes;no;;yes;yes;
HoodedSweat1;de;"DUMMY - Hooded Sweat";"DUMMY - Hooded Sweat";Dummy;DUMMY-02;Dummy;white;White;xl;XL;DUMMY-02-6;0,12;DE;6101209000;0;0;19;https://cdn.smake.com/kXbGm6L1aP2/signed?signature=708c970b6f1c2e5e238c7f1d2a91aee01fe46656728ff4073e6a8e444dbd2b8a;https://cdn.smake.com/L9wU7hF0L5I/signed?signature=3c1d251268cb397d34a9f8f9e0978428b8b057706be29b48ab28ab2d3b2f8e8b;https://cdn.smake.com/J3zT0Rz5U4X/signed?signature=ed2a0cb4c0e8b59dbd1ca6353b6fc9d4b3805ec51b19d72f0a85bc9c726ca514;https://cdn.smake.com/d7zHwK1p5N7/signed?signature=e77b2fb17a2c742451e4582d91c0702df159bb2d8593e16ef9f08efbfa07d03f;yes;no;;yes;yes;
```
# Product Option Import (/docs/master/2022-07-01/endpoints/product-option-imports)
This documentation describes the technical process for importing product option data using the API.
## Step-by-Step Process [#step-by-step-process]
Generate Signed Upload URL
### Get Upload URL [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/csv",
"file_name": "example.csv"
}
```
Response
```json
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/tmp/d24c7338-5e ...",
"headers": {
"Content-Type": "text/csv"
}
}
```
**Note:** The upload URL is valid for **10 minutes**.
### Upload Content [#upload-content]
Upload the Content
Request
```http request
PUT /temporary-upload-url?... HTTP/1.1
Content-Type: text/csv
option_handle,locale,option_name,option_order,value_handle,value_name,value_order,image_url
size,en,Size,1,s,S,1,
size,en,Size,2,m,M,2,
```
Response
```http response
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
### Create a new import [#create-a-new-import]
Creates a new asynchronous import of product options based on a CSV file uploaded to S3.
##### Parameters for creating a product option import [#parameters-for-creating-a-product-option-import]
| Field | Type | Description | Required |
| ----- | ------ | --------------------------------- | -------- |
| path | string | A path of csv file uploaded to S3 | Yes |
Request
```http request
POST /product-option-imports HTTP/1.1
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv"
}
```
Response
```http response
HTTP/1.1 202 Accepted
Location: /product-option-imports/1
```
### Check Import Status [#check-import-status]
Returns a result of product option import with the given `id` = **x**.
Request
```http request
GET /product-option-imports/1
```
Response
```json
{
"id": 1,
"options": [],
"state": "finished",
"failure_message": null,
"total_rows": 2,
"failed_rows": 0,
"processed_rows": 2,
"ignored_rows": 0,
"started_at": "2026-01-12T09:39:28+00:00",
"finished_at": "2026-01-12T09:39:28+00:00",
"source_file": {
"id": 5461,
"collection_name": "source-file",
"file_name": "example.csv",
"size": 188,
"mime_type": "text/plain",
"download_url": "https://api.smake.test/storage/files/99af8a25607f4c0e95e49fd00bc9dc40/example.csv?expires=1768225652&signature=44e1808541d94c18bd0962d2ee483a9d09a0c27b51f94a481345abe9c939e9a7",
"state": null,
"requested": null,
"failure_message": null,
"created_at": "2026-01-12T09:39:28+00:00",
"updated_at": "2026-01-12T09:39:28+00:00"
},
"failed_report_file": null,
"created_at": "2026-01-12T09:39:28+00:00",
"updated_at": "2026-01-12T09:39:28+00:00"
}
```
### Example Import File [#example-import-file]
```csv
option_handle,locale,option_name,option_order,value_handle,value_name,value_order,image_url
size,en,Size,1,s,S,1,
size,en,Size,2,m,M,2,
color,en,Color,3,yellow,Yellow,3,
color,en,Color,4,green,Green,4,
```
# Product Option Type (/docs/master/2022-07-01/endpoints/product-option-type)
Fetch list of production option type and specific option type.
## List [#list]
Returns a collection of production option type.
### Fetching production option type list [#fetching-production-option-type-list]
Request
```http request
GET /product-option-types HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "size",
"name": {
"de": "voluptatem ut corporis",
"en": "est"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
{
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-types",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## Get [#get]
Returns the production option type with the `id` = **x**.
### Fetching indevidual production option type [#fetching-indevidual-production-option-type]
Request
```http request
GET /product-option-types/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "size",
"name": {
"de": "voluptatem ut corporis",
"en": "est"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
```
# Product Option Value (/docs/master/2022-07-01/endpoints/product-option-value)
Here you can Listing, and view individual product option value. And can create product option value with media url or without media.
## List [#list]
Returns a collection of Product option value
### Filtering [#filtering]
You can filter your results as follows:
##### List of product option value for specific id(s) [#list-of-product-option-value-for-specific-ids]
* `/product-option-values?filter[id]=1`
* `/product-option-values?filter[id]=1,2,3`
##### List of product option value for specific name(s) [#list-of-product-option-value-for-specific-names]
* `/product-option-values?filter[name]=B`
* `/product-option-values?filter[name]=B,I`
##### List of product option value for specific handle(s) [#list-of-product-option-value-for-specific-handles]
* `/product-option-values?filter[handle]=B`
* `/product-option-values?filter[handle]=B,I`
### Example of listing product option value [#example-of-listing-product-option-value]
Request
```http request
GET /product-option-values HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 15,
"handle": "L",
"name": {
"de": "L",
"en": "L"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 14,
"handle": "M",
"name": {
"de": "M",
"en": "M"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 13,
"handle": "orange",
"name": {
"de": "orange",
"en": "orange"
},
"option_type": 2,
"media": [
199
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 12,
"handle": "lime",
"name": {
"de": "lime",
"en": "lime"
},
"option_type": 2,
"media": [
194
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 11,
"handle": "green",
"name": {
"de": "green",
"en": "green"
},
"option_type": 2,
"media": [
189
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 10,
"handle": "blue",
"name": {
"de": "blue",
"en": "blue"
},
"option_type": 2,
"media": [
184
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 9,
"handle": "cyan",
"name": {
"de": "cyan",
"en": "cyan"
},
"option_type": 2,
"media": [
179
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 8,
"handle": "pink",
"name": {
"de": "pink",
"en": "pink"
},
"option_type": 2,
"media": [
174
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 7,
"handle": "yellow",
"name": {
"de": "yellow",
"en": "yellow"
},
"option_type": 2,
"media": [
169
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 6,
"handle": "black",
"name": {
"de": "black",
"en": "black"
},
"option_type": 2,
"media": [
164
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 5,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": 2,
"media": [
159
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 4,
"handle": "red",
"name": {
"de": "red",
"en": "red"
},
"option_type": 2,
"media": [
154
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 3,
"handle": "purple",
"name": {
"de": "purple",
"en": "purple"
},
"option_type": 2,
"media": [
149
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 2,
"handle": "S",
"name": {
"de": "S",
"en": "S"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 1,
"handle": "gray",
"name": {
"de": "gray",
"en": "gray"
},
"option_type": 2,
"media": [
144
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-values",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Example of listing product option values with filter [#example-of-listing-product-option-values-with-filter]
Request
```http request
GET /product-option-values?filter[id]=1,2 HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 2,
"handle": "S",
"name": {
"de": "S",
"en": "S"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 1,
"handle": "gray",
"name": {
"de": "gray",
"en": "gray"
},
"option_type": 2,
"media": [
144
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-values",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Example of listing product option values with expanded relation [#example-of-listing-product-option-values-with-expanded-relation]
Allowed relation expansion is media and option\_type.
Request
```http request
GET /product-option-values?expand=option_type HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 15,
"handle": "L",
"name": {
"de": "L",
"en": "L"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "voluptatem ut corporis",
"en": "est"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 14,
"handle": "M",
"name": {
"de": "M",
"en": "M"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "voluptatem ut corporis",
"en": "est"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 13,
"handle": "orange",
"name": {
"de": "orange",
"en": "orange"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
199
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 12,
"handle": "lime",
"name": {
"de": "lime",
"en": "lime"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
194
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 11,
"handle": "green",
"name": {
"de": "green",
"en": "green"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
189
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 10,
"handle": "blue",
"name": {
"de": "blue",
"en": "blue"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
184
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 9,
"handle": "cyan",
"name": {
"de": "cyan",
"en": "cyan"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
179
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 8,
"handle": "pink",
"name": {
"de": "pink",
"en": "pink"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
174
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 7,
"handle": "yellow",
"name": {
"de": "yellow",
"en": "yellow"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
169
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:19+00:00",
"updated_at": "2023-01-10T10:11:19+00:00"
},
{
"id": 6,
"handle": "black",
"name": {
"de": "black",
"en": "black"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
164
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 5,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
159
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 4,
"handle": "red",
"name": {
"de": "red",
"en": "red"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
154
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 3,
"handle": "purple",
"name": {
"de": "purple",
"en": "purple"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
149
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 2,
"handle": "S",
"name": {
"de": "S",
"en": "S"
},
"option_type": {
"id": 1,
"handle": "size",
"name": {
"de": "voluptatem ut corporis",
"en": "est"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
{
"id": 1,
"handle": "gray",
"name": {
"de": "gray",
"en": "gray"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
144
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:17+00:00",
"updated_at": "2023-01-10T10:11:17+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-option-values",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Returns the product option value with the `id` = **x**.
### Example of get a specific product option value [#example-of-get-a-specific-product-option-value]
Request
```http request
GET /product-option-values/3 HTTP/1.1
```
Response
```json
{
"id": 3,
"handle": "purple",
"name": {
"de": "purple",
"en": "purple"
},
"option_type": 2,
"media": [
149
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
```
### Example of get a specific product option value with expanded relation [#example-of-get-a-specific-product-option-value-with-expanded-relation]
Request
```http request
GET /product-option-values/3?expand=media HTTP/1.1
```
Response
```json
{
"id": 3,
"handle": "purple",
"name": {
"de": "purple",
"en": "purple"
},
"option_type": 2,
"media": [
{
"id": 149,
"collection_name": "preview",
"file_name": "production-option-value-purple.png",
"size": 248,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1673876581&path=files%2Ff494d888c0ec4fdea75ba673514f58a2%2Fproduction-option-value-purple.png&signature=d27e675cbf1dc4cbd2ade93024149e5e8381d5ea117303d72dc8e01e2b48eabf",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
```
## CREATE [#create]
You can create product option value with media url or without media url.
### Background processing [#background-processing]
When you create a product option value with media url, this will create media asynchronously via a background job. You will receive the new media `id` in response.
The current state of the asynchronous process is represented due following states:
| State | Meaning |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `empty` | The initial state of a new media for product option value. |
| `checking` | Media is processed automatically in background. For example images will be generated or downloaded. |
| `failed` | Something went wrong during the checking process. |
| `completed` | All automatic processes were successful. The media is ready to use for product option value. |
### Media Array [#media-array]
The request field `media` is always an array of media url and optional. And allowed medias are jpeg, jpg & png.
| Field | Type | Description | Required |
| ---------------- | ------ | --------------------------------------------------------------------------------------- | --------- |
| collection\_name | string | Unique identifier for the intended use. | sometimes |
| url | string | Url which references a file. This file will be downloaded and attached to the resource. | sometimes |
### Example of creating a product option value with media [#example-of-creating-a-product-option-value-with-media]
Request
```http request
POST /product-option-values HTTP/1.1
{
"handle": "Q3",
"name":
{
"de": "Q3",
"en" : "Q3"
},
"option_type": {
"handle": "size"
},
"media" : [
{
"url": "https://cdn.pixabay.com/photo/2016/12/26/18/33/logo-1932539__340.png",
"collection_name": "preview"
}
]
}
```
Response
```json
{
"id": 16,
"handle": "Q3",
"name": {
"de": "Q3",
"en": "Q3"
},
"option_type": 1,
"media": [
1914
],
"media_state": "checking",
"created_at": "2023-01-16T12:54:09+00:00",
"updated_at": "2023-01-16T12:54:09+00:00"
}
```
### Example of creating a product option value without media [#example-of-creating-a-product-option-value-without-media]
Request
```http request
POST /product-option-values HTTP/1.1
{
"handle": "Q",
"name":
{
"de": "Q",
"en" : "Q"
},
"option_type": {
"handle": "size"
}
}
```
Response
```json
{
"id": 17,
"handle": "Q",
"name": {
"de": "Q",
"en": "Q"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-16T13:07:44+00:00",
"updated_at": "2023-01-16T13:07:44+00:00"
}
```
# Product Size Label Import (/docs/master/2022-07-01/endpoints/product-size-label-import)
This documentation describes the technical process for importing product size label data using the API.
## Step-by-Step Process [#step-by-step-process]
Generate Signed Upload URL
### Get Upload URL [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/csv",
"file_name": "example.csv"
}
```
Response
```json
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/tmp/d24c7338-5e ...",
"headers": {
"Content-Type": "text/csv"
}
}
```
**Note:** The upload URL is valid for **10 minutes**.
### Upload Content [#upload-content]
Upload the Content
Request
```http request
PUT /temporary-upload-url?... HTTP/1.1
Content-Type: text/plain
size_label_handle,size_label_display_name,size_scale,size_value,size_handle,command
mens-trousers,"Men's trousers EU",D,50,mens-trousers-eu-d-50
```
Response
```http
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
### Create a new import [#create-a-new-import]
Creates a new asynchronous import of product size labels based on a CSV file uploaded to S3.
##### Parameters for creating a product size label import [#parameters-for-creating-a-product-size-label-import]
| Field | Type | Description | Required |
| ----- | ------ | --------------------------------- | -------- |
| path | string | A path of csv file uploaded to S3 | Yes |
Request
```http request
POST /product-size-label-imports HTTP/1.1
{
"path": "tmp/d24c7338-5eeb-4129-bae6-2f8e30f004bb-metaZXhhbXBsZS5jc3Y=-.csv"
}
```
Response
```http response
HTTP/1.1 202 Accepted
Location: /product-size-label-imports/1
```
### Check Import Status [#check-import-status]
Returns a result of product size label import with the given `id` = **x**.
Request
```http request
GET /product-size-label-imports/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"options": [],
"state": "finished",
"failure_message": null,
"total_rows": 3,
"failed_rows": 0,
"processed_rows": 3,
"ignored_rows": 0,
"started_at": "2026-01-14T12:16:32+00:00",
"finished_at": "2026-01-14T12:16:32+00:00",
"source_file": {
"id": 5474,
"collection_name": "source-file",
"file_name": "example.csv",
"size": 266,
"mime_type": "text/csv",
"download_url": "https://api.smake.test/storage/files/fb9c8ddc270843c7aaadcbd383fbaa2c/example.csv?expires=1768396599&signature=ed46888300b586baa5f31835b8a44ddddaf36cfc9ac22a42f38cf7b9fe0c09c3",
"state": null,
"requested": null,
"failure_message": null,
"created_at": "2026-01-14T12:16:32+00:00",
"updated_at": "2026-01-14T12:16:32+00:00"
},
"failed_report_file": null,
"created_at": "2026-01-14T12:16:32+00:00",
"updated_at": "2026-01-14T12:16:32+00:00"
}
```
### Example Import File [#example-import-file]
```csv
size_label_handle,size_label_display_name,size_scale,size_value,size_handle,command
herren-hosen-eu,"Herren Hosen EU",D,50,herren-hosen-eu-d-50,
herren-hosen-eu,"Herren Hosen EU",D,48,herren-hosen-eu-d-48,
herren-hosen-eu,"Herren Hosen EU",D,46,herren-hosen-eu-d-46,
```
# Product Size Label (/docs/master/2022-07-01/endpoints/product-size-label)
Fetching product size label(list/individual). Create new product size label.
## List [#list]
Returns a collection of product size label.
### Filtering [#filtering]
You can filter your results as follows:
##### Fetch product size label list for specific id(s) [#fetch-product-size-label-list-for-specific-ids]
* `/product-size-labels?filter[id]=1`
* `/product-size-labels?filter[id]=1,2,3`
##### Fetch product size label list for specific name(s) [#fetch-product-size-label-list-for-specific-names]
* `/product-size-labels?filter[name]=Herren Hosen EU`
* `/product-size-labels?filter[name]=Herren Hosen EU,Herren Hosen EU2`
##### Fetch product size label list for specific handle(s) [#fetch-product-size-label-list-for-specific-handles]
* `/product-size-labels?filter[handle]=herren-hosen-eu`
* `/product-size-labels?filter[handle]=herren-hosen-eu,herren-hosen-eu2`
### Fetching product size label list [#fetching-product-size-label-list]
Request
```http request
GET /product-size-labels HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-size-labels",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
##### Expand product size [#expand-product-size]
You can show the content of the product size instead of the `id`.
* `/product-size-labels?expand=product_sizes`
### Fetching product size label list with expanded relation [#fetching-product-size-label-list-with-expanded-relation]
Request
```http request
GET /product-size-labels?expand=product_sizes HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
{
"id": 1,
"handle": "herren-hosen-eu-d-40",
"value": "40",
"product_size_scale": {
"id": 1,
"name": "D",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 2,
"handle": "herren-hosen-eu-gr-40",
"value": "40",
"product_size_scale": {
"id": 2,
"name": "GR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 3,
"handle": "herren-hosen-eu-f-46",
"value": "46",
"product_size_scale": {
"id": 3,
"name": "F",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 4,
"handle": "herren-hosen-eu-b-44",
"value": "44",
"product_size_scale": {
"id": 4,
"name": "B",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 5,
"handle": "herren-hosen-eu-i-46",
"value": "46",
"product_size_scale": {
"id": 5,
"name": "I",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 6,
"handle": "herren-hosen-eu-tr-40",
"value": "40",
"product_size_scale": {
"id": 6,
"name": "TR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-size-labels",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Fetching filtered product size label [#fetching-filtered-product-size-label]
Request
```http request
GET /product-size-labels?filter[id]=1 HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-size-labels",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
You can get specific product size label and also with expanded relation.
### Fetch product size label [#fetch-product-size-label]
Request
```http request
GET /product-size-labels/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "herren-hosen-eu",
"name": "Herren Hosen EU",
"product_sizes": [
1,
2,
3,
4,
5,
6
],
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
## CREATE [#create]
You can create product size label.
### Product Size Array [#product-size-array]
Array of product size object. Minimum 1 obejct is required.
```json
"product_sizes": [
{
"handle": "herren-hosen-eu",
"value": "17",
"product_size_scale": {
"name": "M"
}
}
]
```
### Product Size Scale [#product-size-scale]
For a list of available product size scales see [Product Size Scales](./product-size-scale).
| Field | Type | Description | Required |
| ------ | ------ | -------------------------------------------------------------- | ---------------------------- |
| id | int | The product size scale id. | yes\* (if handle is missing) |
| handle | string | The product size scale handle which will create new size scale | yes\* (if id is missing) |
\* You have to choose exactly either
`id`
or
`handle`
.
### Example of creating a product size label [#example-of-creating-a-product-size-label]
Request
```http request
POST /product-size-labels HTTP/1.1
{
"handle": "1herren-hosen-eu-2",
"name":"1Herren Hosen EU 2",
"product_sizes": [
{
"handle": "1herren-hosen-eu-d-7",
"value": "17",
"product_size_scale": {
"name": "1LKPEQq"
}
},
{
"handle": "1herren-hosen-eu-d-72",
"value": "172",
"product_size_scale": {
"id": 2
}
}
]
}
```
Response
```json
{
"id": 24,
"handle": "1herren-hosen-eu-6",
"name": "1Herren Hosen EU 6",
"product_sizes": [
17,
16
],
"created_at": "2022-12-15T09:12:47+00:00",
"updated_at": "2022-12-15T09:12:47+00:00"
}
```
# Product Size Scale (/docs/master/2022-07-01/endpoints/product-size-scale)
Here you can create, Listing, and view individual product size scale.
## List [#list]
Returns a collection of Product size scale
### Filtering [#filtering]
You can filter your results as follows:
##### List of product size scale for specific id(s) [#list-of-product-size-scale-for-specific-ids]
* `/product-size-scales?filter[id]=1`
* `/product-size-scales?filter[id]=1,2,3`
##### List of product size scale for specific name(s) [#list-of-product-size-scale-for-specific-names]
* `/product-size-scales?filter[name]=B`
* `/product-size-scales?filter[name]=B,I`
### Example of listing product size scales [#example-of-listing-product-size-scales]
Request
```http request
GET /product-size-scales HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 6,
"name": "TR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 5,
"name": "I",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 4,
"name": "B",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 3,
"name": "F",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 2,
"name": "GR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 1,
"name": "D",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-size-scales",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Example of listing product size scales with filter [#example-of-listing-product-size-scales-with-filter]
Request
```http request
GET /product-size-scales?filter[name]=B,I HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 5,
"name": "I",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
},
{
"id": 4,
"name": "B",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/product-size-scales",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Returns the product size scale with the `id` = **x**.
### Example of get a specific product size scale [#example-of-get-a-specific-product-size-scale]
Request
```http request
GET /product-size-scales/1 HTTP/1.1
```
Response
```json
{
"id": 2,
"name": "GR",
"created_at": "2023-01-10T10:11:11+00:00",
"updated_at": "2023-01-10T10:11:11+00:00"
}
```
## CREATE [#create]
You can create product size scale.
### Example of creating a product size scale [#example-of-creating-a-product-size-scale]
Request
```http request
POST /product-size-scales HTTP/1.1
{
"name": "SP"
}
```
Response
```json
{
"id": 7,
"name": "N",
"created_at": "2023-01-16T12:13:37+00:00",
"updated_at": "2023-01-16T12:13:37+00:00"
}
```
# Product Fetch EU (/docs/master/2022-07-01/endpoints/product-strauss-usa)
Get a specified master products. This Endpoint ist only for Strauss EU / USA
## Get [#get]
Returns a master product of given `manufacturer_number` = **x**.
You can expand some resources to show more details.
See Get Endpoint: [Products](../endpoints/product)
### Example of fetching specified master product [#example-of-fetching-specified-master-product]
Request
```http request
GET /products/fetch-by-manufacturer-number/123456789 HTTP/1.1
```
Response
```json
{
"id": 1,
"handle": "123456789",
"manufacturer_number": "123456789",
"name": {
"de": "Zip-Off Hose e.s.trail"
},
"description": {
"de": "Zip-Off Hose e.s.trail"
},
"country": 969,
"brand": 1,
"material_type": 2,
"variants": [
123456,
123457,
],
"scale_factors": [
123458,
123454,
],
"production_areas": [],
"positioning_areas": [
123455,
123451
],
"state": "completed",
"available_at": null,
"discontinue_at": null,
"created_at": "2026-03-06T07:05:01+00:00",
"updated_at": "2026-03-06T08:16:43+00:00"
}
```
### Available expandable attributes: [#available-expandable-attributes]
* country
* brand
* variants
* material\_type
* scale\_factors
* production\_areas
* production\_areas.production\_method
* positioning\_areas
* positioning\_areas.identifier
* positioning\_areas.clamping\_device
* positioning\_areas.production\_method
# Product (/docs/master/2022-07-01/endpoints/product)
Fetching list of master products.
## LIST [#list]
Return a collection of master products.
### Filtering [#filtering]
You can filter your results as follows:
##### Fetch master product list for specific id(s) [#fetch-master-product-list-for-specific-ids]
* `/products?filter[id]=1`
* `/products?filter[id]=1,2,3`
##### Fetch master product list for specific product handle(s) [#fetch-master-product-list-for-specific-product-handles]
* `/products?filter[handle]=12345`
* `/products?filter[handle]=12345,bag,67890`
##### List of product for specific available min date [#list-of-product-for-specific-available-min-date]
* `/products?filter[available_at_min]=2026-01-01 13:00:00`
##### List of product for specific available max date [#list-of-product-for-specific-available-max-date]
* `/products?filter[available_at_max]=2026-01-31 13:00:00`
##### List of product for specific available date at equals [#list-of-product-for-specific-available-date-at-equals]
* `/products?filter[available_at_equals]=2026-01-31 13:00:00`
##### List of product for specific discontinued min date [#list-of-product-for-specific-discontinued-min-date]
* `/products?filter[discontinue_at_min]=2026-01-01 13:00:00`
##### List of product for specific discontinued max date [#list-of-product-for-specific-discontinued-max-date]
* `/products?filter[discontinue_at_max]=2026-01-31 13:00:00`
##### List of product for specific discontinued date at equals [#list-of-product-for-specific-discontinued-date-at-equals]
* `/products?filter[discontinue_at_equals]=2026-01-31 13:00:00`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Expanding relationships [#expanding-relationships]
You can expand some resources to show more details.
See: [Expanding Objects](../basic/expanding-objects)
### Example of fetching master product list [#example-of-fetching-master-product-list]
Request
```http request
GET /products HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 6,
"handle": "0TyqQ5jRSDPHbK7G",
"manufacturer_number": "g9CZTR40EpoP9Mf5",
"name": {
"de": "German",
"en": "English",
"fr": "France",
"ja": "Japan",
"nl": "Netherlands"
},
"description": {
"de": "Quam mollitia nisi esse corrupti. Blanditiis occaecati dolor saepe est delectus sapiente qui. Voluptatem sit sit enim laboriosam harum. Veniam ut maiores consequatur laborum modi.",
"en": "Quam mollitia nisi esse corrupti. Blanditiis occaecati dolor saepe est delectus sapiente qui. Voluptatem sit sit enim laboriosam harum. Veniam ut maiores consequatur laborum modi."
},
"country": 72,
"brand": 14,
"material_type": 1,
"variants": [
181,
182,
183,
184,
185,
186,
187,
.....
],
"scale_factors": [
5,
6,
7,
8
],
"production_areas": [
13,
14,
.....
],
"positioning_areas": [
28,
29,
30,
......
],
"available_at": "2023-01-10T10:11:27+00:00",
"discontinue_at": null,
"created_at": "2023-01-10T10:11:27+00:00",
"updated_at": "2023-01-17T10:58:58+00:00"
},
{
"id": 5,
"handle": "0qPk8lxcojwqScL2",
"manufacturer_number": "NuWExwVisAsIFzny",
"name": {
"de": "T-Shirt 5 designbar",
"en": "T-Shirt 5 designable"
},
"description": {
"de": "Unde nulla expedita sed. Accusantium veritatis consectetur aut natus numquam debitis qui. Ut tempora eum impedit ut rerum eaque rerum. Ipsa est aut dolores veniam sed cupiditate occaecati.",
"en": "Unde nulla expedita sed. Accusantium veritatis consectetur aut natus numquam debitis qui. Ut tempora eum impedit ut rerum eaque rerum. Ipsa est aut dolores veniam sed cupiditate occaecati."
},
"country": 135,
"brand": 13,
"material_type": 1,
"variants": [
145,
146,
147,
148,
149,
......
],
"scale_factors": [
1,
2,
3,
4
],
"production_areas": [
1,
2,
.....
],
"positioning_areas": [
1,
2,
......
],
"available_at": "2023-01-10T10:11:26+00:00",
"discontinue_at": null,
"created_at": "2023-01-10T10:11:26+00:00",
"updated_at": "2023-01-10T10:11:26+00:00"
},
.....
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/products",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
### Example of fetching master product list with expand [#example-of-fetching-master-product-list-with-expand]
Request
```http request
GET /products?expand=country HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 6,
"handle": "0TyqQ5jRSDPHbK7G",
"manufacturer_number": "g9CZTR40EpoP9Mf5",
"name": {
"de": "German",
"en": "English",
"fr": "France",
"ja": "Japan",
"nl": "Netherlands"
},
"description": {
"de": "Quam mollitia nisi esse corrupti. Blanditiis occaecati dolor saepe est delectus sapiente qui. Voluptatem sit sit enim laboriosam harum. Veniam ut maiores consequatur laborum modi.",
"en": "Quam mollitia nisi esse corrupti. Blanditiis occaecati dolor saepe est delectus sapiente qui. Voluptatem sit sit enim laboriosam harum. Veniam ut maiores consequatur laborum modi."
},
"country": {
"id": 1,
"handle": "GA",
"name": {
"de": "Gabun",
"en": "Gabon"
},
"created_at": "2016-11-14T19:12:38+00:00",
"updated_at": "2017-09-07T14:05:06+00:00"
},
.....
}
]
}
```
### Available expandable attributes: [#available-expandable-attributes]
* country
* brand
* variants
* material\_type
* scale\_factors
* production\_areas
* production\_areas.production\_method
* positioning\_areas
* positioning\_areas.identifier
* positioning\_areas.clamping\_device
* positioning\_areas.production\_method
## GET [#get]
Returns a master product of given `id` = **x**.
### Example of fetching specified master product information [#example-of-fetching-specified-master-product-information]
Request
```http request
GET /products/2 HTTP/1.1
```
Response
```json
{
"id": 2,
"handle": "SWn1jwU1XUDfZESy",
"manufacturer_number": "xDj5Mw1Bov1So4H2",
"name": {
"de": "T-Shirt 2 nicht designbar",
"en": "T-Shirt 2 not designable"
},
"description": {
"de": "Occaecati laboriosam occaecati ullam commodi id quasi perferendis. Ratione placeat dolorem in odio rerum temporibus. Sunt commodi praesentium magnam recusandae. Quia ad quis et quia deleniti rerum.",
"en": "Occaecati laboriosam occaecati ullam commodi id quasi perferendis. Ratione placeat dolorem in odio rerum temporibus. Sunt commodi praesentium magnam recusandae. Quia ad quis et quia deleniti rerum."
},
"country": 220,
"brand": 10,
"material_type": 1,
"variants": [
37,
38,
.......
],
"scale_factors": [],
"production_areas": [],
"positioning_areas": [],
"available_at": "2023-01-10T10:11:21+00:00",
"discontinue_at": null,
"created_at": "2023-01-10T10:11:21+00:00",
"updated_at": "2023-01-10T10:11:21+00:00"
}
```
### Expand relation [#expand-relation]
To get a expanded relations please take a look into [Expanding objects](../basic/expanding-objects).
Allowed expansion `country`, `brand`, `variants`, `material_type`, `scale_factors`, `production_areas`, `production_areas.production_method`, `positioning_areas`, `positioning_areas.identifier`, `positioning_areas.clamping_device`, `positioning_areas.production_method`.
### Example of expanded relation [#example-of-expanded-relation]
Request
```http request
GET /products/2?expand=variants HTTP/1.1
```
Response
```json
{
"id": 2,
"handle": "SWn1jwU1XUDfZESy",
"manufacturer_number": "xDj5Mw1Bov1So4H2",
"name": {
"de": "T-Shirt 2 nicht designbar",
"en": "T-Shirt 2 not designable"
},
"description": {
"de": "Occaecati laboriosam occaecati ullam commodi id quasi perferendis. Ratione placeat dolorem in odio rerum temporibus. Sunt commodi praesentium magnam recusandae. Quia ad quis et quia deleniti rerum.",
"en": "Occaecati laboriosam occaecati ullam commodi id quasi perferendis. Ratione placeat dolorem in odio rerum temporibus. Sunt commodi praesentium magnam recusandae. Quia ad quis et quia deleniti rerum."
},
"country": 220,
"brand": 10,
"material_type": 1,
"variants": [
{
"id": 37,
"product_id": 2,
"sku": "production-variant-37",
"external_identifier": "product-2-white-S",
"hs_tariff_code": "9791994518336",
"price": 171.4,
"cost_price": 44.73,
"tax_rate": 7,
"is_master": false,
"option_values": [
{
"id": 5,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": {
"id": 2,
"handle": "color",
"name": {
"de": "ut",
"en": "consequuntur"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
"media": [
{
"id": 159,
"collection_name": "preview",
"file_name": "production-option-value-white.png",
"size": 292,
"mime_type": "image\/png",
"download_url": "https:\/\/api.smake.test\/temporary-url?expires=1674407678&path=files%2Fc5cc45920d5b4bef98ea9e509b07fa1c%2Fproduction-option-value-white.png&signature=066d6bb9b2ab3a254990e318dc8d8f2116626b151b41c927c7c011ddc1d5a94a",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
},
]
............
}
],
"scale_factors": [],
"production_areas": [],
"positioning_areas": [],
"available_at": "2023-01-10T10:11:21+00:00",
"discontinue_at": null,
"created_at": "2023-01-10T10:11:21+00:00",
"updated_at": "2023-01-10T10:11:21+00:00"
}
```
## CREATE [#create]
Create a new master product.
### Example of create a new master product [#example-of-create-a-new-master-product]
Request
```http request
POST /async/products HTTP/1.1
{
"handle": "my-product-1",
"name": {
"de": "Mein Produkt 1",
"en": "My product 1"
},
"description": {
"de": "Beschreibung zu meinem Produkt 1",
"en": "Description for my product 1"
},
"variants": [
{
"sku": "my-variant-8",
"external_identifier": "my-product-1-variant-1",
"price": 15.00,
"cost_price": 8.0,
"tax_rate": 19,
"discontinue_at": null,
"option_values": [
{
"id": 1
},
{
"id": 2
}
],
"views": [
{
"handle": "front",
"media": [
{
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/testfiles/logo.png",
"collection": "view-image"
}
]
},
{
"handle": "back",
"media": [
{
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/testfiles/logo.png",
"collection": "view-image"
}
]
}
]
}
],
"available_at": "2026-01-01T00:00:01+00:00",
"discontinue_at": null
}
```
Response
```json
{
"id": 18,
"handle": "my-product-1",
"variants": [
{
"id": 1024,
"sku": "my-variant-8"
}
]
}
```
## UPDATE [#update]
Update a master product.
### Example of update a specified master product [#example-of-update-a-specified-master-product]
Request
```http request
PUT /async/products/18 HTTP/1.1
{
"handle": "my-product-11",
"name": {
"de": "Mein Produkt 11",
"en": "My product 11"
},
"description": {
"de": "Beschreibung zu meinem Produkt 11",
"en": "Description for my product 11"
},
"variants": [],
"available_at": "2026-01-01T00:00:01+00:00",
"discontinue_at": null
}
```
Response
```json
{
"id": 18,
"handle": "my-product-1",
"variants": [
{
"id": 1024,
"sku": "my-variant-8"
}
]
}
```
## SYNC PRODUCT INTO MERCHANT [#sync-product-into-merchant]
### Example of syncing a specified master product into merchant [#example-of-syncing-a-specified-master-product-into-merchant]
Request
```http request
PUT /products/18/sync-to-merchants HTTP/1.1
```
Response
```http response
HTTP/1.1 200 Ok
```
## DELETE [#delete]
### Example of deleting a specified master product [#example-of-deleting-a-specified-master-product]
Request
```http request
DELETE /products/2 HTTP/1.1
```
Response
```http response
HTTP/1.1 204 No Content
```
Validation Errors
**404 Not Found – Production Product Not Found**
```json
{
"message": "No results found for Production Product"
}
```
**Possible causes:**
* The value in the URL (`{productionProductId}`) does not point to a valid Production Product or is invalid.
***
**423 Locked – Production Product is being processed**
```json
{
"message": "The product: 1 is being processed"
}
```
**Possible causes:**
* To prevent the same product from being processed multiple times simultaneously, we lock the process until it is completed
***
**500 Internal Server Error – Unexpected Error**
```json
{
"message": "An unknown error occurred."
}
```
**Possible causes:**
* Internal server error
* Faulty system dependency
* Database or service outage
> Note: The error is automatically recorded and reported on the server side.
## DELETE VARIANT [#delete-variant]
### Example of deleting a specified master product variant [#example-of-deleting-a-specified-master-product-variant]
Request
```http request
DELETE /products/2/variants/1 HTTP/1.1
```
Response
```http response
HTTP/1.1 204 No Content
```
Validation Errors
**404 Not Found – Production Product Not Found**
```json
{
"message": "No results found for Production Product"
}
```
**Possible causes:**
* The value in the URL (`{productionProductId}`) does not point to a valid Production Product or is invalid.
***
**404 Not Found – Production Variant Not Found**
```json
{
"message": "No results found for Production Variant"
}
```
**Possible causes:**
* The value in the URL (`{productionVariantId}`) does not point to a valid Production Variant or is invalid.
***
**423 Locked – Production Product is being processed**
```json
{
"message": "The product: 2 is being processed"
}
```
**Possible causes:**
* To prevent the same product from being processed multiple times simultaneously, we lock the process until it is completed
***
**500 Internal Server Error – Unexpected Error**
```json
{
"message": "An unknown error occurred."
}
```
**Possible causes:**
* Internal server error
* Faulty system dependency
* Database or service outage
> Note: The error is automatically recorded and reported on the server side.
# Production Method (/docs/master/2022-07-01/endpoints/production-method)
Fetching list of production method.
## LIST [#list]
Return a collection of production method.
### Filtering [#filtering]
You can filter your results as follows:
##### Fetch production method list for specific id(s) [#fetch-production-method-list-for-specific-ids]
* `/production-methods?filter[id]=1`
* `/production-methods?filter[id]=1,2,3`
##### Fetch production method list for specific handle(s) [#fetch-production-method-list-for-specific-handles]
* `/production-methods?filter[handle]=dtg`
* `/production-methods?filter[handle]=dtg,embroidery`
##### Fetch production method list for specific production type name(s) [#fetch-production-method-list-for-specific-production-type-names]
* `/production-methods?filter[collection_name]=dtg`
* `/production-methods?filter[collection_name]=dtg,embroidery`
##### Fetch a list for available production method(s) [#fetch-a-list-for-available-production-methods]
* `/production-methods?filter[is_available]=true`
### Example of fetching production method list [#example-of-fetching-production-method-list]
Request
```http request
GET /production-methods HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 4,
"handle": "manual",
"collection_name": "manual",
"name": {
"ar": "دليل",
"de": "Eigenes Produktionsverfahren",
"en": "Manual",
"es": "Manual",
"fr": "Manuel",
"it": "Manuale",
"ja": "マニュアル",
"ko": "Eigenes Produktionsverfahren",
"nl": "Manueel",
"pl": "Ręcznie",
"sv": "Egen produktionsprocess",
"tr": "El ile"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
{
"id": 3,
"handle": "additional-instruction",
"collection_name": "additional-instruction",
"name": {
"ar": "تعليمات إضافية",
"de": "Zusätzliche Anweisung",
"en": "Additional instruction",
"es": "Instrucciones adicionales",
"fr": "Instruction supplémentaire",
"it": "Ordine aggiuntivo",
"ja": "追加的な指示",
"ko": "Zusätzliche Anweisung",
"nl": "Bijkomende instructie",
"pl": "Dodatkowy instruktaż",
"sv": "Ytterligare instruktioner",
"tr": "Ek talimatlar"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
{
"id": 2,
"handle": "embroidery",
"collection_name": "embroidery",
"name": {
"ar": "زخرفة",
"de": "Direkteinstickung",
"en": "Embroider",
"es": "Bordar",
"fr": "Broderie",
"it": "Ricamo",
"ja": "刺しゅう",
"ko": "Direkteinstickung",
"nl": "Stikken",
"pl": "Haftuj",
"sv": "Direktbroderi",
"tr": "Nakış"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
},
{
"id": 1,
"handle": "dtg",
"collection_name": "dtg",
"name": {
"ar": "طباعة رقمية",
"de": "Digital-Direktdruck",
"en": "Digital print",
"es": "Impresión digital",
"fr": "Impression numérique",
"it": "Stampa digitale",
"ja": "デジタルプリント",
"ko": "Digital-Direktdruck",
"nl": "Digitaal printen",
"pl": "Druk cyfrowy",
"sv": "Digitalt direkttryck",
"tr": "Dijital baskı"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/production-methods",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a production method of given `id` = **x**.
### Example of fetching specified production method information [#example-of-fetching-specified-production-method-information]
Request
```http request
GET /production-methods/3 HTTP/1.1
```
Response
```json
{
"id": 3,
"handle": "additional-instruction",
"collection_name": "additional-instruction",
"name": {
"ar": "تعليمات إضافية",
"de": "Zusätzliche Anweisung",
"en": "Additional instruction",
"es": "Instrucciones adicionales",
"fr": "Instruction supplémentaire",
"it": "Ordine aggiuntivo",
"ja": "追加的な指示",
"ko": "Zusätzliche Anweisung",
"nl": "Bijkomende instructie",
"pl": "Dodatkowy instruktaż",
"sv": "Ytterligare instruktioner",
"tr": "Ek talimatlar"
},
"created_at": "2023-01-10T10:11:10+00:00",
"updated_at": "2023-01-10T10:11:10+00:00"
}
```
# Production (/docs/master/2022-07-01/endpoints/production)
Fetching list of productions.
## LIST [#list]
Returns a collection of productions.
### Filtering [#filtering]
You can filter your results as follows:
##### List of productions for specific id(s) [#list-of-productions-for-specific-ids]
* `/productions?filter[id]=1`
* `/productions?filter[id]=1,2,3`
##### List of productions for specific handle(s) [#list-of-productions-for-specific-handles]
* `/productions?filter[handle]=B`
* `/productions?filter[handle]=B,I`
See: [Pagination](../basic/pagination), [Filtering](../basic/filtering)
### Example of fetching production list [#example-of-fetching-production-list]
Request
```http request
GET /productions HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"name": "New Production",
"handle": "new-unique-handle",
"is_active": true,
"timezone": "Europe/Berlin",
"production_methods": [
{
"id": 3,
"handle": "additional-instruction",
"collection_name": "additional-instruction",
"name": {
"de": "Zusätzliche Anweisung",
"en": "Additional instruction",
"nl": "Bijkomende instructie",
"fr": "Instruction supplémentaire",
"ar": "تعليمات إضافية",
"sv": "Ytterligare instruktioner",
"pl": "Dodatkowy instruktaż",
"tr": "Ek talimatlar",
"es": "Instrucciones adicionales",
"ko": "추가 지침",
"ja": "追加的な指示",
"it": "Ordine aggiuntivo",
"cs": "Dodatečně přidělení",
"da": "Yderligere instruktioner",
"sk": "Doplňujúca inštrukcia",
"hu": "További utasítás"
},
"is_available": true,
"has_presorting": false,
"use_presorting": false,
"created_at": "2026-01-30T10:07:14+00:00",
"updated_at": "2026-01-30T10:07:14+00:00"
},
{
"id": 5,
"handle": "dtf",
"collection_name": "dtf",
"name": {
"de": "Direct-to-Film",
"en": "Direct to Film",
"nl": "Direct-to-Film",
"fr": "Direct-to-Film",
"ar": "الطباعة على الشريحة",
"sv": "Direct-to-Film",
"pl": "Direct-to-Film",
"tr": "DTF (Direct to Film) baskı",
"es": "Direct-to-Film",
"ko": "다이렉트 투 필름(Direct-to-Film)",
"ja": "Direct to Film(フィルム印刷)",
"it": "Direct-to-Film",
"cs": "Direct to Film",
"da": "Direct-to-Film",
"sk": "Direct-to-Film",
"hu": "Fólianyomtatás (DTF)"
},
"is_available": true,
"has_presorting": false,
"use_presorting": true,
"created_at": "2026-01-30T10:07:14+00:00",
"updated_at": "2026-01-30T10:07:14+00:00"
},
...
]
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/productions",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Returns a production with the given `id` = **x**.
### Example of fetching specified production information [#example-of-fetching-specified-production-information]
Request
```http request
GET /productions/1 HTTP/1.1
```
Response
```json
{
"id": 1,
"name": "New Production",
"handle": "new-unique-handle",
"is_active": true,
"timezone": "Europe/Berlin",
"production_methods": [
{
"id": 5,
"handle": "dtf",
"collection_name": "dtf",
"name": {
"de": "Direct-to-Film",
"en": "Direct to Film",
"nl": "Direct-to-Film",
"fr": "Direct-to-Film",
"ar": "الطباعة على الشريحة",
"sv": "Direct-to-Film",
"pl": "Direct-to-Film",
"tr": "DTF (Direct to Film) baskı",
"es": "Direct-to-Film",
"ko": "다이렉트 투 필름(Direct-to-Film)",
"ja": "Direct to Film(フィルム印刷)",
"it": "Direct-to-Film",
"cs": "Direct to Film",
"da": "Direct-to-Film",
"sk": "Direct-to-Film",
"hu": "Fólianyomtatás (DTF)"
},
"is_available": true,
"has_presorting": false,
"use_presorting": true,
"created_at": "2026-01-30T10:07:14+00:00",
"updated_at": "2026-01-30T10:07:14+00:00"
},
...
],
"workflow_type": "default"
}
```
## CREATE [#create]
Create a new Production.
### Parameters for creating a production [#parameters-for-creating-a-production]
| Field | Type | Description | Required |
| -------- | ------ | -------------------------------------- | -------- |
| handle | string | A unique handle for the new production | Yes |
| name | string | The name of the Production | No |
| timezone | string | Indicates the timezone of production | Yes |
### Example of creating a new production [#example-of-creating-a-new-production]
Request
```http request
POST /productions HTTP/1.1
{
"handle": "unique-handle",
"name":"New Production",
"timezone": "Europe/Berlin"
}
```
Response
```json
{
"id": 7,
"name": "New Production",
"handle": "new-unique-handle",
"is_active": false,
"timezone": "Europe/Berlin",
"production_methods": [
{
"id": 5,
"handle": "dtf",
"collection_name": "dtf",
"name": {
"de": "Direct-to-Film",
"en": "Direct to Film",
"nl": "Direct-to-Film",
"fr": "Direct-to-Film",
"ar": "الطباعة على الشريحة",
"sv": "Direct-to-Film",
"pl": "Direct-to-Film",
"tr": "DTF (Direct to Film) baskı",
"es": "Direct-to-Film",
"ko": "다이렉트 투 필름(Direct-to-Film)",
"ja": "Direct to Film(フィルム印刷)",
"it": "Direct-to-Film",
"cs": "Direct to Film",
"da": "Direct-to-Film",
"sk": "Direct-to-Film",
"hu": "Fólianyomtatás (DTF)"
},
"is_available": false,
"has_presorting": false,
"use_presorting": true,
"created_at": "2026-01-30T10:07:14+00:00",
"updated_at": "2026-01-30T10:07:14+00:00"
},
...
],
"workflow_type": null
}
```
## UPDATE [#update]
Update an existing Production.
### Parameters for updating a production [#parameters-for-updating-a-production]
| Field | Type | Description | Required |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------ | -------- |
| handle | string | The new handle for the production | Yes |
| name | string | The new name for the production | Yes |
| is\_active | boolean | Indicates whether the production is set to active | Yes |
| timezone | string | Indicates the timezone of production. to get the avialble timezons please see [Timezones](./timezone). | No |
### Example of updating an existing production [#example-of-updating-an-existing-production]
Request
```http request
PATCH /productions/1 HTTP/1.1
{
"handle": "new-unique-handle",
"name": "New Production",
"is_active": true,
"timezone": "Europe/Berlin"
}
```
Response
```json
{
"id": 1,
"name": "Production New",
"handle": "unique-handle-new",
"is_active": true,
"timezone": "Europe/Berlin",
"production_methods": [
{
"id": 5,
"handle": "dtf",
"collection_name": "dtf",
"name": {
"de": "Direct-to-Film",
"en": "Direct to Film",
"nl": "Direct-to-Film",
"fr": "Direct-to-Film",
"ar": "الطباعة على الشريحة",
"sv": "Direct-to-Film",
"pl": "Direct-to-Film",
"tr": "DTF (Direct to Film) baskı",
"es": "Direct-to-Film",
"ko": "다이렉트 투 필름(Direct-to-Film)",
"ja": "Direct to Film(フィルム印刷)",
"it": "Direct-to-Film",
"cs": "Direct to Film",
"da": "Direct-to-Film",
"sk": "Direct-to-Film",
"hu": "Fólianyomtatás (DTF)"
},
"is_available": true,
"has_presorting": false,
"use_presorting": true,
"created_at": "2026-01-30T10:07:14+00:00",
"updated_at": "2026-01-30T10:07:14+00:00"
},
...
],
"workflow_type": "default"
}
```
# Supplier (/docs/master/2022-07-01/endpoints/supplier)
Fetching list of supplier.
## LIST [#list]
Return a collection of supplier.
### Example of fetching supplier list [#example-of-fetching-supplier-list]
Request
```http request
GET /suppliers HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 1,
"name": "Lina Rau",
"address": {
"id": 123,
"street1": "156 West Points Suite 253",
"zip": "32392-6142",
"city": "East Nicolette",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 2,
"name": "Herr Heinz-Joachim Wiesner B.A.",
"address": {
"id": 124,
"street1": "7924 Swift Crossing Suite 410",
"zip": "04076-4689",
"city": "Lake Vincenzahaven",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 3,
"name": "Paul Fuhrmann",
"address": {
"id": 125,
"street1": "51868 Adrianna Flat",
"zip": "73632-0613",
"city": "Legrosport",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 4,
"name": "Fabian Raab",
"address": {
"id": 126,
"street1": "620 Mikayla Pine",
"zip": "81387",
"city": "Jaidenside",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
{
"id": 5,
"name": "Tim Kruse",
"address": {
"id": 127,
"street1": "43861 Pagac Flat",
"zip": "33959-6440",
"city": "East Mortimerhaven",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://api.smake.io/master-administration/suppliers",
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
```
## GET [#get]
Return a supplier of given `id` = **x**.
### Example of fetching specified supplier information [#example-of-fetching-specified-supplier-information]
Request
```http request
GET /suppliers/2 HTTP/1.1
```
Response
```json
{
"id": 2,
"name": "Herr Heinz-Joachim Wiesner B.A.",
"address": {
"id": 124,
"street1": "7924 Swift Crossing Suite 410",
"zip": "04076-4689",
"city": "Lake Vincenzahaven",
"country_code": "DE",
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
},
"created_at": "2023-01-10T10:11:49+00:00",
"updated_at": "2023-01-10T10:11:49+00:00"
}
```
## CREATE [#create]
Create a new supplier.
### Example of create a new supplier [#example-of-create-a-new-supplier]
Request
```http request
POST /suppliers HTTP/1.1
{
"name": "Muster Lieferant 2",
"address": {
"street1": "Musterstraße 123",
"zip": "45678",
"city": "Musterstadt",
"country_code": "DE"
}
}
```
Response
```json
{
"id": 11,
"name": "Muster Lieferant 2",
"address": {
"id": 95,
"street1": "Musterstraße 123",
"zip": "45678",
"city": "Musterstadt",
"country_code": "DE",
"created_at": "2026-02-02T10:06:49+00:00",
"updated_at": "2026-02-02T10:06:49+00:00"
},
"created_at": "2026-02-02T10:06:49+00:00",
"updated_at": "2026-02-02T10:06:49+00:00"
}
```
# Import Process (/docs/master/2022-07-01/endpoints/temporary-upload-url)
This documentation describes the technical process for importing data using the API.
## Step-by-Step Process [#step-by-step-process]
Generate Signed Upload URL
### Get Upload URL [#get-upload-url]
Request
```http request
POST /temporary-upload-url HTTP/1.1
{
"content_type": "text/csv",
"file_name": "example.csv"
}
```
Response
```json
{
"path": "tmp/3071cc4b-1e05-423c-b5af-dff01c97958d-metaZXhhbXBsZS5jc3Y=-.csv",
"url": "https://smake-public.s3.eu-west-1.amazonaws.com/tmp/3071cc4b-1e ...",
"headers": {
"Content-Type": "text/csv"
}
}
```
**Note:** The upload URL is valid for **10 minutes**.
### Upload Content [#upload-content]
Upload the Content
Request
```http request
PUT /temporary-upload-url?... HTTP/1.1
Content-Type: text/plain
id,handle,locale,name,description,manufacturer,manufacturer_number,brand
361,OTkvY6Q0EPzMbOk4,en,"T-Shirt 6 designable","Iste dolorum cumque ab quas voluptatum.","Kellie Sauer",Zos9y9pfXbhVG3TJ,"Bertram Douglas"
```
Response
```http
HTTP/1.1 200 OK
```
**Note:** Uploaded files will be automatically deleted after **24 hours**.
### Import Data [#import-data]
For example [Product option import](./product-option-imports)
# Timezones (/docs/master/2022-07-01/endpoints/timezone)
## LIST [#list]
Returns a collection of time zones.
### Examples of fetching a list of time zones [#examples-of-fetching-a-list-of-time-zones]
Request
```http request
GET /timezones HTTP/1.1
```
Response
```json
[
{
"Europe/Amsterdam (+01:00)": "Europe/Amsterdam"
},
{
"Europe/Andorra (+01:00)": "Europe/Andorra"
},
{
"Europe/Astrakhan (+04:00)": "Europe/Astrakhan"
},
{
"Europe/Athens (+02:00)": "Europe/Athens"
},
{
"Europe/Belgrade (+01:00)": "Europe/Belgrade"
},
...
]
```
### Filtering [#filtering]
You can filter your results as follows:
#### List time zones for a specified area [#list-time-zones-for-a-specified-area]
* `/timezones?area=Pacific`
#### Available areas [#available-areas]
The available areas are: Africa, America, Antarctica, Arctic, Asia, Atlantic, Australia, Europe, Indian, Pacific and UTC
### Example of filtered timezone list [#example-of-filtered-timezone-list]
Request
```http request
GET /timezones?area=Pacific HTTP/1.1
```
Response
```json
[
{
"Pacific/Apia (+13:00)": "Pacific/Apia"
},
{
"Pacific/Auckland (+13:00)": "Pacific/Auckland"
},
{
"Pacific/Bougainville (+11:00)": "Pacific/Bougainville"
},
{
"Pacific/Chatham (+13:45)": "Pacific/Chatham"
},
{
"Pacific/Chuuk (+10:00)": "Pacific/Chuuk"
},
{
"Pacific/Easter (-05:00)": "Pacific/Easter"
},
...
]
```
## Usage [#usage]
When sending us a request where the timezone is needed, please provide the value of the key.
### Example [#example]
```json
{
"timezone": "The value corresponding to the desired key. For example: key: Pacific/Apia (+13:00), value: Pacific/Apia
}
```
# Variant (/docs/master/2022-07-01/endpoints/variant)
Fetching list of master variants.
## LIST [#list]
Returns a collection of master variant.
### Filtering [#filtering]
You can filter your results as follows:
##### Fetch master variant list for specific id(s) [#fetch-master-variant-list-for-specific-ids]
* `/variants?filter[id]=1`
* `/variants?filter[id]=1,2,3`
##### Fetch master variant list for specific production product id(s) [#fetch-master-variant-list-for-specific-production-product-ids]
* `/variants?filter[production_product_id]=1`
* `/variants?filter[production_product_id]=1,2,3`
##### Fetch master variant list for min date [#fetch-master-variant-list-for-min-date]
* `/variants?filter[discontinue_at_min]=2026-01-01 13:00:00`
##### Fetch master variant list for max date [#fetch-master-variant-list-for-max-date]
* `/variants?filter[discontinue_at_max]=2026-01-31 13:00:00`
##### Fetch master variant list for exact date(s) [#fetch-master-variant-list-for-exact-dates]
* `/variants?filter[discontinue_at]=2026-01-15 13:00:00`
* `/variants?filter[discontinue_at]=2026-01-15 13:00:00,2026-02-20 14:50:00`
### Example of fetching master variant list [#example-of-fetching-master-variant-list]
Request
```http request
GET /variants HTTP/1.1
```
Response
```json
{
"data": [
{
"id": 216,
"product_id": 6,
"sku": "production-variant-216",
"external_identifier": "product-6-white-L",
"hs_tariff_code": "9783660520736",
"price": 125.51,
"cost_price": 135.03,
"tax_rate": 7,
"is_master": false,
"option_values": [
{
"id": 15,
"handle": "L",
"name": {
"de": "L",
"en": "L"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 5,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": 2,
"media": [
159
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
],
"views": [
{
"handle": "front",
"name": {
"de": "Ansicht vorne",
"en": "Front View",
"nl": "Weergave van voren",
"fr": "Vue de devant",
"ar": "العرض بالأمام",
"sv": "Framifrån",
"pl": "Widok z przodu",
"tr": "Ön görünüm",
"es": "Vista delantera",
"ko": "앞에 보기",
"ja": "正面図",
"it": "Vista anteriore"
},
"media": [
{
"id": 1028,
"collection_name": "view-image",
"file_name": "view-image-front-white.png",
"size": 22296,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411027&path=files%2Fd5c6197f22b346a4882f973fc48e667e%2Fview-image-front-white.png&signature=662693284524afc132cdf5eed1033f6678a20cae056d1dca13629d151c456d01",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "back",
"name": {
"de": "Ansicht hinten",
"en": "Rear View",
"nl": "Weergave van achteren",
"fr": "Vue de derrière",
"ar": "العرض بالخلف",
"sv": "Bakifrån",
"pl": "Widok z tyłu",
"tr": "Arka görünüm",
"es": "Vista trasera",
"ko": "뒤 보기",
"ja": "背面図",
"it": "Vista posteriore"
},
"media": [
{
"id": 1029,
"collection_name": "view-image",
"file_name": "view-image-back-white.png",
"size": 14983,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411027&path=files%2F58ad41b86e6148d291c06d70a31c4fd5%2Fview-image-back-white.png&signature=d0576289475239c9a1a2b5c0c551e353f3f56e751a8d0ea3af843fbe93cedbbb",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "left",
"name": {
"de": "Ansicht links",
"en": "Left View",
"nl": "Weergave links",
"fr": "Vue de gauche",
"ar": "العرض يسارًا",
"sv": "Från vänster",
"pl": "Widok z lewej strony",
"tr": "Sol görünüm",
"es": "Vista izquierda",
"ko": "좌측 보기",
"ja": "左側面図",
"it": "Vista a sinistra"
},
"media": [
{
"id": 1030,
"collection_name": "view-image",
"file_name": "view-image-left-white.png",
"size": 10954,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411027&path=files%2F55112c57b5d246d4a040b3a1d5eb23b0%2Fview-image-left-white.png&signature=d08a1fcbbab3043de637a52a8d745ad8b1cc316ba372c94ad8e2b0be0f5def19",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "right",
"name": {
"de": "Ansicht rechts",
"en": "Right View",
"nl": "Weergave rechts",
"fr": "Vue de droite",
"ar": "العرض يمينًا",
"sv": "Från höger",
"pl": "Widok z prawej strony",
"tr": "Sağ görünüm",
"es": "Vista derecha",
"ko": "우측 보기",
"ja": "右側面図",
"it": "Vista a destra"
},
"media": [
{
"id": 1031,
"collection_name": "view-image",
"file_name": "view-image-right-white.png",
"size": 11708,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411027&path=files%2F3490bd0183d44ab5ace39ceea4e534fc%2Fview-image-right-white.png&signature=9b49a81840f1e9b1dacce43afbbb6142ad2241948c2da592df07365ab833a8a0",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
}
],
"discontinue_at": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-17T10:59:02+00:00"
},
......
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://api.smake.io/master-administration/variants?cursor=eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
},
"meta": {
"path": "https://api.smake.io/master-administration/variants",
"per_page": 15,
"next_cursor": "eyJwcm9kdWN0aW9uX3ZhcmlhbnRzLmlkIjoyMDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
}
```
## GET [#get]
Returns a master variant of given `id` = **x**.
### Example of fetching specified master variant information [#example-of-fetching-specified-master-variant-information]
Request
```http request
GET /variants/216 HTTP/1.1
```
Response
```json
{
"id": 216,
"product_id": 6,
"sku": "production-variant-216",
"external_identifier": "product-6-white-L",
"hs_tariff_code": "9783660520736",
"price": 125.51,
"cost_price": 135.03,
"tax_rate": 7,
"is_master": false,
"option_values": [
{
"id": 15,
"handle": "L",
"name": {
"de": "L",
"en": "L"
},
"option_type": 1,
"media": [],
"media_state": "empty",
"created_at": "2023-01-10T10:11:20+00:00",
"updated_at": "2023-01-10T10:11:20+00:00"
},
{
"id": 5,
"handle": "white",
"name": {
"de": "white",
"en": "white"
},
"option_type": 2,
"media": [
159
],
"media_state": "empty",
"created_at": "2023-01-10T10:11:18+00:00",
"updated_at": "2023-01-10T10:11:18+00:00"
}
],
"views": [
{
"handle": "front",
"name": {
"de": "Ansicht vorne",
"en": "Front View",
"nl": "Weergave van voren",
"fr": "Vue de devant",
"ar": "العرض بالأمام",
"sv": "Framifrån",
"pl": "Widok z przodu",
"tr": "Ön görünüm",
"es": "Vista delantera",
"ko": "앞에 보기",
"ja": "正面図",
"it": "Vista anteriore"
},
"media": [
{
"id": 1028,
"collection_name": "view-image",
"file_name": "view-image-front-white.png",
"size": 22296,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411135&path=files%2Fd5c6197f22b346a4882f973fc48e667e%2Fview-image-front-white.png&signature=641ca9a22042abf06a1bdd5f17fb074cc0d63bafd0de5098f7298fb35d435cbe",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "back",
"name": {
"de": "Ansicht hinten",
"en": "Rear View",
"nl": "Weergave van achteren",
"fr": "Vue de derrière",
"ar": "العرض بالخلف",
"sv": "Bakifrån",
"pl": "Widok z tyłu",
"tr": "Arka görünüm",
"es": "Vista trasera",
"ko": "뒤 보기",
"ja": "背面図",
"it": "Vista posteriore"
},
"media": [
{
"id": 1029,
"collection_name": "view-image",
"file_name": "view-image-back-white.png",
"size": 14983,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411135&path=files%2F58ad41b86e6148d291c06d70a31c4fd5%2Fview-image-back-white.png&signature=7abfcadf9d2c34e9b968f784edc5142bdbeac806bf4763b9a17b3f2fe51cb576",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "left",
"name": {
"de": "Ansicht links",
"en": "Left View",
"nl": "Weergave links",
"fr": "Vue de gauche",
"ar": "العرض يسارًا",
"sv": "Från vänster",
"pl": "Widok z lewej strony",
"tr": "Sol görünüm",
"es": "Vista izquierda",
"ko": "좌측 보기",
"ja": "左側面図",
"it": "Vista a sinistra"
},
"media": [
{
"id": 1030,
"collection_name": "view-image",
"file_name": "view-image-left-white.png",
"size": 10954,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411135&path=files%2F55112c57b5d246d4a040b3a1d5eb23b0%2Fview-image-left-white.png&signature=957ae6eb2615ba8bab29bd337c1a30d9ec36a3f75447a7c3813da429c837d784",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
},
{
"handle": "right",
"name": {
"de": "Ansicht rechts",
"en": "Right View",
"nl": "Weergave rechts",
"fr": "Vue de droite",
"ar": "العرض يمينًا",
"sv": "Från höger",
"pl": "Widok z prawej strony",
"tr": "Sağ görünüm",
"es": "Vista derecha",
"ko": "우측 보기",
"ja": "右側面図",
"it": "Vista a destra"
},
"media": [
{
"id": 1031,
"collection_name": "view-image",
"file_name": "view-image-right-white.png",
"size": 11708,
"mime_type": "image/png",
"download_url": "https://api.smake.io/temporary-url?expires=1674411135&path=files%2F3490bd0183d44ab5ace39ceea4e534fc%2Fview-image-right-white.png&signature=7eb0caa5ee5d4fead124ad46c611cc73ceb7fd3e22d245da630f301a09886c6b",
"state": "pending",
"requested": null,
"failure_message": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-10T10:11:28+00:00"
}
]
}
],
"discontinue_at": null,
"created_at": "2023-01-10T10:11:28+00:00",
"updated_at": "2023-01-17T10:59:02+00:00"
}
```
## DELETE [#delete]
### Example of deleting a specified master variant for a specified master product [#example-of-deleting-a-specified-master-variant-for-a-specified-master-product]
Request
```http request
DELETE /products/2/variant/1 HTTP/1.1
```
Response
```http response
HTTP/1.1 204 No Content
```
Validation Errors
**404 Not Found – Production Product Not Found**
```json
{
"message": "No results found for Production Product"
}
```
**Possible causes:**
* The value in the URL (`{productionProductId}`) does not point to a valid Production Product or is invalid.
***
**404 Not Found – Production Variant Not Found**
```json
{
"message": "No results found for Production Variant"
}
```
**Possible causes:**
* The value in the URL (`{productionVariantId}`) does not point to a valid Production Variant or is invalid.
***
**423 Locked – Production Variant is being processed**
```json
{
"message": "The product variant: 1 is being processed"
}
```
**Possible causes:**
* To prevent the same product variant from being processed multiple times simultaneously, we lock the process until
it is completed
***
**500 Internal Server Error – Unexpected Error**
```json
{
"message": "An unknown error occurred."
}
```
**Possible causes:**
* Internal server error
* Faulty system dependency
* Database or service outage
> Note: The error is automatically recorded and reported on the server side.
# Webhook (/docs/master/2022-07-01/endpoints/webhook)
## DELETE [#delete]
### Example of deleting a specified webhook [#example-of-deleting-a-specified-webhook]
Request
```http request
DELETE /webhooks/1 HTTP/1.1
```
Response
```http response
HTTP/1.1 204 No Content
```
Validation Errors
**404 Not Found – Webhook Not Found**
```json
{
"message": ""
}
```
**Possible causes:**
* The ID in the URL (`/webhooks/1`) does not point to a valid Webhook or is invalid.
# Authentication (/docs/master/2022-07-01/setup/authentication)
In order to use the API, you must authenticate **each request** by including your API Token as a bearer token value:
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
```
You must replace `API_TOKEN_HERE` with your personal API Token.
# Headers (/docs/master/2022-07-01/setup/headers)
The API only supports the data format **JSON**. Therefore, make sure you have the following headers
set on **each request**.
```json
GET /orders HTTP/1.1
Authorization: Bearer API_TOKEN_HERE
Accept: application/json
Content-Type: application/json
```
# List variants (/docs/checkout/2022-02-01/endpoints/variants/listVariants)
`GET /variants`
Returns a paginated collection of variants.
**Filtering**
- `?filter[id]=1` or `?filter[id]=1,2,3` — one or more variant IDs
- `?filter[sku]=TS-100-BLK-M` — by SKU
- `?filter[since_id]=1` — IDs greater than the given ID
**Expanding objects** — `?expand=product`, `?expand=customizations`
— see [Basic Usage → Expanding Objects](/docs/checkout/2022-02-01/basic/expanding-objects).
# Show a variant (/docs/checkout/2022-02-01/endpoints/variants/showVariant)
`GET /variants/{id}`
Returns a single variant including its current customizations.
# Design a variant (/docs/checkout/2022-02-01/endpoints/variants/designVariant)
`POST /variants/{id}/design`
Applies customizations (logos, texts) to a variant. Designs are processed
**asynchronously** — poll the variant or subscribe to the
`variant.completed` / `variant.failed` webhook events to get the result
— see [Basic Usage → Polling](/docs/checkout/2022-02-01/basic/polling) and [Webhooks](/docs/checkout/2022-02-01/basic/webhooks).
Each customization targets a view area of the product and references
either an existing logo/text or an inline media object.
# List orders (/docs/checkout/2022-02-01/endpoints/orders/listOrders)
`GET /orders`
Returns a collection of created orders.
**Filtering** — see [Basic Usage → Filtering](/docs/checkout/2022-02-01/basic/filtering)
- `?filter[id]=1,2,3` — one or more order IDs
- `?filter[state]=completed` / `cancelled` — by state
- `?filter[external_identifier]=organic` — by your own identifier
- `?filter[external_reference]=143000` — by your own reference
- `?filter[since_id]=1` — IDs greater than the given ID
- `?filter[created_at_min]=2025-09-27` / `created_at_max` — created in range
- `?filter[updated_at_min]` / `updated_at_max` — updated in range
**Expanding objects** ([Basic Usage → Expanding Objects](/docs/checkout/2022-02-01/basic/expanding-objects)) —
`?expand=order_type`, `?expand=items.id_tags`, `?expand=items.variant`.
# Create an order (/docs/checkout/2022-02-01/endpoints/orders/createOrder)
`POST /orders`
Creates an order from designed variants (see [Variants → Design](/docs/checkout/2022-02-01/endpoints/variants/designVariant)).
Variants must be in state `completed` before they can be ordered; orders with pending designs are
rejected with a validation error. Use `external_identifier` /
`external_reference` to link the order to your shop system —
both are returned in every webhook payload.
# Show an order (/docs/checkout/2022-02-01/endpoints/orders/showOrder)
`GET /orders/{id}`
# Cancel an order (/docs/checkout/2022-02-01/endpoints/orders/cancelOrder)
`POST /orders/{id}/cancel`
Cancels an order that has not entered production yet. Once production
has started the order can no longer be cancelled and this endpoint
returns a validation error. Subscribe to `order.cancelled` ([Basic Usage → Webhooks](/docs/checkout/2022-02-01/basic/webhooks))
to be notified when the cancellation is completed.
# List customers (/docs/checkout/2022-02-01/endpoints/customers/listCustomers)
`GET /customers`
Returns a collection of customers.
**Filtering** — `?filter[id]=1,2,3`, `?filter[email]=jane@example.com`,
`?filter[external_identifier]=crm-4711`.
# Show a customer (/docs/checkout/2022-02-01/endpoints/customers/showCustomer)
`GET /customers/{id}`
# List products (/docs/checkout/2022-02-01/endpoints/products/listProducts)
`GET /products`
Returns a collection of products. Expand `variants` to embed the
sellable variants of each product.
# Show a product (/docs/checkout/2022-02-01/endpoints/products/showProduct)
`GET /products/{id}`
# List logos (/docs/checkout/2022-02-01/endpoints/logos/listLogos)
`GET /logos`
Returns a collection of logos.
**Filtering** — `?filter[id]=1,2,3`, `?filter[state]=completed`.
**Expanding** — `?expand=production_method`.
# Create a logo (/docs/checkout/2022-02-01/endpoints/logos/createLogo)
`POST /logos`
Creates a logo from an [uploaded media object](/docs/checkout/2022-02-01/endpoints/media/uploadMedia) or a public URL.
You have to choose **exactly one** of `media.id` or `media.url`.
Processing is asynchronous — listen to `logo.completed` / `logo.failed`
(see [Basic Usage → Webhooks](/docs/checkout/2022-02-01/basic/webhooks)).
# Show a logo (/docs/checkout/2022-02-01/endpoints/logos/showLogo)
`GET /logos/{id}`
# List texts (/docs/checkout/2022-02-01/endpoints/texts/listTexts)
`GET /texts`
Returns a collection of text personalizations.
# Show a text (/docs/checkout/2022-02-01/endpoints/texts/showText)
`GET /texts/{id}`
# Upload media (/docs/checkout/2022-02-01/endpoints/media/uploadMedia)
`POST /media`
Uploads a raw image file (`multipart/form-data`). The returned media `id` can then be used to
[create a logo](/docs/checkout/2022-02-01/endpoints/logos/createLogo) or
[design a variant](/docs/checkout/2022-02-01/endpoints/variants/designVariant).
# Show a media object (/docs/checkout/2022-02-01/endpoints/media/showMedia)
`GET /media/{id}`
# List webhook subscriptions (/docs/checkout/2022-02-01/endpoints/webhooks/listWebhooks)
`GET /webhooks`
# Create a webhook subscription (/docs/checkout/2022-02-01/endpoints/webhooks/createWebhook)
`POST /webhooks`
Subscribes a URL to one or more events. Deliveries are signed —
see [Basic Usage → Webhooks](/docs/checkout/2022-02-01/basic/webhooks) for signature verification.
# Show a webhook subscription (/docs/checkout/2022-02-01/endpoints/webhooks/showWebhook)
`GET /webhooks/{id}`
# Delete a webhook subscription (/docs/checkout/2022-02-01/endpoints/webhooks/deleteWebhook)
`DELETE /webhooks/{id}`
# Update a webhook subscription (/docs/checkout/2022-02-01/endpoints/webhooks/updateWebhook)
`PUT /webhooks/{id}`
# List payment methods (/docs/checkout/2022-02-01/endpoints/payment-methods/listPaymentMethods)
`GET /payment-methods`
# List shipping methods (/docs/checkout/2022-02-01/endpoints/shipping-methods/listShippingMethods)
`GET /shipping-methods`
# List production methods (/docs/checkout/2022-02-01/endpoints/production-methods/listProductionMethods)
`GET /production-methods`
Returns the embellishment techniques offered by the production
(e.g. DTG, embroidery, DTF). Logos and texts reference one of these.
# List additional instructions (/docs/checkout/2022-02-01/endpoints/additional-instructions/listAdditionalInstructions)
`GET /additional-instructions`
Returns manual production steps that can be booked together with a
variant design (see [Variants → Design](/docs/checkout/2022-02-01/endpoints/variants/designVariant)).
# Show an additional instruction (/docs/checkout/2022-02-01/endpoints/additional-instructions/showAdditionalInstruction)
`GET /additional-instructions/{id}`