All endpoints take optional query parameters that enhance the response objects:
include
— enhance the response objects (e.g. include=variants,translations
). Supported values are:
variants
— includes variants for products that have variants.locations
— includes locations (Voog Page, Article, Element) of the button to where the product has been attached. This will be ignored for anonymous requests.translations
— includes translations for all translatable objects and keys.details
— includes project details (image data).categories
— includes list of product categories associated with product.language_code
— display all top-level values in the given language context.GET /admin/api/ecommerce/v1/products?include=variants
This endpoint also allows anonymous access returning live products only.
Example response:
Status: 200 OK
[
{
"id": 1,
"price": 166.67,
"price_min": 166.67,
"price_max": 166.67,
"status": "live",
"stock": 10,
"reserved_quantity": 1,
"in_stock": true,
"sku": "0001",
"image_id": null,
"uses_variants": false,
"variants_count": 0,
"created_at": "2016-12-10T15:59:23.000Z",
"updated_at": "2016-12-10T15:59:23.000Z",
"name": "Sample product",
"slug": "sample-product",
"description": "Product description"
}, {
"id": 2,
"price": 166.67,
"price_min": 200.0,
"price_max": 250.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"image_id": null,
"uses_variants": true,
"variants_count": 2,
"created_at": "2016-12-10T09:14:15.000Z",
"updated_at": "2016-12-11T18:41:53.000Z",
"name": "Sample product",
"slug": "sample-product-1",
"description": "Product description",
"variant_types": [
{
"id": 1,
"name": "Color",
"values": [
{
"id": 1,
"name": "Red"
}, {
"id": 2,
"name": "Blue"
}
]
}
],
"variants": [
{
"id": 3,
"price": 200.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": "0002",
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Red",
"variant_attributes": [
{
"type_id": 1,
"value_id": 1
}
]
}, {
"id": 4,
"price": 250.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": "0003",
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Blue",
"variant_attributes": [
{
"type_id": 1,
"value_id": 2
}
]
}
]
}
]
per_page
— products per response (default: 50
; maximum: 250
).page
— requested page (default: 1
).Read more about filters.
category
attributes: id
, name
, slug
, parent_id
, depth
, created_at
,
updated_at
.product
attributes: id
, name
, slug
, description
, sku
, price
, price_min
,
price_max
, status
, stock
, reserved_quantity
, uses_variants
, created_at
, updated_at
.POST /admin/api/ecommerce/v1/products?include=translations&language_code=en
Example data:
{
"product": {
"price": 21.0,
"status": "live",
"name": "Product (en)",
"slug": "product-en",
"description": "Product description",
"sku": "0004",
"image_id": 88,
"variant_types": [
{
"name": "Color",
"translations": {
"name": {"en": "Color", "et": "Värv"}
},
"values": [
{
"name": "Blue",
"translations": {
"name": {"en": "Blue", "et": "Sinine"}
}
},
{
"name": "Red",
"translations": {
"name": {"en": "Red", "et": "Punane"}
}
}
]
}
],
"variants": [],
"category_ids": [14556, 32321, 11679],
"translations": {
"name": {
"en": "Product (en)", "et": "Product (et)"
},
"slug": {
"en": "product-en", "et": "product-et"
},
"description": {
"en": "Product description", "et": "Tootekirjeldus"
}
}
}
}
Example response:
Status: 201 Created
{
"id": 5,
"price": 21.0,
"price_min": 21.0,
"price_max": 21.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"uses_variants": true,
"variants_count": 2,
"created_at": "2016-12-10T09:14:15.000Z",
"updated_at": "2016-12-11T18:41:53.000Z",
"name": "Product (en)",
"slug": "product-en",
"description": "Product description",
"image_id": 88,
"image": {
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg",
"thumbnail": {
"content_type": "image/jpeg",
"width": 150,
"height": 80,
"url": "http://media.voog.com/0000/0000/0001/photos/img_medium.jpg"
},
"sizes": [
{
"content_type": "image/jpeg",
"width": 600,
"height": 320,
"url": "http://media.voog.com/0000/0000/0001/photos/img_block.jpg"
},
{
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg"
}
]
},
"variant_types": [
{
"id": 2,
"name": "Color",
"translations": {
"name": {"en": "Color", "et": "Värv"}
},
"values": [
{
"id": 3,
"name": "Blue",
"translations": {
"name": {"en": "Blue", "et": "Sinine"}
}
},
{
"id": 4,
"name": "Red",
"translations": {
"name": {"en": "Red", "et": "Punane"}
}
}
]
}
],
"variants": [
{
"id": 6,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Blue",
"variant_attributes": [
{
"type_id": 2,
"value_id": 3
}
]
}, {
"id": 7,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Red",
"variant_attributes": [
{
"type_id": 2,
"value_id": 4
}
]
}
],
"translations": {
"name": {
"en": "Product (en)", "et": "Product (et)"
},
"slug": {
"en": "product-en", "et": "product-et"
},
"description": {
"en": "Product description", "et": "Tootekirjeldus"
}
}
}
price
— Product price (without tax)status
— ('live' | 'draft') Product statusname
— Product name in the current language contextslug
— Product URL path suffix in the current language contextdescription
— Product description in the current language contextstock
— Product stock quantity as integer (e.g. 10
). Set to null
to turn of automatic stock management.reserved_quantity
— Booked quantity when stock management is turned on. It allows to correct the value.sku
— stock keeping unit identifier / product codeimage_id
— product image id (Asset ID)variant_types
— array of product variant type objects: {name, translations, values: [{name, translations}]}category_ids
— array of category IDs the product belongs totranslations
— Read more about translations.GET /admin/api/ecommerce/v1/products/5
This endpoint also allows anonymous access, returning live products only.
Example request:
GET http://helloworld.voog.com/admin/api/ecommerce/v1/products/5?include=translations,variants&language_code=en
Example response:
Status: 200 OK
{
"id": 5,
"price": 21.0,
"price_min": 21.0,
"price_max": 21.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"uses_variants": true,
"variants_count": 2,
"created_at": "2016-12-10T09:14:15.000Z",
"updated_at": "2016-12-11T18:41:53.000Z",
"name": "Product (en)",
"slug": "product-en",
"description": "Product description",
"image_id": 88,
"image": {
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg",
"thumbnail": {
"content_type": "image/jpeg",
"width": 150,
"height": 80,
"url": "http://media.voog.com/0000/0000/0001/photos/img_medium.jpg"
},
"sizes": [
{
"content_type": "image/jpeg",
"width": 600,
"height": 320,
"url": "http://media.voog.com/0000/0000/0001/photos/img_block.jpg"
},
{
"content_type": "image/jpeg",
"width": 948,
"height": 506,
"url": "http://media.voog.com/0000/0000/0001/photos/img.jpg"
}
]
},
"variant_types": [
{
"id": 2,
"name": "Color",
"translations": {
"name": {"en": "Color", "et": "Värv"}
},
"values": [
{
"id": 3,
"name": "Blue",
"translations": {
"name": {"en": "Blue", "et": "Sinine"}
}
},
{
"id": 4,
"name": "Red",
"translations": {
"name": {"en": "Red", "et": "Punane"}
}
}
]
}
],
"variants": [
{
"id": 6,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Blue",
"variant_attributes": [
{
"type_id": 2,
"value_id": 3
}
]
}, {
"id": 7,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Red",
"variant_attributes": [
{
"type_id": 2,
"value_id": 4
}
]
}
],
"translations": {
"name": {
"en": "Product (en)", "et": "Product (et)"
},
"slug": {
"en": "product-en", "et": "product-et"
},
"description": {
"en": "Product description", "et": "Tootekirjeldus"
}
}
}
PUT /admin/api/ecommerce/v1/products/1
This request updates the page with provided attributes. It generates a new list of product variants if the variant_types
array changes
Example request:
PUT http://helloworld.voog.com/admin/api/ecommerce/v1/products/5?include=variants,translations&language_code=en
Example data:
{
"name": "Product",
"slug": "product",
"description": "Product description",
"variant_types": [
{
"id": 2,
"name": "Color",
"translations": {
"name": {"en": "Color", "et": "Värv"}
},
"values": [
{
"id": 3,
"name": "Blue",
"translations": {
"name": {"en": "Blue", "et": "Sinine"}
}
},
{
"id": 4,
"name": "Red",
"translations": {
"name": {"en": "Red", "et": "Punane"}
}
},
{
"name": "Green",
"translations": {
"name": {"en": "Green", "et": "Roheline"}
}
}
]
}
],
"category_ids": [14556, 32321, 11679],
"translations": {
"name": {"en": "Product", "et": "Product (et)"},
"slug": {"en": "product", "et": "product-et"},
"description": {"en": "Product description", "et": "Tootekirjeldus" }
}
}
Example response:
Status: 200 OK
{
"id": 5,
"price": 21.0,
"price_min": 21.0,
"price_max": 21.0,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"uses_variants": true,
"variants_count": 2,
"created_at": "2016-12-10T09:14:15.000Z",
"updated_at": "2016-12-11T18:41:53.000Z",
"name": "Product",
"slug": "product",
"description": "Product description",
"variant_types": [
{
"id": 2,
"name": "Color",
"translations": {
"name": {"en": "Color", "et": "Värv"}
},
"values": [
{
"id": 3,
"name": "Blue",
"translations": {
"name": {"en": "Blue", "et": "Sinine"}
}
},
{
"id": 4,
"name": "Red",
"translations": {
"name": {"en": "Red", "et": "Punane"}
}
},
{
"id": 5,
"name": "Green",
"translations": {
"name": {"en": "Green", "et": "Roheline"}
}
}
]
}
],
"variants": [
{
"id": 6,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Blue",
"variant_attributes": [
{
"type_id": 2,
"value_id": 3
}
]
}, {
"id": 7,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Red",
"variant_attributes": [
{
"type_id": 2,
"value_id": 4
}
]
}, {
"id": 8,
"price": null,
"status": "live",
"stock": null,
"reserved_quantity": 0,
"in_stock": true,
"sku": null,
"created_at": "2017-03-22T12:47:44.000Z",
"updated_at": "2017-03-22T12:53:07.000Z",
"variant_attributes_text": "Color: Green",
"variant_attributes": [
{
"type_id": 2,
"value_id": 5
}
]
}
],
"translations": {
"name": {
"en": "Product (en)", "et": "Product (et)"
},
"slug": {
"en": "product", "et": "product-et"
},
"description": {
"en": "Product description", "et": "Tootekirjeldus"
}
}
}
Apply requested updates to all requested main products in query (target_ids
).
This endpoint also supports filter parameters to narrow down the list of products to be updated.
When update of some product fails then other products are still updated and the response contains the error details.
Example request:
PUT /admin/api/ecommerce/v1/products
{
"actions": [
{
"target_field": "price",
"action": "increase_by_percent",
"value": 10,
"source_field": "price"
},
{
"target_field": "price",
"action": "round_upwards",
"value": 2
},
{
"target_field": "status",
"action": "set",
"value": "live"
},
{
"target_field": "stock",
"action": "increase_by_fixed",
"value": 10
},
{
"target_field": "category_ids",
"action": "merge",
"value": [1, 2]
}
],
"target_ids": [1, 2, 3]
}
Example response:
Status: 200 OK
{
"counters": {
"processed": 3,
"failed": 0
},
"processed_ids": [
1, 2, 3
],
"failed_ids": []
}
Example payload error response:
Status: 400 Bad Request
{
"errors": {
"payload": {
"actions": [
{
"index": 0,
"errors": [
{
"target_field": "action_not_supported"
}
]
}
],
"target_ids": "empty"
}
}
}
Example items error response:
Status: 409 Conflict
{
"counters": {
"processed": 0,
"failed": 1
},
"processed_ids": [],
"failed_ids": [
999
],
"errors": {
"items": [
{
"id": 999,
"errors": {
"category_ids": [
"not_found"
]
}
}
]
}
}
actions
– array of actions to apply to products (required);
target_field
- field to update (required).source_field
- optional field name to use as source for the action. If not specified, the field itself is used as source.action
– the action to perform on the field (required), one of:set
– set the field to the given value
. source_field
value is copied to target_field
when value
is not specified or is blank.increase_by_fixed
– increase the field by the given value
.decrease_by_fixed
– decrease the field by the given value
.increase_by_percent
– increase the field by the given value
percent.decrease_by_percent
– decrease the field by the given value
percent.round
– round the field to the nearest decimal place given by value
where value
is any positive or negative integer (e.g value: 0
, 11.2545 => 11.0
; value: 1
, 11.2545 => 11.3
; value: -1
, 11.2545 => 10.0
).round_upwards
– round the field up to the nearest decimal place given by value
where value
is any positive or negative integer (e.g value: 0
, 11.2545 => 12.0
; value: 1
, 11.2545 => 11.3
; value: -1
, 11.2545 => 20.0
).round_downwards
– round the field down to the nearest decimal place given by value
where value
is any positive or negative integer (e.g value: 0
, 11.2545 => 11.0
; value: 1
, 11.2545 => 11.2
; value: -1
, 11.2545 => 10.0
).merge
– merge values to the field. value
must be an array of values to merge.remove
– remove values from the field. value
must be an array of values to remove.value
– the value to use by the action (required). It can be a number, string or array depending on the action:set
action.increase_by_fixed
, decrease_by_fixed
, increase_by_percent
, decrease_by_percent
, round
, round_upwards
and round_downwards
actions.merge
and remove
actions.round
, round_upwards
and round_downwards
actions.target_ids
– array of product ids to apply the actions to or string all
to apply to all products (required).Note: Action is skipped if the source_field
value is null
(except for set
, merge
and remove
actions).
Supported target_field
and source_field
values by action:
Action | category_ids | price | reserved_quantity | status | stock |
---|---|---|---|---|---|
set |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
increase_by_fixed |
✔️ | ✔️ | ✔️ | ||
decrease_by_fixed |
✔️ | ✔️ | ✔️ | ||
increase_by_percent |
✔️ | ✔️ | ✔️ | ||
decrease_by_percent |
✔️ | ✔️ | ✔️ | ||
round |
✔️ | ✔️ | ✔️ | ||
round_upwards |
✔️ | ✔️ | ✔️ | ||
round_downwards |
✔️ | ✔️ | ✔️ | ||
merge |
✔️ | ||||
remove |
✔️ |
DELETE /admin/api/ecommerce/v1/products/5
This request deletes the product and all its variants (if any) from the database.
Example request:
DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products/5
Example response:
Status: 204 No Content
This request deletes all main products and all its variants (if any) requested in query (target_ids
).
This endpoint also supports filter parameters to narrow down the list of products to be deleted.
target_ids
– array of product ids to apply the actions to or string "all"
to apply to all products (required).
Can be provided as a query parameter or in the request body:
?target_ids[]=1&target_ids[]=2
)?target_ids=1,2
){"target_ids": [1, 2]}
).Example request 1:
DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products
Example data 1:
{
"target_ids": [1, 2, 3]
}
Example data 2:
{
"target_ids": "all"
}
Example request 2:
DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products?target_ids=1,2,3
Example response:
Status: 204 No Content