REST API reference

Complete reference on how to handle Akeneo PIM resources

Products

Product [uuid]

This API provides two endpoints for interacting with products:

Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.

Get list of products

This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, permissions based on your user groups are applied to the set of products you request.

Available in PIM versions: 7.0 SaaS

REQUEST

get /api/rest/v1/products-uuid

Path parameters

Query parameters

search (string ) • Filter products, for more details see the Filters section

scope (string ) • Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes, for more details see the Filter product values via channel section

locales (string ) • Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes, for more details see the Filter product values via locale section

attributes (string ) • Filter product values to only return those concerning the given attributes, for more details see the Filter on product values section

pagination_type (string , page by default ) • Pagination method type, see Pagination section

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

search_after (string , cursor to the first page by default ) • Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

with_attribute_options (boolean ) • Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)

with_asset_share_links (boolean ) • Return asset collection share link urls in the response. See the `linked_data` format section for more details. (Only available in the SaaS 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 since the 6.0 version)

with_root_parent (boolean ) • Return the root parent product model code of a variant

Headers

Authorization • Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section

Accept • Equal to 'application/json', no other value allowed

Body

RESPONSES

Return products paginated

Body Format application/json

Follow the standard format of the entity

{

_links (object) : {
self (object ) : {
href (string ) • URI of the current page of resources
}
first (object ) : {
href (string ) • URI of the first page of resources
}
previous (object ) : {
href (string ) • URI of the previous page of resources
}
next (object ) : {
href (string ) • URI of the next page of resources
}
}

current_page (integer) • Current page number

_embedded (object) : {
items (array ) : [
{
_links (object) : {
self (object) : {
href (string ) • URI of the resource
}
}
uuid (string) • Product uuid
enabled (boolean) • Whether the product is enabled
family (string) • Family code from which the product inherits its attributes and attributes requirements.
categories (array [string ]) • Codes of the categories in which the product is classified
groups (array [string ]) • Codes of the groups to which the product belong
parent (string) • Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.
values (object) • Product attributes values, see Product values section for more details
associations (object) : {
associationTypeCode (object) : {
groups (array [string ] ) • Array of groups codes with which the product is in relation
products (array [string ] ) • Array of product uuids with which the product is in relation
product_models (array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}
quantified_associations (object) : {
quantifiedAssociationTypeCode (object) : {
products (array [object ] ) • Array of objects containing product uuids and quantities with which the product is in relation
product_models (array [object ] ) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
root_parent (string) • Code of the root parent product model when the product is a variant (only available for Serenity and when the "with_root_parent" is set to "true")
created (string) • Date of creation
updated (string) • Date of the last update
metadata (object) : {
workflow_status (string) • Status of the product regarding the user permissions
}
quality_scores (object) • Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")
completenesses (array [object ]) • Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the "with_completenesses" query parameter is set to "true")
}
]
}

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-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": "tops",
            "root_parent": "clothes",
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "sku": [
                {
                  "data": "top-xl",
                  "locale": null,
                  "scope": null,
                  "attribute_type": "pim_catalog_identifier"
                }
              ],
              "name": [
                {
                  "data": "Top XL",
                  "locale": "en_US",
                  "scope": null,
                  "attribute_type": "pim_catalog_text"
                },
                {
                  "data": "Débardeur XL",
                  "locale": "fr_FR",
                  "scope": null,
                  "attribute_type": "pim_catalog_text"
                }
              ],
              "description": [
                {
                  "data": "Summer top XL",
                  "locale": "en_US",
                  "scope": "ecommerce",
                  "attribute_type": "pim_catalog_textarea"
                },
                {
                  "data": "Top XL",
                  "locale": "en_US",
                  "scope": "tablet",
                  "attribute_type": "pim_catalog_textarea"
                },
                {
                  "data": "Débardeur XL pour l'été",
                  "locale": "fr_FR",
                  "scope": "ecommerce",
                  "attribute_type": "pim_catalog_textarea"
                },
                {
                  "data": "Débardeur XL",
                  "locale": "fr_FR",
                  "scope": "tablet",
                  "attribute_type": "pim_catalog_textarea"
                }
              ],
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "15.5",
                      "currency": "EUR"
                    },
                    {
                      "amount": "15",
                      "currency": "USD"
                    }
                  ],
                  "attribute_type": "pim_catalog_price_collection"
                }
              ],
              "color": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "black",
                  "linked_data": {
                    "attribute": "color",
                    "code": "black",
                    "labels": {
                      "en_US": "Black",
                      "fr_FR": "Noir"
                    }
                  },
                  "attribute_type": "pim_catalog_simpleselect"
                }
              ],
              "size": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "xl",
                  "linked_data": {
                    "attribute": "size",
                    "code": "xl",
                    "labels": {
                      "en_US": "XL",
                      "fr_FR": "XL"
                    }
                  },
                  "attribute_type": "pim_catalog_simpleselect"
                }
              ],
              "collection": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    "winter_2016"
                  ],
                  "linked_data": {
                    "winter_2016": {
                      "attribute": "collection",
                      "code": "winter_2016",
                      "labels": {
                        "en_US": "Winter 2016",
                        "fr_FR": "Hiver 2016"
                      }
                    }
                  },
                  "attribute_type": "pim_catalog_multiselect"
                }
              ]
            },
            "created": "2016-06-23T18:24:44+02:00",
            "updated": "2016-06-25T17:56:12+02:00",
            "associations": {
              "PACK": {
                "products": [
                  "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: 7.0 SaaS

REQUEST

post /api/rest/v1/products-uuid

Path parameters

Query parameters

Headers

Authorization • Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section

Content-type • Equal to 'application/json', no other value allowed

Body

Follow the standard format of the entity

{

uuid (string ) • Product uuid

enabled (boolean , true by default) • Whether the product is enabled

family (string , null only in the case of a non variant product by default) • Family code from which the product inherits its attributes and attributes requirements.

categories (array [string] , [] by default) • Codes of the categories in which the product is classified

groups (array [string] , [] by default) • Codes of the groups to which the product belong

parent (string , null by default) • Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.

values (object ) • Product attributes values, see Product values section for more details

associations (object { associationTypeCode : object { groups : array [string] , products : array [string] , product_models : array [string] } } ) • Several associations related to groups, product models and/or other products, grouped by association types

quantified_associations (object { quantifiedAssociationTypeCode : object { products : array [object] , product_models : array [object] } } ) • Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)

}

Example

{
      "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
      "enabled": true,
      "family": "tshirt",
      "categories": [
        "summer_collection"
      ],
      "groups": [],
      "parent": null,
      "values": {
        "sku": [
          {
            "data": "top",
            "locale": null,
            "scope": null
          }
        ],
        "name": [
          {
            "data": "Top",
            "locale": "en_US",
            "scope": null
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": null
          }
        ],
        "description": [
          {
            "data": "Summer top",
            "locale": "en_US",
            "scope": "ecommerce"
          },
          {
            "data": "Top",
            "locale": "en_US",
            "scope": "tablet"
          },
          {
            "data": "Débardeur pour l'été",
            "locale": "fr_FR",
            "scope": "ecommerce"
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": "tablet"
          }
        ],
        "price": [
          {
            "locale": null,
            "scope": null,
            "data": [
              {
                "amount": "15.5",
                "currency": "EUR"
              },
              {
                "amount": "15",
                "currency": "USD"
              }
            ]
          }
        ],
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "black",
            "linked_data": {
              "attribute": "color",
              "code": "black",
              "labels": {
                "en_US": "Black",
                "fr_FR": "Noir"
              }
            }
          }
        ],
        "size": [
          {
            "locale": null,
            "scope": null,
            "data": "m",
            "linked_data": {
              "attribute": "size",
              "code": "m",
              "labels": {
                "en_US": "M",
                "fr_FR": "M"
              }
            }
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "winter_2016"
            ],
            "linked_data": {
              "winter_2016": {
                "attribute": "collection",
                "code": "winter_2016",
                "labels": {
                  "en_US": "Winter 2016",
                  "fr_FR": "Hiver 2016"
                }
              }
            }
          }
        ]
      },
      "associations": {
        "PACK": {
          "products": [
            "d055527c-0698-4967-8f16-8a5f23f4e5cf"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
              "quantity": 2
            },
            {
              "uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "identifier": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 400,
      "message": "Invalid JSON message received"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 401,
      "message": "Authentication is required"
    }

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 403,
      "message": "Access forbidden. You are not allowed to list categories."
    }

Unsupported Media type

The `Content-type` header has to be `application/json`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/json’ is allowed."
    }

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 422,
      "message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
      "_links": {
        "documentation": {
          "href": "http://api.akeneo.com/api-reference.html"
        }
      }
    }

