REST API reference

Complete reference on how to handle Akeneo PIM resources

Products

Product [identifier]

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 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. (Only available since the 5.0 version)

with_quality_scores (boolean ) • Return product quality scores in the response. (Only available since the 5.0 version)

with_completenesses (boolean ) • Return product completenesses in the response. (Only available on SaaS platforms)

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) : {
              attributeCode (array [object ]) • : [
                  {
                    scope (string )Channel code of the product value
                    locale (string )Locale code of the product value
                    data (object ) • Product value. See the `data` format section for more details.
                    linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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 on SaaS platforms, 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_completenesses=true&with_attribute_options=true"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/top"
              }
            },
            "uuid": "aaf518b2-f91e-40f1-a53a-78ce5e81a6f9",
            "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"
              }
            ],
            "completenesses": [
              {
                "scope": "ecommerce",
                "locale": "en_US",
                "data": 20
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": 30
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": 55
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": 70
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/cap"
              }
            },
            "uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
            "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"
              }
            ],
            "completenesses": [
              {
                "scope": "ecommerce",
                "locale": "en_US",
                "data": 20
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": 30
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": 55
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": 70
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
              }
            },
            "uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
            "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": {},
            "completenesses": []
          }
        ]
      }
    }

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 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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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
          },
          {
            "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": [
            "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 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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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 SaaS


REQUEST

get /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

Query parameters

with_attribute_options (boolean ) • Return labels of attribute options in the response. (Only available since the 5.0 version)

with_quality_scores (boolean ) • Return product quality scores in the response. (Only available since the 5.0 version)

with_completenesses (boolean ) • Return product completenesses in the response. (Only available on SaaS platforms)

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 ) : {
    attributeCode (array [object] ) : [
        {
            scope (string ) Channel code of the product value
            locale (string ) Locale code of the product value
            data (object ) • Product value. See the `data` format section for more details.
            linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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
          },
          {
            "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": [
            "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 SaaS


REQUEST

patch /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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
          },
          {
            "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": [
            "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 SaaS


REQUEST

delete /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

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

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 SaaS


REQUEST

post /api/rest/v1/products/{code}/proposal

Path parameters

code (string) • Code of the resource

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

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 SaaS


REQUEST

get /api/rest/v1/products/{code}/draft

Path parameters

code (string) • Code of the resource

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 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 ) : {
    attributeCode (array [object] ) : [
        {
            scope (string ) Channel code of the product value
            locale (string ) Locale code of the product value
            data (object ) • Product value. See the `data` format section for more details.
            linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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
          },
          {
            "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": [
            "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 [uuid]

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: 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. (Only available since the 5.0 version)

with_quality_scores (boolean ) • Return product quality scores in the response. (Only available since the 5.0 version)

with_completenesses (boolean ) • Return product completenesses in the response. (Only available on SaaS platforms)

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) : {
              attributeCode (array [object ]) • : [
                  {
                    scope (string )Channel code of the product value
                    locale (string )Locale code of the product value
                    data (object ) • Product value. See the `data` format section for more details.
                    linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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 on SaaS platforms, and when the "with_completenesses" query parameter is set to "true")
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product-uuid/25566245-55c3-42ce-86d9-8610ac459fa8"
              }
            },
            "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
            "family": "tshirt",
            "groups": [],
            "parent": null,
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "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
                  }
                ]
              }
            },
            "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": 20
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": 30
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": 55
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": 70
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/fc24e6c3-933c-4a93-8a81-e5c703d134d5"
              }
            },
            "uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
            "family": "caps",
            "groups": [],
            "parent": null,
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "sku": [
                {
                  "data": "cap",
                  "locale": null,
                  "scope": null
                }
              ],
              "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": [
                  "d055527c-0698-4967-8f16-8a5f23f4e5cf"
                ],
                "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"
              }
            ],
            "completenesses": [
              {
                "scope": "ecommerce",
                "locale": "en_US",
                "data": 20
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": 30
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": 55
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": 70
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product-uuid/fa0b115e-46ec-4527-beab-7207452f1b47"
              }
            },
            "uuid": "fa0b115e-46ec-4527-beab-7207452f1b47",
            "family": null,
            "groups": [],
            "parent": null,
            "categories": [
              "winter_collection"
            ],
            "enabled": true,
            "values": {
              "sku": [
                {
                  "data": "sweat",
                  "locale": null,
                  "scope": null
                }
              ]
            },
            "created": "2016-06-23T11:24:44+02:00",
            "updated": "2016-06-23T11:24:44+02:00",
            "associations": {},
            "quantified_associations": {},
            "quality_scores": {},
            "completenesses": []
          }
        ]
      }
    }

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: 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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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
            }
          ]
        }
      }
    }

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: 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

{

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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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: SaaS


REQUEST

get /api/rest/v1/products-uuid/{uuid}

Path parameters

uuid (string) • Uuid of the resource

Query parameters

with_attribute_options (boolean ) • Return labels of attribute options in the response. (Only available since the 5.0 version)

with_quality_scores (boolean ) • Return product quality scores in the response. (Only available since the 5.0 version)

with_completenesses (boolean ) • Return product completenesses in the response. (Only available on SaaS platforms)

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 ) : {
    attributeCode (array [object] ) : [
        {
            scope (string ) Channel code of the product value
            locale (string ) Locale code of the product value
            data (object ) • Product value. See the `data` format section for more details.
            linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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
            }
          ]
        }
      },
      "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: SaaS


REQUEST

patch /api/rest/v1/products-uuid/{uuid}

Path parameters

uuid (string) • Uuid of the resource

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 { attributeCode : array [ object { scope : string , locale : string , data : object , linked_data : 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
            }
          ]
        }
      },
      "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: SaaS


REQUEST

delete /api/rest/v1/products-uuid/{uuid}

Path parameters

uuid (string) • Uuid of the resource

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

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: SaaS


REQUEST

post /api/rest/v1/products-uuid/{uuid}/proposal

Path parameters

uuid (string) • Uuid of the resource

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

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: SaaS


REQUEST

get /api/rest/v1/products-uuid/{uuid}/draft

Path parameters

uuid (string) • Uuid of the resource

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 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 ) : {
    attributeCode (array [object] ) : [
        {
            scope (string ) Channel code of the product value
            locale (string ) Locale code of the product value
            data (object ) • Product value. See the `data` format section for more details.
            linked_data (object ) • Object containing labels of attribute options (only available since the 5.0 and when query parameter "with_attribute_options" is set to "true"). See the `linked_data` format 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
            }
          ]
        }
      },
      "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 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

with_quality_scores (boolean ) • Return product model quality scores in the response. (Only available on SaaS platforms)

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) : {
              attributeCode (array [object ]) • : [
                  {
                    scope (string )Channel code of the product value
                    locale (string )Locale code of the product value
                    data (object )Product value
                   }
              ]
          }
          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 on SaaS platforms 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 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 { attributeCode : array [ object { scope : string , locale : string , data : 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 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 { attributeCode : array [ object { scope : string , locale : string , data : 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 on SaaS platforms 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 SaaS


REQUEST

get /api/rest/v1/product-models/{code}

Path parameters

code (string) • Code of the resource

Query parameters

with_quality_scores (boolean ) • Return product model quality scores in the response. (Only available on SaaS platforms)

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 ) : {
    attributeCode (array [object] ) : [
        {
            scope (string ) Channel code of the product value
            locale (string ) Locale code of the product value
            data (object ) Product value
        }
    ]
  }

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 on SaaS platforms 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 SaaS


REQUEST

patch /api/rest/v1/product-models/{code}

Path parameters

code (string) • Code of the resource

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