REST API reference
Complete reference on how to handle Akeneo PIM resources
Products
Product [uuid]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, permissions based on your user groups are applied to the set of products you request.
Available in PIM versions: 7.0 SaaS
REQUEST
get /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
search
(string )
• Filter products, for more details see the Filters section
scope
(string )
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter product values via channel section
locales
(string )
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter product values via locale section
attributes
(string )
• Filter product values to only return those concerning the given attributes, for more details see the Filter on product values section
pagination_type
(string ,
page
by default )
• Pagination method type, see Pagination section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
with_attribute_options
(boolean )
• Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return products paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
uuid (string)
• Product uuid
enabled (boolean)
• Whether the product is enabled
family (string)
• Family code from which the product inherits its attributes and attributes requirements.
categories (array [string ])
• Codes of the categories in which the product is classified
groups (array [string ])
• Codes of the groups to which the product belong
parent (string)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values (object)
• Product attributes values, see Product values section for more details
associations (object)
: {
associationTypeCode (object)
: {
groups
(array [string ] ) • Array of groups codes with which the product is in relation
products
(array [string ] ) • Array of product uuids with which the product is in relation
product_models
(array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations (object)
: {
quantifiedAssociationTypeCode (object)
: {
products
(array [object ] ) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object ] ) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (object)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses (array [object ])
• Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the "with_completenesses" query parameter is set to "true")
}
]
}
}
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product
This endpoint allows you to create a new product. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to create. If no uuid is provided, the PIM will generate one for you.
Available in PIM versions: 7.0 SaaS
REQUEST
post /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string
)
• Product uuid
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"root_parent": "clothes"
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Enterprise Edition, permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.
Available in PIM versions: 7.0 SaaS
REQUEST
patch /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product in JSON standard format
{
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product (only available since the v2.0 in the Enterprise Edition)
quality_scores
(object
)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array
[object]
)
: [
{
scope
(string
)
•
locale
(string
)
•
data
(integer
)
•
}
]
}
Example
{"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
{"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","values":{"sku":[{"data":"updated_sku","locale":null,"scope":null}]}, "group":["promotion"]}
{"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","values":{"sku":[{"data":"new_product","locale":null,"scope":null}]},"family":"clothes"}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
uuid
(string )
• Product uuid
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","status_code":204}
{"line":2,"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","status_code":201}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a product
This endpoint allows you to get the information about a given product. In the Entreprise Edition, permissions based on your user groups are applied to the product you request.
Available in PIM versions: 7.0 SaaS
REQUEST
get /api/rest/v1/products-uuid/{uuid}
Query parameters
with_attribute_options
(boolean )
• Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)
with_completenesses
(boolean )
• Return product completenesses in the response. (Only available since the 6.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the product in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
uuid
(string )
• Product uuid
enabled
(boolean )
• Whether the product is enabled
family
(string )
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array [string] )
• Codes of the categories in which the product is classified
groups
(array [string] )
• Codes of the groups to which the product belong
parent
(string )
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object )
• Product attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product uuids with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product regarding the user permissions
}
quality_scores
(object )
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array [object] )
: [
{
scope
(string)
•
locale
(string)
•
data
(integer)
•
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"root_parent": "clothes",
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Entreprise Edition, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.
Available in PIM versions: 7.0 SaaS
REQUEST
patch /api/rest/v1/products-uuid/{uuid}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string
)
• Product uuid
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product (only available since the v2.0 in the Enterprise Edition)
quality_scores
(object
)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array
[object]
)
: [
{
scope
(string
)
•
locale
(string
)
•
data
(integer
)
•
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"root_parent": "clothes",
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product
This endpoint allows you to delete a given product. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to delete.
Available in PIM versions: 7.0 SaaS
REQUEST
delete /api/rest/v1/products-uuid/{uuid}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return
Means that the deletion was successful
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval EE only
This endpoint allows you to submit a draft for approval.
Available in PIM versions: 7.0 SaaS
REQUEST
post /api/rest/v1/products-uuid/{uuid}/proposal
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Submitted
Means that the draft submission was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft EE only
This endpoint allows you to get the information about a given draft.
Available in PIM versions: 7.0 SaaS
REQUEST
get /api/rest/v1/products-uuid/{uuid}/draft
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the draft in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
uuid
(string )
• Product uuid
enabled
(boolean )
• Whether the product is enabled
family
(string )
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array [string] )
• Codes of the categories in which the product is classified
groups
(array [string] )
• Codes of the groups to which the product belong
parent
(string )
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object )
• Product attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product uuids with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product regarding the user permissions
}
quality_scores
(object )
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array [object] )
: [
{
scope
(string)
•
locale
(string)
•
data
(integer)
•
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"root_parent": "clothes",
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Product [identifier]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/products
Path parameters
Ø
Query parameters
search
(string )
• Filter products, for more details see the Filters section
scope
(string )
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter product values via channel section
locales
(string )
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter product values via locale section
attributes
(string )
• Filter product values to only return those concerning the given attributes, for more details see the Filter on product values section
pagination_type
(string ,
page
by default )
• Pagination method type, see Pagination section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
with_attribute_options
(boolean )
• Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return products paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled (boolean)
• Whether the product is enabled
family (string)
• Family code from which the product inherits its attributes and attributes requirements.
categories (array [string ])
• Codes of the categories in which the product is classified
groups (array [string ])
• Codes of the groups to which the product belong
parent (string)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values (object)
• Product attributes values, see Product values section for more details
associations (object)
: {
associationTypeCode (object)
: {
groups
(array [string ] ) • Array of groups codes with which the product is in relation
products
(array [string ] ) • Array of product identifiers with which the product is in relation
product_models
(array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations (object)
: {
quantifiedAssociationTypeCode (object)
: {
products
(array [object ] ) • Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array [object ] ) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (object)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses (array [object ])
• Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the "with_completenesses" query parameter is set to "true")
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_quality_scores=true&with_attribute_options=true"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/cap"
}
},
"identifier": "cap",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": {}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product
This endpoint allows you to create a new product. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to create.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/products
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string
)
• Product UUID
identifier
(string
)
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/products
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product in JSON standard format
{
uuid
(string
)
• Product UUID
identifier
(string
)
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product (only available since the v2.0 in the Enterprise Edition)
quality_scores
(object
)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array
[object]
)
: [
{
scope
(string
)
•
locale
(string
)
•
data
(integer
)
•
}
]
}
Example
{"identifier":"cap","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
{"identifier":"mug","group":["promotion"]}
{"identifier":"tshirt","family":"clothes"}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"identifier":"cap","status_code":204}
{"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"identifier":"tshirt","status_code":201}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a product
This endpoint allows you to get the information about a given product. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product you request.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/products/{code}
Query parameters
with_attribute_options
(boolean )
• Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)
with_completenesses
(boolean )
• Return product completenesses in the response. (Only available since the 6.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the product in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
uuid
(string )
• Product UUID
identifier
(string )
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean )
• Whether the product is enabled
family
(string )
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array [string] )
• Codes of the categories in which the product is classified
groups
(array [string] )
• Codes of the groups to which the product belong
parent
(string )
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object )
• Product attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product identifiers with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product regarding the user permissions
}
quality_scores
(object )
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array [object] )
: [
{
scope
(string)
•
locale
(string)
•
data
(integer)
•
}
]
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/products/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string
)
• Product UUID
identifier
(string
)
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean
,
true
by default)
• Whether the product is enabled
family
(string
,
null only in the case of a non variant product
by default)
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product is classified
groups
(array
[string]
,
[]
by default)
• Codes of the groups to which the product belong
parent
(string
,
null
by default)
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object
)
• Product attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product models and/or other products, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product (only available since the v2.0 in the Enterprise Edition)
quality_scores
(object
)
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array
[object]
)
: [
{
scope
(string
)
•
locale
(string
)
•
data
(integer
)
•
}
]
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product
This endpoint allows you to delete a given product. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the product you try to delete.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
delete /api/rest/v1/products/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return
Means that the deletion was successful
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval EE only
This endpoint allows you to submit a draft for approval.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/products/{code}/proposal
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Submitted
Means that the draft submission was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft EE only
This endpoint allows you to get the information about a given draft.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/products/{code}/draft
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the draft in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
uuid
(string )
• Product UUID
identifier
(string )
• Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean )
• Whether the product is enabled
family
(string )
• Family code from which the product inherits its attributes and attributes requirements.
categories
(array [string] )
• Codes of the categories in which the product is classified
groups
(array [string] )
• Codes of the groups to which the product belong
parent
(string )
• Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values
(object )
• Product attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product identifiers with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product regarding the user permissions
}
quality_scores
(object )
• Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses
(array [object] )
: [
{
scope
(string)
•
locale
(string)
•
data
(integer)
•
}
]
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Product model
Get list of product models
This endpoint allows you to get a list of product models. Product models are paginated. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/product-models
Path parameters
Ø
Query parameters
search
(string )
• Filter product models, for more details see the Filters section
scope
(string )
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter product values via channel section
locales
(string )
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter product values via locale section
attributes
(string )
• Filter product values to only return those concerning the given attributes, for more details see the Filter on product values section and the Filter on product model properties section
pagination_type
(string ,
page
by default )
• Pagination method type, see Pagination section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return product models paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Product model code
family (string)
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant (string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent (string)
• Code of the parent product model. This parent can be modified since the 2.3.
categories (array [string ])
• Codes of the categories in which the product model is categorized
values (object)
• Product model attributes values, see Product values section for more details
associations (object)
: {
associationTypeCode (object)
: {
groups
(array [string ] ) • Array of groups codes with which the product is in relation
products
(array [string ] ) • Array of product identifiers with which the product is in relation
product_models
(array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations (object)
: {
quantifiedAssociationTypeCode (object)
: {
products
(array [object ] ) • Array of objects containing product identifiers and quantities with which the product model is in relation
product_models
(array [object ] ) • Array of objects containing product model codes and quantities with which the product model is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product model regarding the user permissions
}
quality_scores (object)
• Product model quality scores for each channel/locale combination (only available since the 7.0 version and when the "with_quality_scores" query parameter is set to "true")
}
]
}
}
Example
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=qg%3D%3D"
},
"first": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3"
},
"next": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=rw%3D%3D"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/amarisshoe"
}
},
"code": "amarisshoe",
"family": "shoes",
"family_variant": "shoes_VariantA1",
"parent": null,
"categories": [
"clothing",
"shoes"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like shoes!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/Abiloitshirt"
}
},
"code": "Abiloitshirt",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"parent": null,
"categories": [
"clothing",
"tshirt"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like tshirt!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
}
],
"product_models": []
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/Astertrousers"
}
},
"code": "Astertrousers",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"parent": null,
"categories": [
"clothing",
"trousers"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like trousers!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product model
This endpoint allows you to create a new product model. In the Enterprise Edition, since the v2.3, permissions based on your user groups are applied to the product model you try to create.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/product-models
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Product model code
family
(string
)
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant
(string
)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string
,
null
by default)
• Code of the parent product model. This parent can be modified since the 2.3.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product model is categorized
values
(object
)
• Product model attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product and/or other product models, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several product models
This endpoint allows you to update and/or create several product models at once. Learn more about Update behavior. Note that if no product models exists for the given code, it creates it. In the Enterprise Edition, since the v2.3, permissions based on your user groups are applied to the product models you try to update. It may result in the creation of drafts if you only have edit rights through the product model's categories.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/product-models
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product model in JSON standard format
{
code
(string
)
• Product model code
family
(string
)
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant
(string
)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string
,
null
by default)
• Code of the parent product model. This parent can be modified since the 2.3.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product model is categorized
values
(object
)
• Product model attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product and/or other product models, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product model (only available since the v2.3 in the Enterprise Edition)
quality_scores
(object
)
• Product model quality scores for each channel/locale combination (only available since the 7.0 version and when the "with_quality_scores" query parameter is set to "true")
}
Example
{"code": "sub_sweat_option_a", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code": "sub_sweat_option_b", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code":"tshirt", "parent": "root_tshirt", "family_variant":"clothesvariant","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing tshirt"}]}}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"sub_sweat_option_a","status_code":204}
{"line":2,"code":"sub_sweat_option_b","status_code":422,"message":"Validation failed.","errors":[{"property":"attribute","message":"Cannot set value \"Option A\" for the attribute axis \"a_simple_select\", as another sibling entity already has this value"}]}
{"line":3,"code":"tshirt","status_code":201}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a product model
This endpoint allows you to get the information about a given product model. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product model you request.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/product-models/{code}
Query parameters
with_quality_scores
(boolean )
• Return product model quality scores in the response. (Only available since the 6.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the product model in JSON standard format.
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Product model code
family
(string )
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant
(string )
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string )
• Code of the parent product model. This parent can be modified since the 2.3.
categories
(array [string] )
• Codes of the categories in which the product model is categorized
values
(object )
• Product model attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product identifiers with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product identifiers and quantities with which the product model is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product model is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product model regarding the user permissions
}
quality_scores
(object )
• Product model quality scores for each channel/locale combination (only available since the 7.0 version and when the "with_quality_scores" query parameter is set to "true")
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a product model
This endpoint allows you to update a given product model. Learn more about Update behavior. Note that if no product model exists for the given code, it creates it. In the Enterprise Edition PIM since the 2.3, permissions based on your user groups are applied to the product model you try to update. It may result in the creation of a draft if you only have edit rights through the product model's categories.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/product-models/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Product model code
family
(string
)
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant
(string
)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string
,
null
by default)
• Code of the parent product model. This parent can be modified since the 2.3.
categories
(array
[string]
,
[]
by default)
• Codes of the categories in which the product model is categorized
values
(object
)
• Product model attributes values, see Product values section for more details
associations
(object
{
associationTypeCode : object
{
groups : array
[string]
,
products : array
[string]
,
product_models : array
[string]
}
}
)
• Several associations related to groups, product and/or other product models, grouped by association types
quantified_associations
(object
{
quantifiedAssociationTypeCode : object
{
products : array
[object]
,
product_models : array
[object]
}
}
)
• Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
metadata
(object
{
workflow_status : string
}
)
• More information around the product model (only available since the v2.3 in the Enterprise Edition)
quality_scores
(object
)
• Product model quality scores for each channel/locale combination (only available since the 7.0 version and when the "with_quality_scores" query parameter is set to "true")
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product model
This endpoint allows you to delete a given product model. All its children, product models and variant products, will be also deleted. In the Enterprise Edition, the permissions based on your connection user group are applied to the product model you try to delete.
Available in PIM versions: 6.0 7.0 SaaS
REQUEST
delete /api/rest/v1/product-models/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return
Means that the deletion was successful
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval EE only
This endpoint allows you to submit a product model draft for approval.
Available in PIM versions: 2.3 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/product-models/{code}/proposal
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Submitted
Means that the draft submission was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft EE only
This endpoint allows you to get the information about a given product model draft.
Available in PIM versions: 2.3 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/product-models/{code}/draft
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the draft in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Product model code
family
(string )
• Family code from which the product inherits its attributes and attributes requirements (since the 3.2)
family_variant
(string )
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string )
• Code of the parent product model. This parent can be modified since the 2.3.
categories
(array [string] )
• Codes of the categories in which the product model is categorized
values
(object )
• Product model attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the product is in relation
products
(array
[string]
)
• Array of product identifiers with which the product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
: {
quantifiedAssociationTypeCode
(object
)
: {
products
(array
[object]
)
• Array of objects containing product identifiers and quantities with which the product model is in relation
product_models
(array
[object]
)
• Array of objects containing product model codes and quantities with which the product model is in relation
}
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
metadata
(object )
: {
workflow_status
(string
)
• Status of the product model regarding the user permissions
}
quality_scores
(object )
• Product model quality scores for each channel/locale combination (only available since the 7.0 version and when the "with_quality_scores" query parameter is set to "true")
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Product media file
Get a list of product media files
This endpoint allows you to get a list of media files that are used as attribute values in products or product models.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/media-files
Path parameters
Ø
Query parameters
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return media files paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI to get the metadata of the media file
}
download (object)
: {
href
(string ) • URI to download the binaries of the media file
}
}
code (string)
• Media file code
original_filename (string)
• Original filename of the media file
mime_type (string)
• Mime type of the media file
size (integer)
• Size of the media file
extension (string)
• Extension of the media file
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
}
},
"current_page": 2,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg/download"
}
},
"code": "d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg",
"original_filename": "10734346-1480.jpg",
"mime_type": "image/jpeg",
"size": 16454,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg/download"
}
},
"code": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg",
"original_filename": "12431976-8797.jpg",
"mime_type": "image/jpeg",
"size": 19725,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg/download"
}
},
"code": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg",
"original_filename": "107406-9841.jpg",
"mime_type": "image/jpeg",
"size": 17639,
"extension": "jpg"
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new product media file
This endpoint allows you to create a new media file and associate it to an attribute value of a given product or product model.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'multipart/form-data', no other value allowed
Body
Given as form-data
product
(string )
• The product to which the media file will be associated. It is a JSON string that follows this format '{"identifier":"product_identifier", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'. You have to either use this field or the `product_model` field, but not both at the same time.
product_model
(string )
• The product model to which the media file will be associated. It is a JSON string that follows this format '{"code":"product_model_code", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'. You have to either use this field or the `product` field, but not both at the same time.
RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `multipart/form-data`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘multipart/form-data’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a product media file
This endpoint allows you to get the information about a given media file that is used as an attribute value of a product or a product model.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/media-files/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the media file in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
download (object )
: {
href (string ) • URI to download the binaries of the media file
}
}
code
(string)
• Media file code
original_filename
(string)
• Original filename of the media file
mime_type
(string)
• Mime type of the media file
size
(integer)
• Size of the media file
extension
(string)
• Extension of the media file
}
Example
{
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Download a product media file
This endpoint allows you to download a given media file that is used as an attribute value of a product or a product model.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/media-files/{code}/download
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
OK
Returns the binary of the media file
Body Format Mime-type of the media file
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Published products
Published product
Important update: Published Products discontinuation. This feature is no longer actively supported and will soon be retired. We recommend exploring alternative solutions. Learn more in the help center.
Get list of published products EE only
This endpoint allows you to get a list of published products. Published products are paginated and they can be filtered.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/published-products
Path parameters
Ø
Query parameters
search
(string )
• Filter published products, for more details see the Filters section
scope
(string )
• Filter published product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter on published product values section
locales
(string )
• Filter published product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter on published product values section
attributes
(string )
• Filter published product values to only return those concerning the given attributes, for more details see the Filter on product values section
pagination_type
(string ,
page
by default )
• Pagination method type, see Pagination section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return published products paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
identifier (string)
• Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled (boolean)
• Whether the published product is enable
family (string)
• Family code from which the published product inherits its attributes and attributes requirements
categories (array [string ])
• Codes of the categories in which the published product is classified
groups (array [string ])
• Codes of the groups to which the published product belong
values (object)
• Published product attributes values, see Product values section for more details
associations (object)
: {
associationTypeCode (object)
: {
groups
(array [string ] ) • Array of groups codes with which the published product is in relation
products
(array [string ] ) • Array of published product identifiers with which the published product is in relation
product_models
(array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations (object)
• Warning: associations with quantities are not compatible with the published products. The response will always be empty.
created (string)
• Date of creation
updated (string)
• Date of the last update
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/cap"
}
},
"identifier": "cap",
"family": "caps",
"groups": [],
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {}
}
]
}
}Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a published product EE only
This endpoint allows you to get the information about a given published product.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/published-products/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the published product in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
identifier
(string )
• Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
enabled
(boolean )
• Whether the published product is enable
family
(string )
• Family code from which the published product inherits its attributes and attributes requirements
categories
(array [string] )
• Codes of the categories in which the published product is classified
groups
(array [string] )
• Codes of the groups to which the published product belong
values
(object )
• Published product attributes values, see Product values section for more details
associations
(object )
: {
associationTypeCode
(object
)
: {
groups
(array
[string]
)
• Array of groups codes with which the published product is in relation
products
(array
[string]
)
• Array of published product identifiers with which the published product is in relation
product_models
(array
[string]
)
• Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations
(object )
• Warning: associations with quantities are not compatible with the published products. The response will always be empty.
created
(string )
• Date of creation
updated
(string )
• Date of the last update
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Catalog structure
Family
Get list of families
This endpoint allows you to get a list of families. Families are paginated and sorted by code.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/families
Path parameters
Ø
Query parameters
search
(string )
• Filter families, for more details see the Filters section.
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return families paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Family code
attribute_as_label (string)
• Attribute code used as label
attribute_as_image (string)
• Attribute code used as the main picture in the user interface (only since v2.0)
attributes (array [string ])
• Attributes codes that compose the family
attribute_requirements (object)
: {
channelCode (array [string ])
•
• Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
}
labels (object)
: {
localeCode (string)
• Family label for the locale `localeCode`
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=2&limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=3&limit=2"
}
},
"current_page": 2,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/tshirt"
}
},
"code": "tshirt",
"attributes": [
"sku",
"name",
"description",
"price",
"size",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"size",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Tshirt",
"fr_FR": "Tshirt"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/caps"
}
},
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new family
This endpoint allows you to create a new family.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
attribute_as_label
(string
)
• Attribute code used as label
attribute_as_image
(string
,
null
by default)
• Attribute code used as the main picture in the user interface (only since v2.0)
attributes
(array
[string]
,
[]
by default)
• Attributes codes that compose the family
attribute_requirements
(object
{
channelCode : array
[
string
]
}
)
• Attributes codes of the family that are required for the completeness calculation for each channel
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family labels for each locale
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several families
This endpoint allows you to update and/or create several families at once.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
attribute_as_label
(string
)
• Attribute code used as label
attribute_as_image
(string
,
null
by default)
• Attribute code used as the main picture in the user interface (only since v2.0)
attributes
(array
[string]
,
[]
by default)
• Attributes codes that compose the family
attribute_requirements
(object
{
channelCode : array
[
string
]
}
)
• Attributes codes of the family that are required for the completeness calculation for each channel
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family labels for each locale
}
Example
{"code":"tshirt","attributes":["description","size"]}
{"code":"cap","attribute_as_label":"descripion"}
{"code":"mug","attributes":["description","short_description"]}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"tshirt","status_code":201}
{"line":2,"code":"cap","status_code":422,"message":"Attribute \"descripion\" does not exist."}
{"line":3,"code":"mug","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a family
This endpoint allows you to get the information about a given family.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/families/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the family in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Family code
attribute_as_label
(string )
• Attribute code used as label
attribute_as_image
(string )
• Attribute code used as the main picture in the user interface (only since v2.0)
attributes
(array [string] )
• Attributes codes that compose the family
attribute_requirements
(object )
: {
channelCode
(array
[string]
)
• Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
}
labels
(object )
: {
localeCode
(string
)
• Family label for the locale `localeCode`
}
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a family
This endpoint allows you to update a given family. Know more about Update behavior. Note that if no family exists for the given code, it creates it.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/families/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
attribute_as_label
(string
)
• Attribute code used as label
attribute_as_image
(string
,
null
by default)
• Attribute code used as the main picture in the user interface (only since v2.0)
attributes
(array
[string]
,
[]
by default)
• Attributes codes that compose the family
attribute_requirements
(object
{
channelCode : array
[
string
]
}
)
• Attributes codes of the family that are required for the completeness calculation for each channel
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family labels for each locale
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new family variant
This endpoint allows you to create a family variant.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/families/{family_code}/variants
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Family variant code
variant_attribute_sets
(array
[object]
)
: [
{
level
(integer
)
• Enrichment level
axes
(array
[string
])
• Codes of attributes used as variant axes
attributes
(array
[string
])
• Codes of attributes bind to this enrichment level
}
]
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family variant labels for each locale
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Family variant
Get list of family variants
This endpoint allows you to get a list of family variants. Family variants are paginated and sorted by code.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/families/{family_code}/variants
Query parameters
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return family variants paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Family variant code
variant_attribute_sets (array [object ])
• Attributes distribution according to the enrichment level
labels (object)
: {
localeCode (string)
• Family variant label for the locale `localeCode`
}
}
]
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create several family variants
This endpoint allows you to update and/or create several family variants at once, for a given family.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/families/{family_code}/variants
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
code
(string
)
• Family variant code
variant_attribute_sets
(array
[object]
)
: [
{
level
(integer
)
• Enrichment level
axes
(array
[string
])
• Codes of attributes used as variant axes
attributes
(array
[string
])
• Codes of attributes bind to this enrichment level
}
]
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family variant labels for each locale
}
Example
{"code": "shoes_by_size", "variant_attribute_sets": [{"level": 1, "axes": ["size"], "attributes": ["color"]}]}
{"code": "shoes_by_color","labels": {"en_US": "Shoes by color"}}
{"code": "shoes_without_axes", "variant_attribute_sets": [{"level": 1, "axes": [], "attributes": ["color"]}]}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"shoes_by_size","status_code":201}
{"line":2,"code":"shoes_by_color","status_code":204}
{"line":3,"code":"mug","status_code":422, "message":"There should be at least one attribute defined as axis for the attribute set for level \"1\""}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a family variant
This endpoint allows you to get the information about a given family variant.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/families/{family_code}/variants/{code}
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the family variant in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Family variant code
variant_attribute_sets
(array [object] )
: [
{
level
(integer)
• Enrichment level
axes
(array)
• Codes of attributes used as variant axes
attributes
(array)
• Codes of attributes bind to this enrichment level
}
]
labels
(object )
: {
localeCode
(string
)
• Family variant label for the locale `localeCode`
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a family variant
This endpoint allows you to update a given family variant. Know more about Update behavior. Note that if no family variant exists for the given code, it creates it.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/families/{family_code}/variants/{code}
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Family variant code
variant_attribute_sets
(array
[object]
)
: [
{
level
(integer
)
• Enrichment level
axes
(array
[string
])
• Codes of attributes used as variant axes
attributes
(array
[string
])
• Codes of attributes bind to this enrichment level
}
]
labels
(object
{
localeCode : string
}
,
[]
by default)
• Family variant labels for each locale
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Attribute
Get list of attributes
This endpoint allows you to get a list of attributes. Attributes are paginated and sorted by code.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attributes
Path parameters
Ø
Query parameters
search
(string )
• Filter attributes, for more details see the Filters section.
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
with_table_select_options
(boolean )
• Return the options of 'select' column types (of a table attribute) in the response. (Only available since the 7.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attributes paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Attribute code
type (string)
• Attribute type. See type section for more details.
labels (object)
: {
localeCode (string)
• Attribute label for the locale `localeCode`
}
group (string)
• Attribute group
group_labels (object)
: {
localeCode (string)
• Group label for the locale `localeCode`
}
sort_order (integer)
• Order of the attribute in its group
localizable (boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable (boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales (array [string ])
• To make the attribute locale specfic, specify here for which locales it is specific
unique (boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter (boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters (integer)
• Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
validation_rule (string)
• Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
validation_regexp (string)
• Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
wysiwyg_enabled (boolean)
• Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
number_min (string)
• Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
number_max (string)
• Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
decimals_allowed (boolean)
• Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
negative_allowed (boolean)
• Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
metric_family (string)
• Metric family when the attribute type is `pim_catalog_metric`
default_metric_unit (string)
• Default metric unit when the attribute type is `pim_catalog_metric`
date_min (string)
• Minimum date allowed when the attribute type is `pim_catalog_date`
date_max (string)
• Maximum date allowed when the attribute type is `pim_catalog_date`
allowed_extensions (array [string ])
• Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
max_file_size (string)
• Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
reference_data_name (string)
• Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
default_value (boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)
table_configuration (array [object ])
• Configuration of the Table attribute (columns)
is_main_identifier (boolean)
• Is this attribute main identifier when attribute type is `pim_catalog_identifier`
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/sku"
}
},
"code": "sku",
"type": "pim_catalog_identifier",
"group": "other",
"group_labels": {
"en_US": "Other",
"fr_FR": "Autre"
},
"unique": true,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Identifier",
"fr_FR": "Identifiant"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/release_date"
}
},
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
},
{
"_links": {
"self": {
"href": "http://localhost:8080/api/rest/v1/attributes/food_composition"
}
},
"code": "food_composition",
"type": "pim_catalog_table",
"group": "product",
"unique": false,
"useable_as_grid_filter": false,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 0,
"localizable": false,
"scopable": false,
"labels": {
"en_US": "Composition",
"fr_FR": "Composition"
},
"guidelines": {},
"auto_option_sorting": null,
"is_read_only": null,
"default_value": null,
"table_configuration": [
{
"code": "ingredient",
"data_type": "select",
"labels": {
"en_US": "Ingredient",
"fr_FR": "Ingrédient"
},
"validations": {},
"is_required_for_completeness": true
},
{
"code": "percentage",
"data_type": "number",
"labels": {
"en_US": "%",
"fr_FR": "%"
},
"validations": {
"max": 100,
"min": 0,
"decimals_allowed": true
},
"is_required_for_completeness": true
},
{
"code": "allergen",
"data_type": "boolean",
"labels": {
"en_US": "Allergen",
"fr_FR": "Allergène"
},
"validations": {},
"is_required_for_completeness": false
}
]
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new attribute
This endpoint allows you to create a new attribute.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/attributes
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute code
type
(string
)
• Attribute type. See type section for more details.
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute labels for each locale
group
(string
)
• Attribute group
sort_order
(integer
,
0
by default)
• Order of the attribute in its group
localizable
(boolean
,
false
by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean
,
false
by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array
[string]
)
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean
)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean
)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer
)
• Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
validation_rule
(string
)
• Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
validation_regexp
(string
)
• Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
wysiwyg_enabled
(boolean
)
• Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
number_min
(string
)
• Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
number_max
(string
)
• Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
decimals_allowed
(boolean
)
• Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
negative_allowed
(boolean
)
• Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
metric_family
(string
)
• Metric family when the attribute type is `pim_catalog_metric`
default_metric_unit
(string
)
• Default metric unit when the attribute type is `pim_catalog_metric`
date_min
(string
)
• Minimum date allowed when the attribute type is `pim_catalog_date`
date_max
(string
)
• Maximum date allowed when the attribute type is `pim_catalog_date`
allowed_extensions
(array
[string]
)
• Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
max_file_size
(string
)
• Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
reference_data_name
(string
)
• Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
default_value
(boolean
)
• Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)
table_configuration
(array
[object]
)
: [
{
code
(string
)
• Column code
data_type
(string
)
• Column data type
validations
(object
)
• User defined validation constraints on the cell content
labels
(object
)
• Column labels for each locale
is_required_for_completeness
(boolean
)
• Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean
)
• Is this attribute main identifier when attribute type is `pim_catalog_identifier`
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several attributes
This endpoint allows you to update and/or create several attributes at once.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attributes
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute in JSON standard format
{
code
(string
)
• Attribute code
type
(string
)
• Attribute type. See type section for more details.
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute labels for each locale
group
(string
)
• Attribute group
group_labels
(object
{
localeCode : string
}
,
[]
by default)
• Group labels for each locale
sort_order
(integer
,
0
by default)
• Order of the attribute in its group
localizable
(boolean
,
false
by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean
,
false
by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array
[string]
)
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean
)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean
)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer
)
• Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
validation_rule
(string
)
• Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
validation_regexp
(string
)
• Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
wysiwyg_enabled
(boolean
)
• Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
number_min
(string
)
• Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
number_max
(string
)
• Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
decimals_allowed
(boolean
)
• Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
negative_allowed
(boolean
)
• Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
metric_family
(string
)
• Metric family when the attribute type is `pim_catalog_metric`
default_metric_unit
(string
)
• Default metric unit when the attribute type is `pim_catalog_metric`
date_min
(string
)
• Minimum date allowed when the attribute type is `pim_catalog_date`
date_max
(string
)
• Maximum date allowed when the attribute type is `pim_catalog_date`
allowed_extensions
(array
[string]
)
• Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
max_file_size
(string
)
• Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
reference_data_name
(string
)
• Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
default_value
(boolean
)
• Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)
table_configuration
(array
[object]
)
: [
{
code
(string
)
• Column code
data_type
(string
)
• Column data type
validations
(object
)
• User defined validation constraints on the cell content
labels
(object
)
• Column labels for each locale
is_required_for_completeness
(boolean
)
• Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean
)
• Is this attribute main identifier when attribute type is `pim_catalog_identifier`
}
Example
{"code":"description","useable_as_grid_filter":true}
{"code":"short_description","group":"marketig"}
{"code":"release_date","date_min":"2017-06-28T08:00:00"}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"description","status_code":201}
{"line":2,"code":"short_description","status_code":422,"message":"Group \"marketig\" does not exist."}
{"line":3,"code":"release_date","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get an attribute
This endpoint allows you to get the information about a given attribute.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attributes/{code}
Query parameters
with_table_select_options
(boolean )
• Return the options of 'select' column types (of a table attribute) in the response. (Only available since the 7.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the attribute in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute code
type
(string )
• Attribute type. See type section for more details.
labels
(object )
: {
localeCode
(string
)
• Attribute label for the locale `localeCode`
}
group
(string )
• Attribute group
group_labels
(object )
: {
localeCode
(string
)
• Group label for the locale `localeCode`
}
sort_order
(integer )
• Order of the attribute in its group
localizable
(boolean )
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean )
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array [string] )
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean )
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean )
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer )
• Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
validation_rule
(string )
• Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
validation_regexp
(string )
• Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
wysiwyg_enabled
(boolean )
• Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
number_min
(string )
• Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
number_max
(string )
• Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
decimals_allowed
(boolean )
• Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
negative_allowed
(boolean )
• Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
metric_family
(string )
• Metric family when the attribute type is `pim_catalog_metric`
default_metric_unit
(string )
• Default metric unit when the attribute type is `pim_catalog_metric`
date_min
(string )
• Minimum date allowed when the attribute type is `pim_catalog_date`
date_max
(string )
• Maximum date allowed when the attribute type is `pim_catalog_date`
allowed_extensions
(array [string] )
• Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
max_file_size
(string )
• Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
reference_data_name
(string )
• Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
default_value
(boolean )
• Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)
table_configuration
(array [object] )
: [
{
code
(string)
• Column code
data_type
(string)
• Column data type
validations
(object)
• User defined validation constraints on the cell content
labels
(object)
• Column labels for each locale
is_required_for_completeness
(boolean)
• Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean )
• Is this attribute main identifier when attribute type is `pim_catalog_identifier`
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an attribute
This endpoint allows you to update a given attribute. Know more about Update behavior. Note that if no attribute exists for the given code, it creates it.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attributes/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute code
type
(string
)
• Attribute type. See type section for more details.
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute labels for each locale
group
(string
)
• Attribute group
group_labels
(object
{
localeCode : string
}
,
[]
by default)
• Group labels for each locale
sort_order
(integer
,
0
by default)
• Order of the attribute in its group
localizable
(boolean
,
false
by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean
,
false
by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array
[string]
)
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean
)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean
)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer
)
• Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
validation_rule
(string
)
• Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
validation_regexp
(string
)
• Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
wysiwyg_enabled
(boolean
)
• Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
number_min
(string
)
• Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
number_max
(string
)
• Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
decimals_allowed
(boolean
)
• Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
negative_allowed
(boolean
)
• Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
metric_family
(string
)
• Metric family when the attribute type is `pim_catalog_metric`
default_metric_unit
(string
)
• Default metric unit when the attribute type is `pim_catalog_metric`
date_min
(string
)
• Minimum date allowed when the attribute type is `pim_catalog_date`
date_max
(string
)
• Maximum date allowed when the attribute type is `pim_catalog_date`
allowed_extensions
(array
[string]
)
• Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
max_file_size
(string
)
• Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
reference_data_name
(string
)
• Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
default_value
(boolean
)
• Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)
table_configuration
(array
[object]
)
: [
{
code
(string
)
• Column code
data_type
(string
)
• Column data type
validations
(object
)
• User defined validation constraints on the cell content
labels
(object
)
• Column labels for each locale
is_required_for_completeness
(boolean
)
• Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean
)
• Is this attribute main identifier when attribute type is `pim_catalog_identifier`
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Attribute option
Get list of attribute options
This endpoint allows you to get a list of attribute options. Attribute options are paginated and sorted by code.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attributes/{attribute_code}/options
Query parameters
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attribute options paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Code of option
attribute (string)
• Code of attribute related to the attribute option
sort_order (integer)
• Order of attribute option
labels (object)
: {
localeCode (string)
• Attribute option label for the locale `localeCode`
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/red"
}
},
"code": "red",
"attribute": "a_simple_select",
"sort_order": 1,
"labels": {
"en_US": "Red",
"fr_FR": "Rouge"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/black"
}
},
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/purple"
}
},
"code": "purple",
"attribute": "a_simple_select",
"sort_order": 3,
"labels": {
"en_US": "Purple",
"fr_FR": "Violet"
}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new attribute option
This endpoint allows you to create a new attribute option.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/attributes/{attribute_code}/options
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several attribute options
This endpoint allows you to update several attribute options at once. Please note that this endpoint applies a rate limit of 3 concurrent API requests per second.
Available in PIM versions: 2.1 2.2 2.3 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attributes/{attribute_code}/options
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute option in JSON standard format
Example
{"code":"black", "attribute":"a_simple_select", "labels":{"en_US": "Black","fr_FR": "Noir"}}
{"code":"red", "label":{"en_US": "Red","fr_FR": "Rouge"}}
{"code":"yellow", "labels":{"en_US": "Yellow","fr_FR": "Jaune"}}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"black","status_code":201}
{"line":2,"code":"red","status_code":422,"message":"Property \"label\" does not exist. Check the API format documentation."}
{"line":3,"code":"yellow","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Too many requests
There are too many requests on this endpoint
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 429,
"message": "You have exceeded the limit of API requests per second."
}Get an attribute option
This endpoint allows you to get the information about a given attribute option.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attributes/{attribute_code}/options/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the attribute option in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Code of option
attribute
(string )
• Code of attribute related to the attribute option
sort_order
(integer )
• Order of attribute option
labels
(object )
: {
localeCode
(string
)
• Attribute option label for the locale `localeCode`
}
}
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an attribute option
This endpoint allows you to update a given attribute option. Know more about Update behavior. Note that if no attribute option exists for the given code, it creates it. Please note that this endpoint applies a rate limit of 3 concurrent API requests per second.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attributes/{attribute_code}/options/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Too many requests
There are too many requests on this endpoint
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 429,
"message": "You have exceeded the limit of API requests per second."
}Attribute group
Get list of attribute groups
This endpoint allows you to get a list of attribute groups. Attribute groups are paginated and sorted by code.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
search
(string )
• Filter attribute groups, for more details see the Filters section.
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attribute groups paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Attribute group code
sort_order (integer)
• Attribute group order among other attribute groups
attributes (array [string ])
• Attribute codes that compose the attribute group
labels (object)
: {
localeCode (string)
• Attribute group label for the locale `localeCode`
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=3&limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=1&limit=2"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=2&limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=4&limit=2"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/marketing"
}
},
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/technical"
}
},
"code": "technical",
"sort_order": 5,
"attributes": [
"weight",
"maximum_scan_size",
"color_scanning",
"power_requirements",
"maximum_print_size",
"sensor_type",
"total_megapixels",
"optical_zoom",
"camera_type"
],
"labels": {
"en_US": "Technical",
"fr_FR": "Technique"
}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new attribute group
This endpoint allows you to create a new attribute group.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute group code
sort_order
(integer
,
0
by default)
• Attribute group order among other attribute groups
attributes
(array
[string]
,
[]
by default)
• Attribute codes that compose the attribute group
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute group labels for each locale
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several attribute groups
This endpoint allows you to update and/or create several attribute groups at once.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute group in JSON standard format
{
code
(string
)
• Attribute group code
sort_order
(integer
,
0
by default)
• Attribute group order among other attribute groups
attributes
(array
[string]
,
[]
by default)
• Attribute codes that compose the attribute group
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute group labels for each locale
}
Example
{"code":"technical","labels":{"en_US": "Technical", "fr_FR": "Technique"}}
{"code":"marketing","type":"bar"}
{"code":"design","sort_order":7}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
Follow the standard format of the entity
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"technical","status_code":201}
{"line":2,"code":"marketing","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_attribute_groups__code_"}}}
{"line":3,"code":"design","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get an attribute group
This endpoint allows you to get the information about a given attribute group.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/attribute-groups/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the attribute group in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute group code
sort_order
(integer )
• Attribute group order among other attribute groups
attributes
(array [string] )
• Attribute codes that compose the attribute group
labels
(object )
: {
localeCode
(string
)
• Attribute group label for the locale `localeCode`
}
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an attribute group
This endpoint allows you to update a given attribute group. Know more about Update behavior. Note that if no attribute group exists for the given code, it creates it.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/attribute-groups/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute group code
sort_order
(integer
,
0
by default)
• Attribute group order among other attribute groups
attributes
(array
[string]
,
[]
by default)
• Attribute codes that compose the attribute group
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute group labels for each locale
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Association type
Get a list of association types
This endpoint allows you to get a list of association types. Association types are paginated and sorted by code.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/association-types
Path parameters
Ø
Query parameters
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return association types paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Association type code
labels (object)
: {
localeCode (string)
• Association type label for the locale `localeCode`
}
is_quantified (boolean)
• When true, the association is a quantified association (Only available in the PIM Serenity version.)
is_two_way (boolean)
• When true, the association is a two-way association (Only available in the PIM Serenity version.)
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/X_SELL"
}
},
"code": "X_SELL",
"labels": {
"en_US": "Cross sell",
"fr_FR": "Vente croisée"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/UPSELL"
}
},
"code": "UPSELL",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/SUBSTITUTION"
}
},
"code": "SUBSTITUTION",
"labels": {
"en_US": "Substitution",
"fr_FR": "Remplacement"
},
"is_quantified": false,
"is_two_way": false
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new association type
This endpoint allows you to create a new association type.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/association-types
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Association type code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Association type labels for each locale
is_quantified
(boolean
,
false
by default)
• When true, the association is a quantified association (Only available in the PIM Serenity version.)
is_two_way
(boolean
,
false
by default)
• When true, the association is a two-way association (Only available in the PIM Serenity version.)
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several association types
This endpoint allows you to update and/or create several association types at once.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/association-types
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an association type in JSON standard format
{
code
(string
)
• Association type code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Association type labels for each locale
is_quantified
(boolean
,
false
by default)
• When true, the association is a quantified association (Only available in the PIM Serenity version.)
is_two_way
(boolean
,
false
by default)
• When true, the association is a two-way association (Only available in the PIM Serenity version.)
}
Example
{"code":"new_sell"}
{"code":"substitution", "type":"bar"}
{"code":"x_cross_sell", "is_two_way": true, "is_quantified": false}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
Follow the standard format of the entity
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"new_sell","status_code":201}
{"line":2,"code":"substitution","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_association_types__code_"}}}
{"line":3,"code":"x_cross_sell","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get an association type
This endpoint allows you to get the information about a given association type.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/association-types/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the association type in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Association type code
labels
(object )
: {
localeCode
(string
)
• Association type label for the locale `localeCode`
}
is_quantified
(boolean )
• When true, the association is a quantified association (Only available in the PIM Serenity version.)
is_two_way
(boolean )
• When true, the association is a two-way association (Only available in the PIM Serenity version.)
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an association type
This endpoint allows you to update a given association type. Know more about Update behavior. Note that if no association type exists for the given code, it creates it.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/association-types/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Association type code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Association type labels for each locale
is_quantified
(boolean
,
false
by default)
• When true, the association is a quantified association (Only available in the PIM Serenity version.)
is_two_way
(boolean
,
false
by default)
• When true, the association is a two-way association (Only available in the PIM Serenity version.)
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Category
Get list of categories
This endpoint allows you to get a list of categories. Categories are paginated and sorted by `root/left`.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/categories
Path parameters
Ø
Query parameters
search
(string )
• Filter categories, for more details see the Filters section.
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
with_position
(boolean )
• Return information about category position into its category tree (only available since the 7.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return categories paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Category code
parent (string)
• Category code of the parent's category
updated (string)
• Date of the last update
position (integer)
• Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")
labels (object)
: {
localeCode (string)
• Category label for the locale `localeCode`
}
values (object)
: {
attributeCode|attributeUuid|channelCode|localeCode (array [object ])
•
: [
{
data
(object ) • Attribute value
type
(string ) • The attribute type
locale
(string ) • Locale code of the attribute value
channel
(string ) • Channel code of the attribute value
attribute_code
(string ) • The attribute code with its uuid (attributeCode|attributeUuid)
}
]
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5"
}
},
"current_page": 2,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/winter_collection"
}
},
"code": "winter_collection",
"parent": null,
"updated": "2021-05-21T11:32:00+02:00",
"position": 1,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver",
"de_DE": "Winter-Kollektion"
},
"values": {
"description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
"data": "<p>Winter collection description</p>\n",
"type": "textarea",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
},
"image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
"data": {
"size": 1401359,
"extension": "jpg",
"file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
"mime_type": "image/jpeg",
"original_filename": "IMG_7860.jpg"
},
"type": "image",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/woman"
}
},
"code": "woman",
"parent": "winter_collection",
"updated": "2021-04-21T10:41:02+02:00",
"position": 1,
"labels": {
"en_US": "Woman",
"fr_FR": "Femme",
"de_DE": "Damen"
},
"values": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/man"
}
},
"code": "man",
"parent": "winter_collection",
"updated": "2021-03-02T12:59:59+02:00",
"position": 2,
"labels": {
"en_US": "Man",
"fr_FR": "Homme",
"de_DE": "Herren"
},
"values": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/kids"
}
},
"code": "kids",
"parent": "winter_collection",
"updated": "2021-01-03T12:40:00+02:00",
"position": 3,
"labels": {
"en_US": "Kids",
"fr_FR": "Enfant",
"de_DE": "Kinder"
},
"values": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/summer_collection"
}
},
"code": "summer_collection",
"parent": null,
"updated": "2021-04-04T09:42:00+02:00",
"position": 1,
"labels": {
"en_US": "Summer collection",
"fr_FR": "Collection été",
"de_DE": "Sommer-Kollektion"
},
"values": {}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new category
This endpoint allows you to create a new category.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/categories
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Category code
parent
(string
,
null
by default)
• Category code of the parent's category
labels
(object
{
localeCode : string
}
,
[]
by default)
• Category labels for each locale
values
(array
[object]
,
[]
by default)
: [
{
data
(string
)
• Attribute value. It should be a `string` for Text and Text Area attributes, a `boolean` for Yes/No attribute and for Image attribute use the create category media file endpoint. It can also be `null` to remove the value.
locale
(string
)
• Locale code of the attribute value.
channel
(string
)
• Channel code of the attribute value.
attribute_code
(string
)
• The attribute code.
}
]
}
Example
{
"code": "winter_collection",
"parent": null,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": [
{
"data": "<p>Winter collection description</p>",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_text_area_attribute"
},
{
"data": false,
"channel": "ecommerce",
"locale": null,
"attribute_code": "a_boolean_attribute"
},
{
"data": null,
"channel": null,
"locale": null,
"attribute_code": "an_image_attribute"
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several categories
This endpoint allows you to update several categories at once.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/categories
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a category in JSON standard format
{
code
(string
)
• Category code
parent
(string
,
null
by default)
• Category code of the parent's category
updated
(string
)
• Date of the last update
position
(integer
)
• Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")
labels
(object
{
localeCode : string
}
,
[]
by default)
• Category labels for each locale
values
(array
[object]
,
[]
by default)
: [
{
data
(string
)
• Attribute value. It should be a `string` for Text and Text Area attributes, a `boolean` for Yes/No attribute and for Image attribute use the create category media file endpoint. It can also be `null` to remove the value.
locale
(string
)
• Locale code of the attribute value.
channel
(string
)
• Channel code of the attribute value.
attribute_code
(string
)
• The attribute code.
}
]
}
Example
{"code":"spring_collection","parent":null}
{"code":"woman","parent":"spring_collectionn"}
{"code":"man","parent":"spring_collection"}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"spring_collection","status_code":201}
{"line":2,"code":"woman","status_code":422,"message":"Category \"spring_collectionn\" does not exist."}
{"line":3,"code":"man","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a category
This endpoint allows you to get the information about a given category.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/categories/{code}
Query parameters
with_position
(boolean )
• Return information about category position into its category tree (only available since the 7.0 version)
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the category in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Category code
parent
(string )
• Category code of the parent's category
updated
(string )
• Date of the last update
position
(integer )
• Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")
labels
(object )
: {
localeCode
(string
)
• Category label for the locale `localeCode`
}
values
(object )
: {
attributeCode|attributeUuid|channelCode|localeCode
(array
[object]
)
: [
{
data
(object
)
• Attribute value
type
(string
)
• The attribute type
locale
(string
)
• Locale code of the attribute value
channel
(string
)
• Channel code of the attribute value
attribute_code
(string
)
• The attribute code with its uuid (attributeCode|attributeUuid)
}
]
}
}
Example
{
"code": "winter_collection",
"parent": null,
"updated": "2021-05-22T12:48:00+02:00",
"position": 1,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": {
"description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
"data": "<p>Winter collection description</p>\n",
"type": "textarea",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
},
"image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
"data": {
"size": 1401359,
"extension": "jpg",
"file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
"mime_type": "image/jpeg",
"original_filename": "IMG_7860.jpg"
},
"type": "image",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
}
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a category
This endpoint allows you to update a given category. Know more about Update behavior. Note that if no category exists for the given code, it creates it.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/categories/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Category code
parent
(string
,
null
by default)
• Category code of the parent's category
updated
(string
)
• Date of the last update
position
(integer
)
• Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")
labels
(object
{
localeCode : string
}
,
[]
by default)
• Category labels for each locale
values
(array
[object]
,
[]
by default)
: [
{
data
(string
)
• Attribute value. It should be a `string` for Text and Text Area attributes, a `boolean` for Yes/No attribute and for Image attribute use the create category media file endpoint. It can also be `null` to remove the value.
locale
(string
)
• Locale code of the attribute value.
channel
(string
)
• Channel code of the attribute value.
attribute_code
(string
)
• The attribute code.
}
]
}
Example
{
"code": "winter_collection",
"parent": null,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": [
{
"data": "<p>Winter collection description</p>",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_text_area_attribute"
},
{
"data": false,
"channel": "ecommerce",
"locale": null,
"attribute_code": "a_boolean_attribute"
},
{
"data": null,
"channel": null,
"locale": null,
"attribute_code": "an_image_attribute"
}
]
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Target market settings
Channel
Get a list of channels
This endpoint allows you to get a list of channels. Channels are paginated and sorted by code.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/channels
Path parameters
Ø
Query parameters
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return channels paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Channel code
locales (array [string ])
• Codes of activated locales for the channel
currencies (array [string ])
• Codes of activated currencies for the channel
category_tree (string)
• Code of the category tree linked to the channel
conversion_units (object)
: {
attributeCode (string)
• Conversion unit code used to convert the values of the attribute `attributeCode` when exporting via the channel
}
labels (object)
: {
localeCode (string)
• Channel label for the locale `localeCode`
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/ecommerce"
}
},
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {
"a_metric": "KILOWATT",
"a_metric_negative": "CELSIUS",
"a_metric_to_not_convert": null
},
"labels": {
"en_US": "Ecommerce",
"fr_FR": "E-commerce",
"de_DE": "E-commerce"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/mobile"
}
},
"code": "mobile",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {
"a_metric": "KILOWATT",
"a_metric_negative": "CELSIUS",
"a_metric_to_not_convert": null
},
"labels": {
"en_US": "Mobile",
"fr_FR": "Mobile",
"de_DE": "Mobile"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/print"
}
},
"code": "print",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {},
"labels": {
"en_US": "Print",
"fr_FR": "Print",
"de_DE": "Print"
}
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Create a new channel
This endpoint allows you to create a new channel.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/channels
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
locales
(array
[string]
)
• Codes of activated locales for the channel
currencies
(array
[string]
)
• Codes of activated currencies for the channel
category_tree
(string
)
• Code of the category tree linked to the channel
conversion_units
(object
{
attributeCode : string
}
)
• Units to which the given metric attributes should be converted when exporting products
labels
(object
{
localeCode : string
}
,
[]
by default)
• Channel labels for each locale
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several channels
This endpoint allows you to update and/or create several channels at once.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/channels
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a channel in JSON standard format
{
locales
(array
[string]
)
• Codes of activated locales for the channel
currencies
(array
[string]
)
• Codes of activated currencies for the channel
category_tree
(string
)
• Code of the category tree linked to the channel
conversion_units
(object
{
attributeCode : string
}
)
• Units to which the given metric attributes should be converted when exporting products
labels
(object
{
localeCode : string
}
,
[]
by default)
• Channel labels for each locale
}
Example
{"code":"ecommerce_fr", "category_tree": "master", "currencies": ["EUR"], "locales": ["fr_FR"], "labels":{"fr_FR": "Ecommerce Fr"}}
{"code":"ecommerce_ch", "type":"bar"}
{"code":"tablet", "labels":{"en_US": "Tablet", "fr_FR": "Tablette"}}RESPONSES
OK
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
Follow the standard format of the entity
{
line
(integer )
• Line number
identifier
(string )
• Resource identifier, only filled when the resource is a product
code
(string )
• Resource code, only filled when the resource is not a product
status_code
(integer )
• HTTP status code, see Client errors to understand the meaning of each code
message
(string )
• Message explaining the error
}
Example
{"line":1,"code":"ecommerce_fr","status_code":201}
{"line":2,"code":"ecommerce_ch","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_channels__code_"}}}
{"line":3,"code":"tablet","status_code":204}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a channel
This endpoint allows you to get the information about a given channel.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/channels/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the channel in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Channel code
locales
(array [string] )
• Codes of activated locales for the channel
currencies
(array [string] )
• Codes of activated currencies for the channel
category_tree
(string )
• Code of the category tree linked to the channel
conversion_units
(object )
: {
attributeCode
(string
)
• Conversion unit code used to convert the values of the attribute `attributeCode` when exporting via the channel
}
labels
(object )
: {
localeCode
(string
)
• Channel label for the locale `localeCode`
}
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a channel
This endpoint allows you to update a given channel. Know more about Update behavior. Note that if no channel exists for the given code, it creates it.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/channels/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
locales
(array
[string]
)
• Codes of activated locales for the channel
currencies
(array
[string]
)
• Codes of activated currencies for the channel
category_tree
(string
)
• Code of the category tree linked to the channel
conversion_units
(object
{
attributeCode : string
}
)
• Units to which the given metric attributes should be converted when exporting products
labels
(object
{
localeCode : string
}
,
[]
by default)
• Channel labels for each locale
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Locale
Get a list of locales
This endpoint allows you to get a list of locales. Locales are paginated and sorted by code.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/locales
Path parameters
Ø
Query parameters
search
(string )
• Filter locales, for more details see the Filters section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return locales paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Locale code
enabled (boolean)
• Whether the locale is enabled
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=2&limit=4"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=4"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=4"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=2&limit=4"
}
},
"current_page": 2,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/en_US"
}
},
"code": "en_US",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/fr_FR"
}
},
"code": "fr_FR",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/de_DE"
}
},
"code": "de_DE",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/af_ZA"
}
},
"code": "af_ZA",
"enabled": false
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get a locale
This endpoint allows you to get the information about a given locale.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/locales/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the locale in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Locale code
enabled
(boolean )
• Whether the locale is enabled
}
Example
{
"code": "en_US",
"enable": true
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Currency
Get a list of currencies
This endpoint allows you to get a list of currencies. Currencies are paginated and sorted by code.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/currencies
Path parameters
Ø
Query parameters
search
(string )
• Filter currencies, for more details see the Filters section
page
(integer ,
1
by default )
• Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section
limit
(integer ,
10
by default )
• Number of results by page, see Pagination section
with_count
(boolean )
• Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return currencies paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Currency code
enabled (boolean)
• Whether the currency is enabled
label (string)
• Currency label
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/ADP"
}
},
"code": "ADP",
"enabled": true,
"label": "ADP (Andorran Peseta)"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/AED"
}
},
"code": "AED",
"enabled": true,
"label": "AED (United Arab Emirates Dirham)"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/AFA"
}
},
"code": "AFA",
"enabled": false,
"label": "AFA (Afghan Afghani (1927–2002))"
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get a currency
This endpoint allows you to get the information about a given currency.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/currencies/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the currency in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Currency code
enabled
(boolean )
• Whether the currency is enabled
label
(string )
• Currency label
}
Example
{
"code": "EUR",
"enabled": true,
"label": "EUR (Euro)"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Measure family
Get list of measure families (deprecated as of v5.0)
This endpoint allows you to get a list of measure families. Measure families are paginated and sorted by code.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/measure-families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return measure families paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
previous (object )
: {
href (string ) • URI of the previous page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Measure family code
standard (string)
• Measure family standard
units (array [object ])
• Family units
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/measure-families?page=1&limit=1"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/measure-families?page=1&limit=1"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/measure-families/Area"
}
},
"code": "Area",
"standard": "SQUARE_METER",
"units": [
{
"code": "SQUARE_MILLIMETER",
"convert": {
"mul": "0.000001"
},
"symbol": "mm²"
},
{
"code": "SQUARE_CENTIMETER",
"convert": {
"mul": "0.0001"
},
"symbol": "cm²"
},
{
"code": "SQUARE_DECIMETER",
"convert": {
"mul": "0.01"
},
"symbol": "dm²"
},
{
"code": "SQUARE_METER",
"convert": {
"mul": "1"
},
"symbol": "m²"
},
{
"code": "CENTIARE",
"convert": {
"mul": "1"
},
"symbol": "ca"
},
{
"code": "SQUARE_DEKAMETER",
"convert": {
"mul": "100"
},
"symbol": "dam²"
},
{
"code": "ARE",
"convert": {
"mul": "100"
},
"symbol": "a"
},
{
"code": "SQUARE_HECTOMETER",
"convert": {
"mul": "10000"
},
"symbol": "hm²"
}
]
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get a measure family (deprecated as of v5.0)
This endpoint allows you to get the information about a given measure family.
Available in PIM versions: 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/measure-families/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the measure family in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Measure family code
standard
(string )
• Measure family standard
units
(array [object] )
: [
{
code
(string)
• Measure code
convert
(object)
• Mathematic operation to convert the unit into the standard unit
symbol
(string)
• Measure symbol
}
]
}
Example
{
"code": "Area",
"standard": "SQUARE_METER",
"units": [
{
"code": "SQUARE_MILLIMETER",
"convert": {
"mul": "0.001"
},
"symbol": "mm²"
},
{
"code": "SQUARE_CENTIMETER",
"convert": {
"mul": "0.001"
},
"symbol": "cm²"
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Access forbidden
The user does not have the permission to execute this request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Measurement family
Get list of measurement families
This endpoint allows you to get a list of measurement families.
Available in PIM versions: 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/measurement-families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the measurement families
Body Format application/json
{
code
(string )
• Measurement family code
labels
(object )
: {
localeCode
(string
)
• Measurement family label for the locale `localeCode`
}
standard_unit_code
(string )
• Unit code used as the standard unit for this measurement family
units
(object )
: {
unitCode
(object
)
: {
code
(string
)
• Measurement unit code. More details here.
labels
(object
)
• Unit labels for each locale. More details here.
convert_from_standard
(array
[object]
)
• Calculation to convert the unit from the standard unit. More details here.
symbol
(string
)
• Measurement unit symbol. More details here.
}
}
}
Example
[
{
"code": "AREA",
"labels": {
"en_US": "Area",
"fr_FR": "Surface"
},
"standard_unit_code": "SQUARE_METER",
"units": {
"SQUARE_MILLIMETER": {
"code": "SQUARE_MILLIMETER",
"labels": {
"en_US": "Square millimeter",
"fr_FR": "Millimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.000001"
}
],
"symbol": "mm²"
},
"SQUARE_CENTIMETER": {
"code": "SQUARE_CENTIMETER",
"labels": {
"en_US": "Square centimeter",
"fr_FR": "Centimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.0001"
}
],
"symbol": "cm²"
},
"SQUARE_METER": {
"code": "SQUARE_METER",
"labels": {
"en_US": "Square meter",
"fr_FR": "Mètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "1"
}
],
"symbol": "m²"
}
}
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create several measurement families
This endpoint allows you to update and/or create several measurement families at once.
Available in PIM versions: 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/measurement-families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
[
code
(string
)
• Measurement family code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Measurement family labels for each locale
standard_unit_code
(string
)
• Unit code used as the standard unit for this measurement family
units
(object
{
unitCode : object
{
code : string
,
labels : object
,
convert_from_standard : array
[object]
,
symbol : string
}
}
)
• Measurement units for this family with their conversion operations. More details here.
]
}
Example
[
{
"code": "AREA",
"labels": {
"en_US": "Area",
"fr_FR": "Surface"
},
"standard_unit_code": "SQUARE_METER",
"units": {
"SQUARE_MILLIMETER": {
"code": "SQUARE_MILLIMETER",
"labels": {
"en_US": "Square millimeter",
"fr_FR": "Millimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.000001"
}
],
"symbol": "mm²"
},
"SQUARE_CENTIMETER": {
"code": "SQUARE_CENTIMETER",
"labels": {
"en_US": "Square centimeter",
"fr_FR": "Centimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.0001"
}
],
"symbol": "cm²"
},
"SQUARE_METER": {
"code": "SQUARE_METER",
"labels": {
"en_US": "Square meter",
"fr_FR": "Mètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "1"
}
],
"symbol": "m²"
}
}
}
]RESPONSES
OK
Returns a JSON containing the status of each update or creation
Body Format application/json
[
{
code
(string
)
• Resource code
status_code
(integer
)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string
)
• Message explaining the error
errors
(array
[object]
)
• List of errors
}
]
Example
[
{
"code": "Angle",
"status_code": 201
},
{
"code": "Force",
"status_code": 204
},
{
"code": "Area",
"status_code": 422,
"message": "The measurement family has data that does not comply with the business rules.",
"errors": [
{
"property": "standard_unit_code",
"message": "The standard unit code of the \"Angle\" measurement family cannot be changed"
}
]
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Reference entities
Reference entity
Get list of reference entities EE only
This endpoint allows you to get a list of reference entities. Reference entities are paginated.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities
Path parameters
Ø
Query parameters
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return reference entities paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
image_download (object)
: {
href
(string ) • URI to download the binaries of the reference entity image file
}
}
code (string)
• Reference entity code
labels (object)
: {
localeCode (string)
• Reference entity label for the locale `localeCode`
}
image (string)
• Code of the reference entity image
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities?search_after=2x055w%3D%3D"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands"
},
"image_download": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}
},
"code": "brands",
"labels": {
"en_US": "Brands",
"fr_FR": "Marque"
},
"image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/designers"
}
},
"code": "designers",
"labels": {
"en_US": "Designers",
"fr_FR": "Designers"
},
"image": null
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/colors"
}
},
"code": "colors",
"labels": {
"en_US": "Colors",
"fr_FR": "Couleurs"
},
"image": null
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get a reference entity EE only
This endpoint allows you to get the information about a given reference entity.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the reference entity in JSON format.
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
image_download (object )
: {
href (string ) • URI to download the binaries of the reference entity image file
}
}
code
(string)
• Reference entity code
labels
(object)
: {
localeCode (string )
• Reference entity label for the locale `localeCode`
}
image
(string)
• Code of the reference entity image
}
Example
{
"_links": {
"image_download": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}
},
"code": "brands",
"labels": {
"en_US": "Brands",
"fr_FR": "Marques"
},
"image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a reference entity EE only
This endpoint allows you to update a given reference entity. Note that if the reference entity does not already exist, it creates it.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/reference-entities/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "brands",
"labels": {
"en_US": "Brands",
"fr_FR": "Marques"
},
"image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Reference entity attribute
Get the list of attributes of a given reference entity EE only
This endpoint allows you to get the list of attributes of a given reference entity.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the attributes of the given reference entity
Body Format application/json
[
{
code
(string
)
• Attribute code
labels
(object
)
• Attribute labels for each locale
type
(string
)
• Attribute type. See type section for more details.
value_per_locale
(boolean
)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean
)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean
)
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer
)
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean
)
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean
)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string
)
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string
)
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array
[string]
)
• Extensions allowed when the attribute type is `image`
max_file_size
(string
)
• Max file size in MB when the attribute type is `image`
reference_entity_code
(string
)
• Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`
asset_family_identifier
(string
)
• Code of the linked asset family when the attribute type is `asset_collection`
decimals_allowed
(boolean
)
• Whether decimals are allowed when the attribute type is `number`
min_value
(string
)
• Minimum value allowed when the attribute type is `number`
max_value
(string
)
• Maximum value allowed when the attribute type is `number`
}
]
Example
[
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"max_characters": null,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none",
"validation_regexp": null
},
{
"code": "country",
"labels": {
"en_US": "Country",
"fr_FR": "Pays"
},
"type": "text",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": false
},
{
"code": "creation_year",
"labels": {
"en_US": "Creation year",
"fr_FR": "Année de création"
},
"type": "number",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": false,
"decimals_allowed": false,
"min_value": "1800",
"max_value": "2100"
},
{
"code": "collection_overview",
"labels": {
"en_US": "Collection overview",
"fr_FR": "Aperçu de la collection"
},
"type": "image",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"allowed_extensions": [
"png"
],
"max_file_size": "1000"
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get an attribute of a given reference entity EE only
This endpoint allows you to get the information about a given attribute for a given reference entity.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the reference entity attribute in JSON format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute code
labels
(object )
: {
localeCode
(string
)
• Attribute label for the locale `localeCode`
}
type
(string )
• Attribute type. See type section for more details.
value_per_locale
(boolean )
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean )
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean )
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer )
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean )
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean )
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string )
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string )
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array [string] )
• Extensions allowed when the attribute type is `image`
max_file_size
(string )
• Max file size in MB when the attribute type is `image`
reference_entity_code
(string )
• Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`
asset_family_identifier
(string )
• Code of the linked asset family when the attribute type is `asset_collection`
decimals_allowed
(boolean )
• Whether decimals are allowed when the attribute type is `number`
min_value
(string )
• Minimum value allowed when the attribute type is `number`
max_value
(string )
• Maximum value allowed when the attribute type is `number`
}
Example
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"max_characters": null,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none",
"validation_regexp": null
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an attribute of a given reference entity EE only
This endpoint allows you to update a given attribute for a given renference entity. Note that if the attribute does not already exist for the given reference entity, it creates it.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute labels for each locale
type
(string
)
• Attribute type. See type section for more details.
value_per_locale
(boolean
,
false
by default)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean
,
false
by default)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean
,
false
by default)
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer
)
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean
,
false
by default)
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean
)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string
,
none
by default)
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string
,
null
by default)
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array
[string]
,
[]
by default)
• Extensions allowed when the attribute type is `image`
max_file_size
(string
,
null
by default)
• Max file size in MB when the attribute type is `image`
reference_entity_code
(string
,
null
by default)
• Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`
asset_family_identifier
(string
,
null
by default)
• Code of the linked asset family when the attribute type is `asset_collection`
decimals_allowed
(boolean
,
false
by default)
• Whether decimals are allowed when the attribute type is `number`
min_value
(string
,
null
by default)
• Minimum value allowed when the attribute type is `number`
max_value
(string
,
null
by default)
• Maximum value allowed when the attribute type is `number`
}
Example
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"max_characters": null,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none",
"validation_regexp": null
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Reference entity attribute option
Get a list of attribute options of a given attribute for a given reference entity EE only
This endpoint allows you to get a list of attribute options for a given reference entity.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the options of the given attributes of the given reference entity
Body Format application/json
[
{
code
(string
)
• Attribute's option code
labels
(object
)
• Attribute labels for each locale
}
]
Example
[
{
"code": "woodland_retreat",
"labels": {
"en_US": "Woodland Retreat",
"fr_FR": "Retraite dans les Bois"
}
},
{
"code": "new_nordic",
"labels": {
"en_US": "New Nordic",
"fr_FR": "Renouveau Scandinave"
}
},
{
"code": "global_nomad",
"labels": {
"en_US": "Global Nomad",
"fr_FR": "Nomade du Monde"
}
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get an attribute option for a given attribute of a given reference entity EE only
This endpoint allows you to get the information about a given attribute option.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}
Path parameters
reference_entity_code
(string)
• Code of the reference entity
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the reference entity attribute option in JSON format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute's option code
labels
(object )
: {
localeCode
(string
)
• Attribute label for the locale `localeCode`
}
}
Example
{
"code": "global_nomad",
"labels": {
"en_US": "Global Nomad",
"fr_FR": "Nomade du Monde"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a reference entity attribute option EE only
This endpoint allows you to update a given option for a given attribute and a given reference entity. Learn more about Update behavior. Note that if the option does not already exist for the given attribute of the given reference entity, it creates it.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}
Path parameters
reference_entity_code
(string)
• Code of the reference entity
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Reference entity record
Get the list of the records of a reference entity EE only
This endpoint allows you to get a list of records of a given reference entity. Records are paginated and can be filtered.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/records
Query parameters
search
(string )
• Filter records of the reference entity, for more details see the Filters section
channel
(string )
• Filter attribute values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter attribute values by channel section
locales
(string )
• Filter attribute values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter attribute values by locale section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the records of the given reference entity paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Code of the record
values (object)
• Record attributes values, see Reference entity record values section for more details
created (string)
• Date of creation.
updated (string)
• Date of the last update.
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records?search_after=2x088w%3D%3D"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/kartell"
}
},
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"data": "The contemporary Italian furniture brand",
"locale": "en_US",
"channel": null
},
{
"data": "L'éditeur de meubles comtemporain italien",
"locale": "fr_FR",
"channel": null
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:60+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/usm"
}
},
"code": "usm",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "USM"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "9/c/g/1/0cb0c0e115dedba76f8d1ad8343ec897abc43bv4_image.jpg"
}
],
"description": [
{
"data": "Modular furniture from Switzerland for your home and office",
"locale": "en_US",
"channel": null
},
{
"data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises",
"locale": "fr_FR",
"channel": null
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "switzerland"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:60+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/ligneroset"
}
},
"code": "ligneroset",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Ligne Roset"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "4/b/0/1/0cb0c0e115dedde78b8d1ad8343ec980cd5daa54_image.jpg"
}
],
"description": [
{
"data": "Very well known French brand of modern and luxury furniture",
"locale": "en_US",
"channel": null
},
{
"data": "La marque renommée des meubles de luxe à la française",
"locale": "fr_FR",
"channel": null
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "france"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:60+00:00"
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create several reference entity records EE only
This endpoint allows you to update and/or create several records of one given reference entity at once. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/records
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
[
code
(string
)
• Code of the record
values
(object
)
• Record attributes values, see Reference entity record values section for more details
created
(string
,
null
by default)
• Date of creation.
updated
(string
,
null
by default)
• Date of the last update.
]
}
Example
[
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
}
},
{
"code": "ligneroset",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Ligne Roset"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "4/b/0/1/0cb0c0e115dedde78b8d1ad8343ec980cd5daa54_image.jpg"
}
],
"description": [
{
"data": "Very well known French brand of modern and luxury furniture",
"locale": "en_US",
"channel": null
},
{
"data": "La marque renommée des meubles de luxe à la française",
"locale": "fr_FR",
"channel": null
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "france"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1860"
}
]
}
},
{
"code": "usm",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "USM"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "9/c/g/1/0cb0c0e115dedba76f8d1ad8343ec897abc43bv4_image.jpg"
}
],
"description": [
{
"data": "Modular furniture from Switzerland for your home and office",
"locale": "en_US",
"channel": null
},
{
"data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises",
"locale": "fr_FR",
"channel": null
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "switzerland"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1885"
}
]
}
}
]RESPONSES
OK
Returns an JSON array in which each object gives you the status of each record creation or update
Body Format application/json
[
{
code
(string
)
• Resource code
status_code
(integer
)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string
)
• Message explaining the error
}
]
Example
[
{
"code": "kartell",
"status_code": 204
},
{
"code": "ligneroset",
"status_code": 422,
"message": "Property 'group' does not exist."
},
{
"code": "usm",
"status_code": 201
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get a record of a given reference entity EE only
This endpoint allows you to get the information about a given record for a given reference entity.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the product in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Code of the record
values
(object )
• Record attributes values, see Reference entity record values section for more details
created
(string )
• Date of creation.
updated
(string )
• Date of the last update.
}
Example
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:60+00:00"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create a record of a given reference entity EE only
This endpoint allows you to update a given record of a given renference entity. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Code of the record
values
(object
)
• Record attributes values, see Reference entity record values section for more details
created
(string
,
null
by default)
• Date of creation.
updated
(string
,
null
by default)
• Date of the last update.
}
Example
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
}
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Reference entity media file
Create a new media file for a reference entity or a record EE only
This endpoint allows you to create a new media file and associate it to the image of a reference entity, or to the main image or to an attribute value of a record.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/reference-entities-media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'multipart/form-data', no other value allowed
Body
RESPONSES
Created
Means that the media file creation was successful
Headers
Location • URI of the created resource
Reference-entities-media-file-code • Code of the media file
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `multipart/form-data`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘multipart/form-data’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Download the media file associated to a reference entity or a record EE only
This endpoint allows you to download a given media file that is associated with a reference entity or a record.
Available in PIM versions: 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/reference-entities-media-files/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
OK
Returns the binary of the media file
Body Format Mime-type of the media file
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Asset Manager
Asset family
Get list of asset families EE only
This endpoint allows you to get a list of asset families. Asset families are paginated.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families
Path parameters
Ø
Query parameters
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return asset families paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Asset family code
labels (object)
: {
localeCode (string)
• Asset family label for the locale `localeCode`
}
attribute_as_main_media (string)
• Attribute code that is used as the main media of the asset family.
naming_convention (object)
: {
source (object)
• The string on which the naming convention should be applied. More details here.
pattern (string)
• The regular expression that should be applied on the source. More details here.
abort_asset_creation_on_error (boolean)
• Whether the asset should be created if the naming convention failed to apply. More details here.
}
product_link_rules (array [object ])
• The rules that will be run after the asset creation, in order to automatically link the assets of this family to a set of products. To understand the format of this property, see here.
transformations (array [object ])
• The transformations to perform on source files in order to generate new files into your asset attributes (only available since v4.0). To understand the format of this property, see here.
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families?search_after=2x055w%3D%3D"
}
},
"_embedded": {
"_items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/packshots"
}
},
"code": "packshots",
"labels": {
"en_US": "Packshots",
"fr_FR": "Plans produit"
},
"“naming_convention”": {
"source": {
"property": "code",
"channel": null,
"locale": null
},
"pattern": "/(?P<product_ref>.*)\\.jpg/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "=",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "{{my_product_attribute}}",
"mode": "add"
}
]
}
],
"transformations": [
{
"label": "My transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"locale": null,
"channel": null
},
"target": {
"attribute": "thumbnail",
"locale": null,
"channel": null
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/videos"
}
},
"code": "videos",
"labels": {
"en_US": "Videos",
"fr_FR": "Vidéos"
},
"product_link_rules": [
{
"product_selections": [
{
"field": "categories",
"operator": "IN",
"value": [
"{{category}}"
]
}
],
"assign_assets_to": [
{
"attribute": "presentation_video",
"locale": "{{locale}}",
"mode": "replace"
}
]
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/user_guides"
}
},
"code": "user_guides",
"labels": {
"en_US": "User guides",
"fr_FR": "Guides utilisateur"
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "=",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "user_instructions",
"locale": "{{locale}}",
"mode": "replace"
}
]
}
]
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get an asset family EE only
This endpoint allows you to get the information about a given asset family.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the asset family in JSON format.
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Asset family code
labels
(object )
: {
localeCode
(string
)
• Asset family label for the locale `localeCode`
}
attribute_as_main_media
(string )
• Attribute code that is used as the main media of the asset family.
naming_convention
(object )
: {
source
(object
)
• The string on which the naming convention should be applied. More details here.
pattern
(string
)
• The regular expression that should be applied on the source. More details here.
abort_asset_creation_on_error
(boolean
)
• Whether the asset should be created if the naming convention failed to apply. More details here.
}
product_link_rules
(array [object] )
: [
{
product_selections
(array)
• The product selection to which the assets of the asset family to be automatically linked. More details here.
assign_assets_to
(array)
• The product value in which your assets will be assigned. More details here.
}
]
transformations
(array [object] )
: [
{
label
(string)
• The name of the transformation
filename_suffix
(string)
• The suffix that will be appended to the source filename to generate the target filename. More details here.
filename_prefix
(string)
• The prefix that will be prepended to the source filename to generate the target filename. More details here.
source
(object)
• The attribute value in which is stored the media file you want to use as the source file for your transformation. More details here.
target
(object)
• The attribute value in which the PIM will generate the new transformed file, aka the target file. More details here.
operations
(object)
• The transformations that should be applied to your source file to generate the target file. More details here.
}
]
}
Example
{
"code": "model_pictures",
"labels": {
"en_US": "Model pictures",
"fr_FR": "Photographies en pied"
},
"attribute_as_main_media": "main_image",
"naming_convention": {
"source": {
"property": "code",
"channel": null,
"locale": null
},
"pattern": "/(?P<product_ref>.*)-.*/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "EQUALS",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "model_pictures",
"mode": "replace"
}
]
}
],
"transformations": [
{
"label": "Thumbnail plus black and white transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"channel": null,
"locale": null
},
"target": {
"attribute": "thumbnail",
"channel": null,
"locale": null
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
]
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an asset family EE only
This endpoint allows you to update a given asset family. Note that if the asset family does not already exist, it creates it.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/asset-families/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Asset family code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Asset family labels for each locale
attribute_as_main_media
(string
,
First media file or media link attribute that was created
by default)
• Attribute code that is used as the main media of the asset family.
naming_convention
(object
{
source : object
,
pattern : string
,
abort_asset_creation_on_error : boolean
}
,
[]
by default)
• The naming convention ran over the asset code or the main media filename upon each asset creation, in order to automatically set several values in asset attributes. To learn more and see the format of this property, take a look at here.
product_link_rules
(array
[object]
,
[]
by default)
: [
{
product_selections
(array
[object
])
• The product selection to which the assets of the asset family to be automatically linked. More details here.
assign_assets_to
(array
[object
])
• The product value in which your assets will be assigned. More details here.
}
]
transformations
(array
[object]
,
[]
by default)
: [
{
label
(string
)
• The name of the transformation
filename_suffix
(string
)
• The suffix that will be appended to the source filename to generate the target filename. More details here.
filename_prefix
(string
)
• The prefix that will be prepended to the source filename to generate the target filename. More details here.
source
(object
)
• The attribute value in which is stored the media file you want to use as the source file for your transformation. More details here.
target
(object
)
• The attribute value in which the PIM will generate the new transformed file, aka the target file. More details here.
operations
(object
)
• The transformations that should be applied to your source file to generate the target file. More details here.
}
]
}
Example
{
"code": "model_pictures",
"labels": {
"en_US": "Model pictures",
"fr_FR": "Photographies en pied"
},
"attribute_as_main_media": "main_image",
"naming_convention": {
"source": {
"property": "code",
"channel": null,
"locale": null
},
"pattern": "/(?P<product_ref>.*)-.*/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "EQUALS",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "model_pictures",
"mode": "replace"
}
]
}
],
"transformations": [
{
"label": "Thumbnail plus black and white transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"channel": null,
"locale": null
},
"target": {
"attribute": "thumbnail",
"channel": null,
"locale": null
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
],
"sharing_enabled": true
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Asset attribute
Get the list of attributes of a given asset family EE only
This endpoint allows you to get the list of attributes of a given asset family.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the attributes of the given asset family
Body Format application/json
[
{
code
(string
)
• Attribute code
labels
(object
)
• Attribute labels for each locale
type
(string
)
• Attribute type. See type section for more details.
value_per_locale
(boolean
)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean
)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean
)
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean
)
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer
)
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean
)
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean
)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string
)
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string
)
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array
[string]
)
• Extensions allowed when the attribute type is `media_file`
max_file_size
(string
)
• Max file size in MB when the attribute type is `media_file`
decimals_allowed
(boolean
)
• Whether decimals are allowed when the attribute type is `number`
min_value
(string
)
• Minimum value allowed when the attribute type is `number`
max_value
(string
)
• Maximum value allowed when the attribute type is `number`
media_type
(string
)
• For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file.
prefix
(string
)
• Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media
suffix
(string
)
• Suffix of the `media_link` attribute type. The common url suffix for the media
}
]
Example
[
{
"code": "model_is_wearing_size",
"labels": {
"en_US": "Model is wearing size",
"fr_FR": "Le mannequin porte la taille"
},
"type": "single_option",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": true
},
{
"code": "media_link",
"labels": {
"en_US": "Media link",
"fr_FR": "Lien vers le média"
},
"type": "media_link",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": true,
"prefix": "https://my-dam.com/",
"suffix": "?height=630&width=485",
"media_type": "image"
},
{
"code": "warning_mention",
"labels": {
"en_US": "Warning mention",
"fr_FR": "Phrase d'avertissement"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": false,
"max_characters": "50",
"is_textarea": false,
"is_rich_text_editor": false,
"validation_rule": "none",
"validation_regexp": null
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get an attribute of a given asset family EE only
This endpoint allows you to get the information about a given attribute for a given asset family.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the asset attribute in JSON format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute code
labels
(object )
: {
localeCode
(string
)
• Attribute label for the locale `localeCode`
}
type
(string )
• Attribute type. See type section for more details.
value_per_locale
(boolean )
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean )
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean )
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean )
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer )
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean )
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean )
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string )
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string )
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array [string] )
• Extensions allowed when the attribute type is `media_file`
max_file_size
(string )
• Max file size in MB when the attribute type is `media_file`
decimals_allowed
(boolean )
• Whether decimals are allowed when the attribute type is `number`
min_value
(string )
• Minimum value allowed when the attribute type is `number`
max_value
(string )
• Maximum value allowed when the attribute type is `number`
media_type
(string )
• For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file.
prefix
(string )
• Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media
suffix
(string )
• Suffix of the `media_link` attribute type. The common url suffix for the media
}
Example
{
"code": "model_is_wearing_size",
"labels": {
"en_US": "Model is wearing size",
"fr_FR": "Le mannequin porte la taille"
},
"type": "single_option",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": true
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an attribute of a given asset family EE only
This endpoint allows you to update a given attribute for a given asset family. Note that if the attribute does not already exist for the given asset family, it creates it.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/attributes/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Attribute code
labels
(object
{
localeCode : string
}
,
[]
by default)
• Attribute labels for each locale
type
(string
)
• Attribute type. See type section for more details.
value_per_locale
(boolean
,
false
by default)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean
,
false
by default)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean
,
false
by default)
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean
,
false
by default)
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer
)
• Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
is_textarea
(boolean
,
false
by default)
• Whether the UI should display a text area instead of a simple field when the attribute type is `text`
is_rich_text_editor
(boolean
)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
validation_rule
(string
,
none
by default)
• Validation rule type used to validate the attribute value when the attribute type is `text`
validation_regexp
(string
,
null
by default)
• Regexp expression used to validate the attribute value when the attribute type is `text`
allowed_extensions
(array
[string]
,
[]
by default)
• Extensions allowed when the attribute type is `media_file`
max_file_size
(string
,
null
by default)
• Max file size in MB when the attribute type is `media_file`
decimals_allowed
(boolean
,
false
by default)
• Whether decimals are allowed when the attribute type is `number`
min_value
(string
,
null
by default)
• Minimum value allowed when the attribute type is `number`
max_value
(string
,
null
by default)
• Maximum value allowed when the attribute type is `number`
media_type
(string
)
• For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file.
prefix
(string
,
null
by default)
• Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media
suffix
(string
,
null
by default)
• Suffix of the `media_link` attribute type. The common url suffix for the media
}
Example
{
"code": "model_is_wearing_size",
"labels": {
"en_US": "Model is wearing size",
"fr_FR": "Le mannequin porte la taille"
},
"type": "single_option",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": true
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Asset attribute option
Get a list of attribute options of a given attribute for a given asset family EE only
This endpoint allows you to get a list of attribute options for a given asset family.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the options of the given attribute of the given asset family
Body Format application/json
[
{
code
(string
)
• Attribute's option code
labels
(object
)
• Attribute labels for each locale
}
]
Example
[
{
"code": "unique_size",
"labels": {
"en_US": "Unique size",
"fr_FR": "Taille unique"
}
},
{
"code": "size_27",
"labels": {
"en_US": "Size 27",
"fr_FR": "Taille 36"
}
},
{
"code": "small",
"labels": {
"en_US": "S",
"fr_FR": "S"
}
}
]Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Get an attribute option for a given attribute of a given asset family EE only
This endpoint allows you to get the information about a given asset attribute option.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options/{code}
Path parameters
asset_family_code
(string)
• Code of the asset family
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the asset attribute option in JSON format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Attribute's option code
labels
(object )
: {
localeCode
(string
)
• Attribute label for the locale `localeCode`
}
}
Example
{
"code": "small",
"labels": {
"en_US": "S",
"fr_FR": "S"
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an asset attribute option for a given asset family EE only
This endpoint allows you to update a given option for a given attribute and a given asset family. Learn more about the Update behavior. Note that if the option does not already exist for the given attribute of the given asset family, it creates it.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options/{code}
Path parameters
asset_family_code
(string)
• Code of the asset family
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Asset media file
Create a new media file for an asset EE only
This endpoint allows you to create a new media file and associate it to a media file attribute value of an asset.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/rest/v1/asset-media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'multipart/form-data', no other value allowed
Body
RESPONSES
Created
Means that the media file creation was successful
Headers
Location • URI of the created resource
Asset-media-file-code • Code of the media file
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `multipart/form-data`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘multipart/form-data’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Download the media file associated to an asset EE only
This endpoint allows you to download a given media file that is associated with an asset.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-media-files/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
OK
Returns the binary of the media file
Body Format Mime-type of the media file
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Asset
Get the list of the assets of a given asset family EE only
This endpoint allows you to get a list of assets of a given asset family. Assets are paginated. This endpoint is case sensitive on the asset family code.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/assets
Query parameters
search
(string )
• Filter assets, for more details see the Asset filters section
channel
(string )
• Filter asset values to return scopable asset attributes for the given channel as well as the non localizable/non scopable asset attributes, for more details see the Filter asset values by channel section
locales
(string )
• Filter asset values to return localizable attributes for the given locales as well as the non localizable/non scopable asset attributes, for more details see the Filter asset values by locale section
search_after
(string ,
cursor to the first page
by default )
• Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the assets of the given asset family paginated
Body Format application/json
Follow the standard format of the entity
{
_links
(object)
: {
self (object )
: {
href (string ) • URI of the current page of resources
}
first (object )
: {
href (string ) • URI of the first page of resources
}
next (object )
: {
href (string ) • URI of the next page of resources
}
}
_embedded
(object)
: {
_items (array )
: [
{
_links (object)
: {
self (object)
: {
href
(string ) • URI of the resource
}
}
code (string)
• Code of the asset
values (object)
: {
attributeCode (array [object ])
•
: [
{
channel
(string ) • Channel code of the asset attribute value
locale
(string ) • Locale code of the asset attribute value
data
(object ) • Asset attribute value. See the `data` format section for more details.
_links
(object ) • Related links for the `media file` attribute values. See the `_links` format section for more details.
}
]
}
created (string)
• Date of creation
updated (string)
• Date of the last update
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets?search_after=2x088w%3D%3D"
}
},
"_embedded": {
"_items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/allie_jean_model_picture"
}
},
"code": "allie_jean_model_picture",
"values": {
"media_file": [
{
"locale": null,
"channel": null,
"data": "0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png",
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png"
},
"share_link": {
"href": "https://demo.asset.akeneo.com/model_pictures/allie_jean_model_picture.png"
}
}
}
],
"media_link": [
{
"locale": null,
"channel": null,
"data": "allie_jean_model_picture.png",
"linked_data": {
"full_url": "https://example.com/allie_jean_model_picture.png",
"prefix": "https://example.com/",
"suffix": null
}
}
],
"model_is_wearing_size": [
{
"locale": null,
"channel": null,
"data": "size_27"
}
],
"warning_mention": [
{
"data": "Photo not retouched",
"locale": "en_US",
"channel": null
},
{
"data": "Photo non retouchée",
"locale": "fr_FR",
"channel": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/amy_socks_model_picture"
}
},
"code": "amy_socks_model_picture",
"values": {
"media_file": [
{
"locale": null,
"channel": null,
"data": "0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_amy_socks_model_picture.png",
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_amy_socks_model_picture.png"
},
"share_link": {
"href": "https://demo.asset.akeneo.com/model_pictures/amy_socks_model_picture.jpg"
}
}
}
],
"media_link": [
{
"locale": null,
"channel": null,
"data": "amy_socks_model_picture.png",
"linked_data": {
"full_url": "https://example.com/amy_socks_model_picture.png",
"prefix": "https://example.com/",
"suffix": null
}
}
],
"model_is_wearing_size": [
{
"locale": null,
"channel": null,
"data": "unique_size"
}
],
"warning_mention": [
{
"data": "Photo not retouched",
"locale": "en_US",
"channel": null
},
{
"data": "Photo non retouchée",
"locale": "fr_FR",
"channel": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/alice_blouse_model_picture"
}
},
"code": "alice_blouse_model_picture",
"values": {
"media_file": [
{
"locale": null,
"channel": null,
"data": "0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_alice_blouse_model_picture.png",
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_alice_blouse_model_picture.png"
},
"share_link": {
"href": "https://demo.asset.akeneo.com/model_pictures/alice_blouse_model_picture.png"
}
}
}
],
"media_link": [
{
"locale": null,
"channel": null,
"data": "alice_blouse_model_picture.png",
"linked_data": {
"full_url": "https://example.com/alice_blouse_model_picture.png",
"prefix": "https://example.com/",
"suffix": null
}
}
],
"model_is_wearing_size": [
{
"locale": null,
"channel": null,
"data": "small"
}
],
"warning_mention": [
{
"data": "Photo retouched",
"locale": "en_US",
"channel": null
},
{
"data": "Photo non retouchée",
"locale": "fr_FR",
"channel": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}
]
}
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create several assets EE only
This endpoint allows you to update and/or create several assets of one given asset family at once. Learn more about the Update behavior. Note that if the asset does not already exist for the given asset family, it creates it. This endpoint is case sensitive on the asset family code.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/assets
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
[
code
(string
)
• Code of the asset
values
(object
{
attributeCode : array
[
object
{
channel : string
,
locale : string
,
data : object
,
_links : object
}
]
}
)
• Asset attributes values, see the Focus on the asset values section for more details.
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
]
}
Example
[
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture1.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"red",
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"code": "sku_54628_picture2",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture2.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"blue",
"white"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"code": "sku_54628_picture3",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture3.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}
]RESPONSES
OK
Returns an JSON array in which each object gives you the status of each asset creation or update
Body Format application/json
[
{
code
(string
)
• Resource code
status_code
(integer
)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string
)
• Message explaining the error
}
]
Example
[
{
"code": "sku_54628_picture1",
"status_code": 204
},
{
"code": "sku_54628_picture2",
"status_code": 422,
"message": "Property 'group' does not exist."
},
{
"code": "sku_54628_picture3",
"status_code": 201
}
]Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Request Entity Too Large
There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}Unsupported Media type
The `Content-type` header has to be `application/vnd.akeneo.collection+json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}Get an asset of a given asset family EE only
This endpoint allows you to get the information about a given asset for a given asset family. This endpoint is case sensitive on the asset family code.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
OK
Returns the content of the asset in JSON standard format
Body Format application/json
Follow the standard format of the entity
{
code
(string )
• Code of the asset
values
(object )
: {
attributeCode
(array
[object]
)
: [
{
channel
(string
)
• Channel code of the asset attribute value
locale
(string
)
• Locale code of the asset attribute value
data
(object
)
• Asset attribute value. See the `data` format section for more details.
_links
(object
)
• Related links for the `media file` attribute values. See the `_links` format section for more details.
}
]
}
created
(string )
• Date of creation
updated
(string )
• Date of the last update
}
Example
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture1.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"red",
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Update/create an asset EE only
This endpoint allows you to update a given asset of a given asset family. Learn more about the Update behavior. Note that if the asset does not already exist for the given asset family, it creates it. This endpoint is case sensitive on the asset family code.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string
)
• Code of the asset
values
(object
{
attributeCode : array
[
object
{
channel : string
,
locale : string
,
data : object
,
_links : object
}
]
}
)
• Asset attributes values, see the Focus on the asset values section for more details.
created
(string
)
• Date of creation
updated
(string
)
• Date of the last update
}
Example
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture1.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"red",
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}RESPONSES
Created
Means that the creation was successful
Headers
Location • URI of the created resource
Body Format application/json
Ø
No content to return
Means that the update was successful
Headers
Location • URI of the updated resource
Body Format application/json
Ø
Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete an asset EE only
This endpoint allows you to delete a given asset. This endpoint is case sensitive on the asset family code.
Available in PIM versions: 3.2 4.0 5.0 6.0 7.0 SaaS
REQUEST
delete /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return
Means that the deletion was successful
Body Format application/json
Ø
Authentication required
Can be caused by a missing or expired token
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}Resource not found
The resource code given in the URI does not correspond to any existing PIM resource
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Utilities
Overview
Get list of all endpoints
This endpoint allows you to get the list of all the available endpoints. No need to be authenticated to use this endpoint.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
get /api/rest/v1
Path parameters
Ø
Query parameters
Ø
Headers
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the list of all available endpoints
Body Format application/json
{
host
(string )
• Host name
authentication
(object )
• Endpoint to get the authentication token
routes
(object )
• All the availables endpoints
}
Example
{
"host": "https://demo.akeneo.com",
"authentication": {
"fos_oauth_server_token": {
"route": "/api/oauth/v1/token",
"methods": [
"POST"
]
}
},
"routes": {
"pim_api_category_list": {
"route": "/api/rest/v1/categories",
"methods": [
"GET"
]
},
"pim_api_category_get": {
"route": "/api/rest/v1/categories/{code}",
"methods": [
"GET"
]
},
"pim_api_category_create": {
"route": "/api/rest/v1/categories",
"methods": [
"POST"
]
},
"pim_api_category_partial_update": {
"route": "/api/rest/v1/categories/{code}",
"methods": [
"PATCH"
]
}
}
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}Authentication
Get authentication token
This endpoint allows you to get an authentication token. No need to be authenticated to use this endpoint.
Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS
REQUEST
post /api/oauth/v1/token
Path parameters
Ø
Query parameters
Ø
Headers
Content-type
• Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed
Authorization
• Equal to 'Basic xx', where 'xx' is the base 64 encoding of the client id and secret. Find out how to generate them in the Client ID/secret generation section.
Body
RESPONSES
Return an authentication token
Body Format application/json
{
access_token
(string )
• Authentication token that should be given in every authenticated request to the API
expires_in
(integer )
• Validity of the token given in seconds, 3600s = 1h by default
token_type
(string )
• Token type, always equal to "bearer"
scope
(string )
• Unused, always equal to "null"
refresh_token
(string )
• Use this token when your access token has expired. See Refresh an expired token section for more details.
}
Example
{
"access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
"expires_in": 3600,
"token_type": "bearer",
"scope": null,
"refresh_token": "M2FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
}Bad request
Can be caused by a malformed JSON request
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}Unsupported Media type
The `Content-type` header has to be `application/json`
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}Unprocessable entity
The validation of the entity given in the body of the request failed
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}System
Get system information
This endpoint allows you to get the version and the edition of the PIM. Example of what you can get
| Environment | Edition | Version |
|---|---|---|
| SaaS EE | Serenity | v20230112013744 |
| SaaS CE | GE | v20210526040645 |
| PaaS or onPrem EE | EE | 6.0.28 |
| PaaS or onPrem CE | CE | 6.0.28 |
Available in PIM versions: 6.0 7.0 SaaS
REQUEST
get /api/rest/v1/system-information
Path parameters
Ø
Query parameters
Ø
Headers
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the version and the edition of the PIM.
Body Format application/json
{
version
(string )
• Version of the PIM
edition
(string )
• Edition of the PIM
}
Example
{
"version": "20210521041041",
"edition": "Serenity"
}Not Acceptable
The `Accept` header is not `application/json` but it should
Body Format application/json
{
code
(integer )
• HTTP status code
message
(string )
• Message explaining the error
}
Example
{
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}