Update/create several products

This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Enterprise Edition, permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.

Available in PIM versions: 7.0 SaaS

REQUEST

patch /api/rest/v1/products-uuid

Path parameters

Query parameters

Headers

Authorization • Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section

Content-type • Equal to 'application/vnd.akeneo.collection+json', no other value allowed

Body

Contains several lines, each line is a product in JSON standard format

{

uuid (string ) • Product uuid

enabled (boolean , true by default) • Whether the product is enabled

family (string , null only in the case of a non variant product by default) • Family code from which the product inherits its attributes and attributes requirements.

categories (array [string] , [] by default) • Codes of the categories in which the product is classified

groups (array [string] , [] by default) • Codes of the groups to which the product belong

parent (string , null by default) • Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.

values (object ) • Product attributes values, see Product values section for more details

root_parent (string , null by default) • Code of the root parent product model when the product is a variant (only available for Serenity and when the "with_root_parent" is set to "true")

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

Returns a plain text response whose lines are JSON containing the status of each update or creation

Body Format application/json

{

line (integer ) • Line number

uuid (string ) • Product uuid

status_code (integer ) • HTTP status code, see Client errors to understand the meaning of each code

message (string ) • Message explaining the error

}

Example

{"line":1,"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","status_code":204}
    {"line":2,"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","status_code":422,"message":"Property \"group\" does not exist."}
    {"line":3,"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","status_code":201}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 401,
      "message": "Authentication is required"
    }

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 403,
      "message": "Access forbidden. You are not allowed to list categories."
    }

