Products API¶
These endpoints will allow you to easily manage products. Base URI is /api/v1/products.
Product API response structure¶
If you request a product via API, you will receive an object with the following fields:
| Field | Description |
|---|---|
| id | Id of the product |
| code | Unique product identifier (for example SKU) |
| averageRating | Average from accepted ratings given by customer |
| channels | Collection of channels to which the product was assigned |
| translations | Collection of translations (each contains slug and name in given language) |
| options | Options assigned to the product |
| images | Images assigned to the product |
If you request for more detailed data, you will receive an object with the following fields:
| Field | Description |
|---|---|
| id | Id of the product |
| code | Unique product identifier |
| averageRating | Average from ratings given by customer |
| channels | Collection of channels to which the product was assigned |
| translations | Collection of translations (each contains slug and name in given language) |
| attributes | Collection of attributes connected with the product (for example material) |
| associations | Collection of products associated with the created product (for example accessories to this product) |
| variants | Collection of variants connected with the product |
| reviews | Collection of reviews passed by customers |
| productTaxons | Collection of relations between product and taxons |
| mainTaxon | The main taxon to whose the product is assigned |
Note
Read more about Product model in the component docs.
Creating a Product¶
To create a new product you will need to call the /api/v1/products/ endpoint with the POST method.
Definition¶
POST /api/v1/products/
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | request | (unique) Product identifier |
Example¶
To create a new product use the below method:
$ curl http://demo.sylius.com/api/v1/products/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code": "TS3"
}
'
Exemplary Response¶
STATUS: 201 CREATED
{
"id": 61,
"code": "TS3",
"attributes": [],
"options": [],
"associations": [],
"productTaxons": [],
"channels": [],
"reviews": [],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/TS3"
},
"variants": {
"href": "\/api\/v1\/products\/TS3\/variants\/"
}
}
}
Warning
If you try to create a product without name, code or slug, you will receive a 400 Bad Request error, that will contain validation errors.
Example¶
$ curl http://demo.sylius.com/api/v1/products/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST
Exemplary Response¶
STATUS: 400 Bad Request
{
"code": 400,
"message": "Validation Failed",
"errors": {
"children": {
"enabled": {},
"translations": {},
"attributes": {},
"associations": {},
"channels": {},
"mainTaxon": {},
"productTaxons": {},
"images": {},
"code": {
"errors": [
"Please enter product code."
]
},
"options": {}
}
}
}
You can also create a product with additional (not required) fields:
| Parameter | Parameter type | Description |
|---|---|---|
| channels | request | Collection of channels codes, which we want to associate with created product |
| translations[‘localeCode’][‘name’] | request | Name of the product |
| translations[‘localeCode’][‘slug’] | request | (unique) Slug for the product |
| options | request | Collection of options codes, which we want to associate with created product |
| images | request | Collection of images types, which we want to associate with created product |
| attributes | request | Array of attributes (each object has information about selected attribute’s code, its value and locale in which it was defined) |
| associations | request | Object with code of productAssociationType and string in which the codes of associated products was written down. |
| productTaxons | request | String in which the codes of taxons was written down (separated by comma) |
| mainTaxon | request | The main taxon’s code to whose product is assigned |
Example¶
$ curl http://demo.sylius.com/api/v1/products/ \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X POST \
--data '
{
"code": "MUG_TH",
"mainTaxon": "mugs",
"productTaxons": "mugs",
"channels": [
"US_WEB"
],
"attributes": [
{
"attribute": "mug_color",
"localeCode": "en_US",
"value": "yellow"
}
],
"options": [
"mug_type"
],
"associations": {
"similar_products": "SMM,BMM"
},
"translations": {
"en_US": {
"name": "Theme Mug",
"slug": "theme-mug"
},
"pl": {
"name": "Kubek z motywem",
"slug": "kubek-z-motywem"
}
},
"images": [
{
"type": "ford"
}
]
}
'
Exemplary Response¶
STATUS: 201 CREATED
{
"name": "Theme Mug",
"id": 69,
"code": "MUG_TH",
"attributes": [
{
"code": "mug_material",
"name": "Mug material",
"value": "concrete",
"type": "text",
"id": 155
}
],
"options": [
{
"id": 1,
"code": "mug_type",
"position": 0,
"values": [
{
"name": "Mug type",
"code": "mug_type_medium"
},
{
"name": "Mug type",
"code": "mug_type_double"
},
{
"name": "Mug type",
"code": "mug_type_monster"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/mug_type"
}
}
}
],
"associations": [
{
"id": 13,
"type": {
"name": "Similar products",
"id": 1,
"code": "similar_products",
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Similar products"
}
}
},
"associatedProducts": [
{
"name": "Batman mug",
"id": 63,
"code": "BMM",
"attributes": [],
"options": [],
"associations": [],
"translations": {
"en_US": {
"locale": "en_US",
"id": 63,
"name": "Batman mug",
"slug": "batman-mug"
}
},
"productTaxons": [],
"channels": [],
"reviews": [],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/BMM"
},
"variants": {
"href": "\/api\/v1\/products\/BMM\/variants\/"
}
}
},
{
"name": "Spider-Man Mug",
"id": 68,
"code": "SMM",
"attributes": [],
"options": [],
"associations": [],
"translations": {
"en_US": {
"locale": "en_US",
"id": 70,
"name": "Spider-Man Mug",
"slug": "spider-man-mug"
}
},
"productTaxons": [],
"channels": [],
"reviews": [],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/SMM"
},
"variants": {
"href": "\/api\/v1\/products\/SMM\/variants\/"
}
}
}
]
}
],
"translations": {
"en_US": {
"locale": "en_US",
"id": 71,
"name": "Theme Mug",
"slug": "theme-mug"
},
"pl": {
"locale": "pl",
"id": 72,
"name": "Kubek z motywem",
"slug": "kubek-z-motywem"
}
},
"productTaxons": [
{
"id": 78,
"taxon": {
"name": "Mugs",
"id": 2,
"code": "mugs",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"children": {
"1": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 4,
"right": 5,
"level": 1,
"position": 1,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/t_shirts"
}
}
}
},
"left": 1,
"right": 6,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Cupiditate ut esse perspiciatis. Aspernatur nihil ducimus maxime doloremque. Ut aut ad unde necessitatibus voluptatibus id in."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/category"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"children": {
"1": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 4,
"right": 5,
"level": 1,
"position": 1,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/t_shirts"
}
}
}
},
"left": 1,
"right": 6,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Cupiditate ut esse perspiciatis. Aspernatur nihil ducimus maxime doloremque. Ut aut ad unde necessitatibus voluptatibus id in."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/category"
}
}
},
"children": [],
"left": 2,
"right": 3,
"level": 1,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 2,
"name": "Mugs",
"slug": "mugs",
"description": "Non omnis vel impedit eaque necessitatibus et eveniet. Fugiat distinctio quos aut commodi ea minima. Et natus ratione sit aperiam a molestiae. Eligendi sed cumque deleniti unde magnam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/mugs"
}
}
},
"position": 0
}
],
"channels": [
{
"id": 1,
"code": "US_WEB",
"name": "US Web Store",
"hostname": "localhost",
"color": "DarkSeaGreen",
"createdAt": "2017-02-27T09:12:16+0100",
"updatedAt": "2017-02-27T09:12:16+0100",
"enabled": true,
"taxCalculationStrategy": "order_items_based",
"_links": {
"self": {
"href": "\/api\/v1\/channels\/US_WEB"
}
}
}
],
"mainTaxon": {
"name": "Mugs",
"id": 2,
"code": "mugs",
"root": {
"name": "Category",
"id": 1,
"code": "category",
"children": {
"1": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 4,
"right": 5,
"level": 1,
"position": 1,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/t_shirts"
}
}
}
},
"left": 1,
"right": 6,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Cupiditate ut esse perspiciatis. Aspernatur nihil ducimus maxime doloremque. Ut aut ad unde necessitatibus voluptatibus id in."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/category"
}
}
},
"parent": {
"name": "Category",
"id": 1,
"code": "category",
"children": {
"1": {
"name": "T-Shirts",
"id": 5,
"code": "t_shirts",
"children": [],
"left": 4,
"right": 5,
"level": 1,
"position": 1,
"translations": [],
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/t_shirts"
}
}
}
},
"left": 1,
"right": 6,
"level": 0,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"name": "Category",
"slug": "category",
"description": "Cupiditate ut esse perspiciatis. Aspernatur nihil ducimus maxime doloremque. Ut aut ad unde necessitatibus voluptatibus id in."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/category"
}
}
},
"children": [],
"left": 2,
"right": 3,
"level": 1,
"position": 0,
"translations": {
"en_US": {
"locale": "en_US",
"id": 2,
"name": "Mugs",
"slug": "mugs",
"description": "Non omnis vel impedit eaque necessitatibus et eveniet. Fugiat distinctio quos aut commodi ea minima. Et natus ratione sit aperiam a molestiae. Eligendi sed cumque deleniti unde magnam."
}
},
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/taxons\/mugs"
}
}
},
"reviews": [],
"averageRating": 0,
"images": [
{
"id": 121,
"type": "ford",
"path": "65\/f6\/1e3b25f3721768b535e5c37ac005.jpeg"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/MUG_TH"
},
"variants": {
"href": "\/api\/v1\/products\/MUG_TH\/variants\/"
}
}
}
Note
The images (files) should be passed in an array as an attribute of request. See how it is done in Sylius here.
Getting a Single Product¶
To retrieve the details of a product you will need to call the /api/v1/product/code endpoint with the GET method.
Definition¶
GET /api/v1/products/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Unique product identifier |
Example¶
To see the details for the product with code = BMM use the below method:
$ curl http://demo.sylius.com/api/v1/products/BMM \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Note
The BMM code is an exemplary value. Your value can be different. Check in the list of all products if you are not sure which code should be used.
Exemplary Response¶
STATUS: 200 OK
{
"name": "Batman mug",
"id": 63,
"code": "BMM",
"attributes": [],
"options": [],
"associations": [],
"translations": {
"en_US": {
"locale": "en_US",
"id": 63,
"name": "Batman mug",
"slug": "batman-mug"
}
},
"productTaxons": [],
"channels": [],
"reviews": [],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/BMM"
},
"variants": {
"href": "\/api\/v1\/products\/BMM\/variants\/"
}
}
}
Collection of Products¶
To retrieve a paginated list of products you will need to call the /api/v1/products/ endpoint with the GET method.
Definition¶
GET /api/v1/products/
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| limit | query | (optional) Number of items to display per page, by default = 10 |
| sorting[‘nameOfField’][‘direction’] | query | (optional) Field and direction of sorting, by default ‘desc’ and ‘createdAt’ |
To see the first page of all products use the below method:
Example¶
$ curl http://demo.sylius.com/api/v1/products/ \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json"
Exemplary Response¶
STATUS: 200 OK
{
"page": 1,
"limit": 4,
"pages": 16,
"total": 63,
"_links": {
"self": {
"href": "\/api\/v1\/products\/?sorting%5Bcode%5D=desc&page=1&limit=4"
},
"first": {
"href": "\/api\/v1\/products\/?sorting%5Bcode%5D=desc&page=1&limit=4"
},
"last": {
"href": "\/api\/v1\/products\/?sorting%5Bcode%5D=desc&page=16&limit=4"
},
"next": {
"href": "\/api\/v1\/products\/?sorting%5Bcode%5D=desc&page=2&limit=4"
}
},
"_embedded": {
"items": [
{
"name": "Spiderman Mug",
"id": 61,
"code": "SMM",
"options": [],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/SMM"
}
}
},
{
"name": "Theme Mug",
"id": 63,
"code": "MUG_TH",
"options": [
{
"id": 1,
"code": "mug_type",
"position": 0,
"values": [
{
"code": "mug_type_medium",
"translations": {
"en_US": {
"locale": "en_US",
"id": 1,
"value": "Medium mug"
}
}
},
{
"code": "mug_type_double",
"translations": {
"en_US": {
"locale": "en_US",
"id": 2,
"value": "Double mug"
}
}
},
{
"code": "mug_type_monster",
"translations": {
"en_US": {
"locale": "en_US",
"id": 3,
"value": "Monster mug"
}
}
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/mug_type"
}
}
}
],
"averageRating": 0,
"images": [],
"_links": {
"self": {
"href": "\/api\/v1\/products\/MUG_TH"
}
}
},
{
"name": "Sticker \"quis\"",
"id": 16,
"code": "fe06f44e-2169-328f-8cd2-cd5495b4b6ad",
"options": [
{
"id": 2,
"code": "sticker_size",
"position": 1,
"values": [
{
"code": "sticker_size-3",
"translations": {
"en_US": {
"locale": "en_US",
"id": 4,
"value": "3\""
}
}
},
{
"code": "sticker_size_5",
"translations": {
"en_US": {
"locale": "en_US",
"id": 5,
"value": "5\""
}
}
},
{
"code": "sticker_size_7",
"translations": {
"en_US": {
"locale": "en_US",
"id": 6,
"value": "7\""
}
}
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/sticker_size"
}
}
}
],
"averageRating": 0,
"images": [
{
"id": 31,
"type": "main"
},
{
"id": 32,
"type": "thumbnail"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/fe06f44e-2169-328f-8cd2-cd5495b4b6ad"
}
}
},
{
"name": "T-Shirt \"vel\"",
"id": 51,
"code": "f6858e9c-2f48-3d59-9f54-e7ac9898c0bd",
"options": [
{
"id": 3,
"code": "t_shirt_color",
"position": 2,
"values": [
{
"code": "t_shirt_color_red",
"translations": {
"en_US": {
"locale": "en_US",
"id": 7,
"value": "Red"
}
}
},
{
"code": "t_shirt_color_black",
"translations": {
"en_US": {
"locale": "en_US",
"id": 8,
"value": "Black"
}
}
},
{
"code": "t_shirt_color_white",
"translations": {
"en_US": {
"locale": "en_US",
"id": 9,
"value": "White"
}
}
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/t_shirt_color"
}
}
},
{
"id": 4,
"code": "t_shirt_size",
"position": 3,
"values": [
{
"code": "t_shirt_size_s",
"translations": {
"en_US": {
"locale": "en_US",
"id": 10,
"value": "S"
}
}
},
{
"code": "t_shirt_size_m",
"translations": {
"en_US": {
"locale": "en_US",
"id": 11,
"value": "M"
}
}
},
{
"code": "t_shirt_size_l",
"translations": {
"en_US": {
"locale": "en_US",
"id": 12,
"value": "L"
}
}
},
{
"code": "t_shirt_size_xl",
"translations": {
"en_US": {
"locale": "en_US",
"id": 13,
"value": "XL"
}
}
},
{
"code": "t_shirt_size_xxl",
"translations": {
"en_US": {
"locale": "en_US",
"id": 14,
"value": "XXL"
}
}
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/t_shirt_size"
}
}
}
],
"averageRating": 0,
"images": [
{
"id": 101,
"type": "main"
},
{
"id": 102,
"type": "thumbnail"
}
],
"_links": {
"self": {
"href": "\/api\/v1\/products\/f6858e9c-2f48-3d59-9f54-e7ac9898c0bd"
}
}
}
]
}
}
Updating a Product¶
To fully update a product you will need to call the /api/v1/products/code endpoint with the PUT method.
Definition¶
PUT /api/v1/products/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Unique product identifier |
| translations[‘localeCode’][‘name’] | request | Name of the product |
| translations[‘localeCode’][‘slug’] | request | (unique) Slug |
Example¶
To fully update the product withcode = BMMuse the below method:
$ curl http://demo.sylius.com/api/v1/products/BMM \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PUT \
--data '
{
"translations": {
"en_US": {
"name": "Batman mug",
"slug": "batman-mug"
}
}
}
'
Exemplary Response¶
STATUS: 204 No Content
To update a product partially you will need to call the /api/v1/products/code endpoint with the PATCH method.
Definition¶
PATCH /api/v1/products/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Unique product identifier |
Example¶
To partially update the product with code = BMM use the below method:
$ curl http://demo.sylius.com/api/v1/products/BMM \
-H "Authorization: Bearer SampleToken" \
-H "Content-Type: application/json" \
-X PATCH \
--data '
{
"translations": {
"en_US": {
"name": "Batman mug"
}
}
}
'
Exemplary Response¶
STATUS: 204 No Content
Deleting a Product¶
To delete a product you will need to call the /api/v1/products/code endpoint with the DELETE method.
Definition¶
DELETE /api/v1/products/{code}
| Parameter | Parameter type | Description |
|---|---|---|
| Authorization | header | Token received during authentication |
| code | url attribute | Unique product identifier |
Example¶
To delete the product with code = MUG_TH use the below method:
$ curl http://demo.sylius.com/api/v1/products/MUG_TH \
-H "Authorization: Bearer SampleToken" \
-H "Accept: application/json" \
-X DELETE
Exemplary Response¶
STATUS: 204 No Content