Request Entity Too Large

There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 413,
      "message": "Too many resources to process, 100 is the maximum allowed."
    }

Unsupported Media type

The `Content-type` header has to be `application/vnd.akeneo.collection+json`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/vnd.akeneo.collection+json’ is allowed."
    }

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 422,
      "message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
      "_links": {
        "documentation": {
          "href": "http://api.akeneo.com/api-reference.html"
        }
      }
    }

Get a product

This endpoint allows you to get the information about a given product. In the Entreprise Edition, permissions based on your user groups are applied to the product you request.

Available in PIM versions: 7.0 SaaS

REQUEST

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

Path parameters

uuid (string) • Uuid of the resource

Query parameters

with_attribute_options (boolean ) • Return labels of attribute options in the response. See the `linked_data` format section for more details. (Only available since the 5.0 version)

with_asset_share_links (boolean ) • Return asset collection share link urls in the response. See the `linked_data` format section for more details. (Only available in the SaaS 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 since the 6.0 version)

with_root_parent (boolean ) • Return the root parent product model code of a variant

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

Returns the content of the product in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

uuid (string ) • Product uuid

enabled (boolean ) • Whether the product is enabled

family (string ) • Family code from which the product inherits its attributes and attributes requirements.

categories (array [string] ) • Codes of the categories in which the product is classified

groups (array [string] ) • Codes of the groups to which the product belong

parent (string ) • Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.

values (object ) • Product attributes values, see Product values section for more details

associations (object ) : {
associationTypeCode (object ) : {
groups (array [string] ) • Array of groups codes with which the product is in relation
products (array [string] ) • Array of product uuids with which the product is in relation
product_models (array [string] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
}
}

quantified_associations (object ) : {
quantifiedAssociationTypeCode (object ) : {
products (array [object] ) • Array of objects containing product uuids and quantities with which the product is in relation
product_models (array [object] ) • Array of objects containing product model codes and quantities with which the product is in relation
}
}

root_parent (string ) • Code of the root parent product model when the product is a variant (only available for Serenity and when the "with_root_parent" is set to "true")

created (string ) • Date of creation

updated (string ) • Date of the last update

metadata (object ) : {
workflow_status (string ) • Status of the product regarding the user permissions
}

quality_scores (object ) • Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")

completenesses (array [object] ) : [
{
scope (string) •
locale (string) •
data (integer) •
}
]

}

Example

{
      "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
      "enabled": true,
      "family": "tshirt",
      "categories": [
        "summer_collection"
      ],
      "groups": [],
      "parent": null,
      "values": {
        "sku": [
          {
            "data": "top",
            "locale": null,
            "scope": null
          }
        ],
        "name": [
          {
            "data": "Top",
            "locale": "en_US",
            "scope": null
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": null
          }
        ],
        "description": [
          {
            "data": "Summer top",
            "locale": "en_US",
            "scope": "ecommerce"
          },
          {
            "data": "Top",
            "locale": "en_US",
            "scope": "tablet"
          },
          {
            "data": "Débardeur pour l'été",
            "locale": "fr_FR",
            "scope": "ecommerce"
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": "tablet"
          }
        ],
        "price": [
          {
            "locale": null,
            "scope": null,
            "data": [
              {
                "amount": "15.5",
                "currency": "EUR"
              },
              {
                "amount": "15",
                "currency": "USD"
              }
            ]
          }
        ],
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "black",
            "linked_data": {
              "attribute": "color",
              "code": "black",
              "labels": {
                "en_US": "Black",
                "fr_FR": "Noir"
              }
            }
          }
        ],
        "size": [
          {
            "locale": null,
            "scope": null,
            "data": "m",
            "linked_data": {
              "attribute": "size",
              "code": "m",
              "labels": {
                "en_US": "M",
                "fr_FR": "M"
              }
            }
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "winter_2016"
            ],
            "linked_data": {
              "winter_2016": {
                "attribute": "collection",
                "code": "winter_2016",
                "labels": {
                  "en_US": "Winter 2016",
                  "fr_FR": "Hiver 2016"
                }
              }
            }
          }
        ]
      },
      "created": "2016-06-23T18:24:44+02:00",
      "updated": "2016-06-25T17:56:12+02:00",
      "associations": {
        "PACK": {
          "products": [
            "d055527c-0698-4967-8f16-8a5f23f4e5cf"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
              "quantity": 2
            },
            {
              "uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "identifier": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "root_parent": "clothes",
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "completenesses": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": 10
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": 20
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": 30
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": 40
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 401,
      "message": "Authentication is required"
    }

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 403,
      "message": "Access forbidden. You are not allowed to list categories."
    }

Resource not found

The resource code given in the URI does not correspond to any existing PIM resource

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 404,
      "message": "Resource `my_resource_code` does not exist."
    }

Not Acceptable

The `Accept` header is not `application/json` but it should

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 406,
      "message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
    }

Update/create a product

This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Entreprise Edition, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.

Available in PIM versions: 7.0 SaaS

REQUEST

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

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 ) • Product attributes values, see Product values section for more details

root_parent (string , null by default) • Code of the root parent product model when the product is a variant (only available for Serenity and when the "with_root_parent" is set to "true")

created (string ) • Date of creation

updated (string ) • Date of the last update

metadata (object { workflow_status : string } ) • More information around the product (only available since the v2.0 in the Enterprise Edition)

quality_scores (object ) • Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")

completenesses (array [object] ) : [
{
scope (string ) •
locale (string ) •
data (integer ) •
}
]

}

Example

{
      "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
      "enabled": true,
      "family": "tshirt",
      "categories": [
        "summer_collection"
      ],
      "groups": [],
      "parent": null,
      "values": {
        "sku": [
          {
            "data": "top",
            "locale": null,
            "scope": null
          }
        ],
        "name": [
          {
            "data": "Top",
            "locale": "en_US",
            "scope": null
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": null
          }
        ],
        "description": [
          {
            "data": "Summer top",
            "locale": "en_US",
            "scope": "ecommerce"
          },
          {
            "data": "Top",
            "locale": "en_US",
            "scope": "tablet"
          },
          {
            "data": "Débardeur pour l'été",
            "locale": "fr_FR",
            "scope": "ecommerce"
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": "tablet"
          }
        ],
        "price": [
          {
            "locale": null,
            "scope": null,
            "data": [
              {
                "amount": "15.5",
                "currency": "EUR"
              },
              {
                "amount": "15",
                "currency": "USD"
              }
            ]
          }
        ],
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "black",
            "linked_data": {
              "attribute": "color",
              "code": "black",
              "labels": {
                "en_US": "Black",
                "fr_FR": "Noir"
              }
            }
          }
        ],
        "size": [
          {
            "locale": null,
            "scope": null,
            "data": "m",
            "linked_data": {
              "attribute": "size",
              "code": "m",
              "labels": {
                "en_US": "M",
                "fr_FR": "M"
              }
            }
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "winter_2016"
            ],
            "linked_data": {
              "winter_2016": {
                "attribute": "collection",
                "code": "winter_2016",
                "labels": {
                  "en_US": "Winter 2016",
                  "fr_FR": "Hiver 2016"
                }
              }
            }
          }
        ]
      },
      "created": "2016-06-23T18:24:44+02:00",
      "updated": "2016-06-25T17:56:12+02:00",
      "associations": {
        "PACK": {
          "products": [
            "d055527c-0698-4967-8f16-8a5f23f4e5cf"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
              "quantity": 2
            },
            {
              "uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "identifier": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "root_parent": "clothes",
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "completenesses": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": 10
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": 20
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": 30
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": 40
        }
      ]
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 401,
      "message": "Authentication is required"
    }

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 403,
      "message": "Access forbidden. You are not allowed to list categories."
    }

Unsupported Media type

The `Content-type` header has to be `application/json`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/json’ is allowed."
    }

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 422,
      "message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
      "_links": {
        "documentation": {
          "href": "http://api.akeneo.com/api-reference.html"
        }
      }
    }

Delete a product

This endpoint allows you to delete a given product. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to delete.

Available in PIM versions: 7.0 SaaS

REQUEST

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

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

Returns the content of the draft in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

uuid (string ) • Product uuid

enabled (boolean ) • Whether the product is enabled

family (string ) • Family code from which the product inherits its attributes and attributes requirements.

categories (array [string] ) • Codes of the categories in which the product is classified

groups (array [string] ) • Codes of the groups to which the product belong

parent (string ) • Code of the parent product model when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.

values (object ) • Product attributes values, see Product values section for more details

root_parent (string ) • Code of the root parent product model when the product is a variant (only available for Serenity and when the "with_root_parent" is set to "true")

created (string ) • Date of creation

updated (string ) • Date of the last update

metadata (object ) : {
workflow_status (string ) • Status of the product regarding the user permissions
}

quality_scores (object ) • Product quality scores for each channel/locale combination (only available since the 5.0 and when the "with_quality_scores" query parameter is set to "true")

completenesses (array [object] ) : [
{
scope (string) •
locale (string) •
data (integer) •
}
]

}

Example

{
      "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
      "enabled": true,
      "family": "tshirt",
      "categories": [
        "summer_collection"
      ],
      "groups": [],
      "parent": null,
      "values": {
        "sku": [
          {
            "data": "top",
            "locale": null,
            "scope": null
          }
        ],
        "name": [
          {
            "data": "Top",
            "locale": "en_US",
            "scope": null
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": null
          }
        ],
        "description": [
          {
            "data": "Summer top",
            "locale": "en_US",
            "scope": "ecommerce"
          },
          {
            "data": "Top",
            "locale": "en_US",
            "scope": "tablet"
          },
          {
            "data": "Débardeur pour l'été",
            "locale": "fr_FR",
            "scope": "ecommerce"
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": "tablet"
          }
        ],
        "price": [
          {
            "locale": null,
            "scope": null,
            "data": [
              {
                "amount": "15.5",
                "currency": "EUR"
              },
              {
                "amount": "15",
                "currency": "USD"
              }
            ]
          }
        ],
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "black",
            "linked_data": {
              "attribute": "color",
              "code": "black",
              "labels": {
                "en_US": "Black",
                "fr_FR": "Noir"
              }
            }
          }
        ],
        "size": [
          {
            "locale": null,
            "scope": null,
            "data": "m",
            "linked_data": {
              "attribute": "size",
              "code": "m",
              "labels": {
                "en_US": "M",
                "fr_FR": "M"
              }
            }
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "winter_2016"
            ],
            "linked_data": {
              "winter_2016": {
                "attribute": "collection",
                "code": "winter_2016",
                "labels": {
                  "en_US": "Winter 2016",
                  "fr_FR": "Hiver 2016"
                }
              }
            }
          }
        ]
      },
      "created": "2016-06-23T18:24:44+02:00",
      "updated": "2016-06-25T17:56:12+02:00",
      "associations": {
        "PACK": {
          "products": [
            "d055527c-0698-4967-8f16-8a5f23f4e5cf"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
              "quantity": 2
            },
            {
              "uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "identifier": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "root_parent": "clothes",
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "completenesses": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": 10
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": 20
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": 30
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": 40
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 401,
      "message": "Authentication is required"
    }

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 403,
      "message": "Access forbidden. You are not allowed to list categories."
    }

Resource not found

The resource code given in the URI does not correspond to any existing PIM resource

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 404,
      "message": "Resource `my_resource_code` does not exist."
    }

Not Acceptable

The `Accept` header is not `application/json` but it should

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 406,
      "message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
    }

Product [identifier]

This API provides two endpoints for interacting with products:

Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.

Get list of products

This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.

Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS

REQUEST

get /api/rest/v1/products