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


REQUEST

get /api/rest/v1/products

Path parameters

Ø

Query parameters

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

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

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

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

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

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

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

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

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

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
              }
          }
          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.
                   }
              ]
          }
          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)
              }
          }
          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
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/top"
              }
            },
            "identifier": "top",
            "family": "tshirt",
            "groups": [],
            "parent": null,
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "name": [
                {
                  "data": "Top",
                  "locale": "en_US",
                  "scope": null
                },
                {
                  "data": "Débardeur",
                  "locale": "fr_FR",
                  "scope": null
                }
              ],
              "description": [
                {
                  "data": "Summer top",
                  "locale": "en_US",
                  "scope": "ecommerce"
                },
                {
                  "data": "Top",
                  "locale": "en_US",
                  "scope": "tablet"
                },
                {
                  "data": "Débardeur pour l'été",
                  "locale": "fr_FR",
                  "scope": "ecommerce"
                },
                {
                  "data": "Débardeur",
                  "locale": "fr_FR",
                  "scope": "tablet"
                }
              ],
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "15.5",
                      "currency": "EUR"
                    },
                    {
                      "amount": "15",
                      "currency": "USD"
                    }
                  ]
                }
              ],
              "color": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "black"
                }
              ],
              "size": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "m"
                }
              ],
              "collection": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    "winter_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
                  }
                ]
              }
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/cap"
              }
            },
            "identifier": "cap",
            "family": "caps",
            "groups": [],
            "parent": null,
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "name": [
                {
                  "data": "Cap",
                  "locale": "en_US",
                  "scope": null
                },
                {
                  "data": "Casquette",
                  "locale": "fr_FR",
                  "scope": null
                }
              ],
              "description": [
                {
                  "data": "Cap unisex",
                  "locale": "en_US",
                  "scope": "ecommerce"
                },
                {
                  "data": "Cap unisex",
                  "locale": "en_US",
                  "scope": "tablet"
                },
                {
                  "data": "Casquette unisexe",
                  "locale": "fr_FR",
                  "scope": "ecommerce"
                },
                {
                  "data": "Casquette unisexe",
                  "locale": "fr_FR",
                  "scope": "tablet"
                }
              ],
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "20",
                      "currency": "EUR"
                    },
                    {
                      "amount": "20",
                      "currency": "USD"
                    }
                  ]
                }
              ],
              "color": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "black"
                }
              ]
            },
            "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": {}
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
              }
            },
            "identifier": "sweat",
            "family": null,
            "groups": [],
            "parent": null,
            "categories": [
              "winter_collection"
            ],
            "enabled": true,
            "values": {},
            "created": "2016-06-23T11:24:44+02:00",
            "updated": "2016-06-23T11:24:44+02:00",
            "associations": {},
            "quantified_associations": {}
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new product

This endpoint allows you to create a new product. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to create.

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


REQUEST

post /api/rest/v1/products

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

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 } ] } ) • 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

}

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
            }
          ]
        }
      },
      "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

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several products

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

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


REQUEST

patch /api/rest/v1/products

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

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 } ] } ) • 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

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)

}

Example

{"identifier":"cap","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
    {"identifier":"mug","group":["promotion"]}
    {"identifier":"tshirt","family":"clothes"}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"identifier":"cap","status_code":204}
    {"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
    {"line":3,"identifier":"tshirt","status_code":201}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a product

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

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


REQUEST

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

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 product in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

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.
        }
    ]
  }

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)
    }
  }

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
  }

}

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

{

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 } ] } ) • 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

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)

}

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

{

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.
        }
    ]
  }

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)
    }
  }

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
  }

}

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 model

Get list of product models

This endpoint allows you to get a list of product models. Product models are paginated. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.

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


REQUEST

get /api/rest/v1/product-models

Path parameters

Ø

Query parameters

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

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

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

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

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

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return product models paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Product model code
          family_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)
              }
          }
          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
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=qg%3D%3D"
        },
        "first": {
          "href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3"
        },
        "next": {
          "href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=rw%3D%3D"
        }
      },
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "http://demo.akeneo.com/api/rest/v1/product-models/amarisshoe"
              }
            },
            "code": "amarisshoe",
            "family": "shoes",
            "family_variant": "shoes_VariantA1",
            "parent": null,
            "categories": [
              "clothing",
              "shoes"
            ],
            "values": {
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "50.00",
                      "currency": "EUR"
                    }
                  ]
                }
              ],
              "description": [
                {
                  "locale": "en_US",
                  "scope": "ecommerce",
                  "data": "I like shoes!"
                }
              ]
            },
            "associations": {
              "PACK": {
                "products": [
                  "sunglasses"
                ],
                "product_models": [],
                "groups": []
              }
            },
            "quantified_associations": {
              "PRODUCT_SET": {
                "products": [
                  {
                    "identifier": "cap",
                    "quantity": 2
                  },
                  {
                    "identifier": "shoes",
                    "quantity": 1
                  }
                ],
                "product_models": [
                  {
                    "identifier": "model-biker-jacket-leather",
                    "quantity": 2
                  }
                ]
              }
            },
            "quality_scores": [
              {
                "scope": "ecommerce",
                "locale": "en_US",
                "data": "A"
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": "B"
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": "D"
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": "E"
              }
            ],
            "created": "2017-10-04T18:04:10+02:00",
            "updated": "2017-10-04T18:04:10+02:00"
          },
          {
            "_links": {
              "self": {
                "href": "http://demo.akeneo.com/api/rest/v1/product-models/Abiloitshirt"
              }
            },
            "code": "Abiloitshirt",
            "family": "clothing",
            "family_variant": "clothing_VariantA1",
            "parent": null,
            "categories": [
              "clothing",
              "tshirt"
            ],
            "values": {
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "50.00",
                      "currency": "EUR"
                    }
                  ]
                }
              ],
              "description": [
                {
                  "locale": "en_US",
                  "scope": "ecommerce",
                  "data": "I like tshirt!"
                }
              ]
            },
            "associations": {
              "PACK": {
                "products": [
                  "sunglasses"
                ],
                "product_models": [],
                "groups": []
              }
            },
            "quantified_associations": {
              "PRODUCT_SET": {
                "products": [
                  {
                    "identifier": "cap",
                    "quantity": 2
                  }
                ],
                "product_models": []
              }
            },
            "quality_scores": [
              {
                "scope": "ecommerce",
                "locale": "en_US",
                "data": "A"
              },
              {
                "scope": "ecommerce",
                "locale": "fr_FR",
                "data": "B"
              },
              {
                "scope": "tablet",
                "locale": "en_US",
                "data": "D"
              },
              {
                "scope": "tablet",
                "locale": "fr_FR",
                "data": "E"
              }
            ],
            "created": "2017-10-04T18:04:10+02:00",
            "updated": "2017-10-04T18:04:10+02:00"
          },
          {
            "_links": {
              "self": {
                "href": "http://demo.akeneo.com/api/rest/v1/product-models/Astertrousers"
              }
            },
            "code": "Astertrousers",
            "family": "clothing",
            "family_variant": "clothing_VariantA1",
            "parent": null,
            "categories": [
              "clothing",
              "trousers"
            ],
            "values": {
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "50.00",
                      "currency": "EUR"
                    }
                  ]
                }
              ],
              "description": [
                {
                  "locale": "en_US",
                  "scope": "ecommerce",
                  "data": "I like trousers!"
                }
              ]
            },
            "associations": {
              "PACK": {
                "products": [
                  "sunglasses"
                ],
                "product_models": [],
                "groups": []
              }
            },
            "quantified_associations": {},
            "created": "2017-10-04T18:04:10+02:00",
            "updated": "2017-10-04T18:04:10+02:00"
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new product model

This endpoint allows you to create a new product model. In the Enterprise Edition, since the v2.3, permissions based on your user groups are applied to the product model you try to create.

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


REQUEST

post /api/rest/v1/product-models

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Product model code

family_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

}

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"
        }
      ]
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several product models

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

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


REQUEST

patch /api/rest/v1/product-models

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • Product model code

family_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

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)

}

Example

{"code": "sub_sweat_option_a", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
    {"code": "sub_sweat_option_b", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
    {"code":"tshirt", "parent": "root_tshirt", "family_variant":"clothesvariant","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing tshirt"}]}}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"sub_sweat_option_a","status_code":204}
    {"line":2,"code":"sub_sweat_option_b","status_code":422,"message":"Validation failed.","errors":[{"property":"attribute","message":"Cannot set value \"Option A\" for the attribute axis \"a_simple_select\", as another sibling entity already has this value"}]}
    {"line":3,"code":"tshirt","status_code":201}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a product model

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

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


REQUEST

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

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 product model in JSON standard format.

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Product model code

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)
    }
  }

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
  }

}

Example

{
      "code": "model-biker-jacket-leather",
      "family": "clothing",
      "family_variant": "clothing_material_size",
      "parent": "model-biker-jacket",
      "categories": [
        "summer_collection"
      ],
      "values": {
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "antique_white"
          }
        ],
        "material": [
          {
            "locale": null,
            "scope": null,
            "data": "leather"
          }
        ],
        "variation_name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket leather"
          }
        ],
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket"
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "summer_2017"
            ]
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "scope": "ecommerce",
            "data": "Biker jacket"
          }
        ]
      },
      "associations": {
        "PACK": {
          "products": [
            "sunglass"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "identifier": "top",
              "quantity": 2
            },
            {
              "identifier": "cap",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "code": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "created": "2017-10-02T15:03:55+02:00",
      "updated": "2017-10-02T15:03:55+02:00"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a product model

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

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


REQUEST

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

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

{

code (string ) • Product model code

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

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)

}

Example

{
      "code": "model-biker-jacket-leather",
      "family": "clothing",
      "family_variant": "clothing_material_size",
      "parent": "model-biker-jacket",
      "categories": [
        "summer_collection"
      ],
      "values": {
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "antique_white"
          }
        ],
        "material": [
          {
            "locale": null,
            "scope": null,
            "data": "leather"
          }
        ],
        "variation_name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket leather"
          }
        ],
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket"
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "summer_2017"
            ]
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "scope": "ecommerce",
            "data": "Biker jacket"
          }
        ]
      },
      "associations": {
        "PACK": {
          "products": [
            "sunglass"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "identifier": "top",
              "quantity": 2
            },
            {
              "identifier": "cap",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "code": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "created": "2017-10-02T15:03:55+02:00",
      "updated": "2017-10-02T15:03:55+02:00"
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Submit a draft for approval  EE only

This endpoint allows you to submit a product model draft for approval.

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


REQUEST

post /api/rest/v1/product-models/{code}/proposal

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 product model draft.

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


REQUEST

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

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

{

code (string ) • Product model code

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)
    }
  }

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
  }

}

Example

{
      "code": "model-biker-jacket-leather",
      "family": "clothing",
      "family_variant": "clothing_material_size",
      "parent": "model-biker-jacket",
      "categories": [
        "summer_collection"
      ],
      "values": {
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "antique_white"
          }
        ],
        "material": [
          {
            "locale": null,
            "scope": null,
            "data": "leather"
          }
        ],
        "variation_name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket leather"
          }
        ],
        "name": [
          {
            "locale": "en_US",
            "scope": null,
            "data": "Biker jacket"
          }
        ],
        "collection": [
          {
            "locale": null,
            "scope": null,
            "data": [
              "summer_2017"
            ]
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "scope": "ecommerce",
            "data": "Biker jacket"
          }
        ]
      },
      "associations": {
        "PACK": {
          "products": [
            "sunglass"
          ],
          "product_models": [],
          "groups": []
        }
      },
      "quantified_associations": {
        "PRODUCT_SET": {
          "products": [
            {
              "identifier": "top",
              "quantity": 2
            },
            {
              "identifier": "cap",
              "quantity": 1
            }
          ],
          "product_models": [
            {
              "code": "model-biker-jacket-leather",
              "quantity": 2
            }
          ]
        }
      },
      "quality_scores": [
        {
          "scope": "ecommerce",
          "locale": "en_US",
          "data": "A"
        },
        {
          "scope": "ecommerce",
          "locale": "fr_FR",
          "data": "B"
        },
        {
          "scope": "tablet",
          "locale": "en_US",
          "data": "D"
        },
        {
          "scope": "tablet",
          "locale": "fr_FR",
          "data": "E"
        }
      ],
      "created": "2017-10-02T15:03:55+02:00",
      "updated": "2017-10-02T15:03:55+02:00"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Product media file

Get a list of product media files

This endpoint allows you to get a list of media files that are used as attribute values in products or product models.

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


REQUEST

get /api/rest/v1/media-files

Path parameters

Ø

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return media files paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI to get the metadata of the media file
              }
              download (object) : {
                  href (string ) • URI to download the binaries of the media file
              }
          }
          code (string) • Media file code
          original_filename (string) • Original filename of the media file
          mime_type (string) • Mime type of the media file
          size (integer) • Size of the media file
          extension (string) • Extension of the media file
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg"
              },
              "download": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
              }
            },
            "code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
            "original_filename": "10806799-1356.jpg",
            "mime_type": "image/jpeg",
            "size": 16070,
            "extension": "jpg"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg"
              },
              "download": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg/download"
              }
            },
            "code": "d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg",
            "original_filename": "10734346-1480.jpg",
            "mime_type": "image/jpeg",
            "size": 16454,
            "extension": "jpg"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg"
              },
              "download": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg/download"
              }
            },
            "code": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg",
            "original_filename": "12431976-8797.jpg",
            "mime_type": "image/jpeg",
            "size": 19725,
            "extension": "jpg"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg"
              },
              "download": {
                "href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg/download"
              }
            },
            "code": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg",
            "original_filename": "107406-9841.jpg",
            "mime_type": "image/jpeg",
            "size": 17639,
            "extension": "jpg"
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new product media file

This endpoint allows you to create a new media file and associate it to an attribute value of a given product or product model.

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


REQUEST

post /api/rest/v1/media-files

Path parameters

Ø

Query parameters

Ø

Headers

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

Content-type • Equal to 'multipart/form-data', no other value allowed

Body

Given as form-data

product (string ) • The product to which the media file will be associated. It is a JSON string that follows this format '{"identifier":"product_identifier", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'. You have to either use this field or the `product_model` field, but not both at the same time.

product_model (string ) • The product model to which the media file will be associated. It is a JSON string that follows this format '{"code":"product_model_code", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'. You have to either use this field or the `product` field, but not both at the same time.

file (string / binary) • The binaries of the file


RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

The `Content-type` header has to be `multipart/form-data`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a product media file

This endpoint allows you to get the information about a given media file that is used as an attribute value of a product or a product model.

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


REQUEST

get /api/rest/v1/media-files/{code}

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 media file in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

_links (object) : {
    download (object ) : {
        href (string ) • URI to download the binaries of the media file
    }
  }

code (string) • Media file code

original_filename (string) • Original filename of the media file

mime_type (string) • Mime type of the media file

size (integer) • Size of the media file

extension (string) • Extension of the media file

}

Example

{
      "_links": {
        "download": {
          "href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
        }
      },
      "code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
      "original_filename": "10806799-1356.jpg",
      "mime_type": "image/jpeg",
      "size": 16070,
      "extension": "jpg"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Download a product media file

This endpoint allows you to download a given media file that is used as an attribute value of a product or a product model.

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


REQUEST

get /api/rest/v1/media-files/{code}/download

Path parameters

code (string) • Code of the resource

Query parameters

Ø

Headers

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

Body

Ø


RESPONSES

OK

Returns the binary of the media file

Body Format Mime-type of the media file
Media file binary

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Published products

Published product

Important update: Published Products discontinuation. This feature is no longer actively supported and will soon be retired. We recommend exploring alternative solutions. Learn more in the help center.

Get list of published products  EE only

This endpoint allows you to get a list of published products. Published products are paginated and they can be filtered.

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


REQUEST

get /api/rest/v1/published-products

Path parameters

Ø

Query parameters

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

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

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

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

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

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return published products paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          identifier (string) • Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
          enabled (boolean) • Whether the published product is enable
          family (string)Family code from which the published product inherits its attributes and attributes requirements
          categories (array [string ]) • Codes of the categories in which the published product is classified
          groups (array [string ]) • Codes of the groups to which the published product belong
          values (object) : {
              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 published product is in relation
                  products (array [string ] ) • Array of published product identifiers with which the published product is in relation
                  product_models (array [string ] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
              }
          }
          quantified_associations (object) • Warning: associations with quantities are not compatible with the published products. The response will always be empty.
          created (string) • Date of creation
          updated (string) • Date of the last update
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/published-products?page=3&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/published-products?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/published-products?page=2&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/published-products?page=4&limit=3"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/published-products/top"
              }
            },
            "identifier": "top",
            "family": "tshirt",
            "groups": [],
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "name": [
                {
                  "data": "Top",
                  "locale": "en_US",
                  "scope": null
                },
                {
                  "data": "Débardeur",
                  "locale": "fr_FR",
                  "scope": null
                }
              ],
              "description": [
                {
                  "data": "Summer top",
                  "locale": "en_US",
                  "scope": "ecommerce"
                },
                {
                  "data": "Top",
                  "locale": "en_US",
                  "scope": "tablet"
                },
                {
                  "data": "Débardeur pour l'été",
                  "locale": "fr_FR",
                  "scope": "ecommerce"
                },
                {
                  "data": "Débardeur",
                  "locale": "fr_FR",
                  "scope": "tablet"
                }
              ],
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "15.5",
                      "currency": "EUR"
                    },
                    {
                      "amount": "15",
                      "currency": "USD"
                    }
                  ]
                }
              ],
              "color": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "black"
                }
              ],
              "size": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "m"
                }
              ]
            },
            "created": "2016-06-23T18:24:44+02:00",
            "updated": "2016-06-25T17:56:12+02:00",
            "associations": {
              "PACK": {
                "products": [
                  "sunglasses"
                ],
                "product_models": [],
                "groups": []
              }
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/published-products/cap"
              }
            },
            "identifier": "cap",
            "family": "caps",
            "groups": [],
            "categories": [
              "summer_collection"
            ],
            "enabled": true,
            "values": {
              "name": [
                {
                  "data": "Cap",
                  "locale": "en_US",
                  "scope": null
                },
                {
                  "data": "Casquette",
                  "locale": "fr_FR",
                  "scope": null
                }
              ],
              "description": [
                {
                  "data": "Cap unisex",
                  "locale": "en_US",
                  "scope": "ecommerce"
                },
                {
                  "data": "Cap unisex",
                  "locale": "en_US",
                  "scope": "tablet"
                },
                {
                  "data": "Casquette unisexe",
                  "locale": "fr_FR",
                  "scope": "ecommerce"
                },
                {
                  "data": "Casquette unisexe",
                  "locale": "fr_FR",
                  "scope": "tablet"
                }
              ],
              "price": [
                {
                  "locale": null,
                  "scope": null,
                  "data": [
                    {
                      "amount": "20",
                      "currency": "EUR"
                    },
                    {
                      "amount": "20",
                      "currency": "USD"
                    }
                  ]
                }
              ],
              "color": [
                {
                  "locale": null,
                  "scope": null,
                  "data": "black"
                }
              ]
            },
            "created": "2016-06-23T18:24:44+02:00",
            "updated": "2016-06-25T17:56:12+02:00",
            "associations": {
              "PACK": {
                "products": [
                  "sunglasses"
                ],
                "product_models": [],
                "groups": []
              }
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/published-products/sweat"
              }
            },
            "identifier": "sweat",
            "family": null,
            "groups": [],
            "categories": [
              "winter_collection"
            ],
            "enabled": true,
            "values": {},
            "created": "2016-06-23T11:24:44+02:00",
            "updated": "2016-06-23T11:24:44+02:00",
            "associations": {}
          }
        ]
      }
    }

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a published product  EE only

This endpoint allows you to get the information about a given published product.

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


REQUEST

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

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 published product in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

identifier (string ) • Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute

enabled (boolean ) • Whether the published product is enable

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

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

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

values (object ) : {
    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 published product is in relation
        products (array [string] ) • Array of published product identifiers with which the published product is in relation
        product_models (array [string] ) • Array of product model codes with which the product is in relation (only available since the v2.1)
    }
  }

quantified_associations (object ) • Warning: associations with quantities are not compatible with the published products. The response will always be empty.

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{
      "identifier": "top",
      "enabled": true,
      "family": "tshirt",
      "categories": [
        "summer_collection"
      ],
      "groups": [],
      "values": {
        "name": [
          {
            "data": "Top",
            "locale": "en_US",
            "scope": null
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": null
          }
        ],
        "description": [
          {
            "data": "Summer top",
            "locale": "en_US",
            "scope": "ecommerce"
          },
          {
            "data": "Top",
            "locale": "en_US",
            "scope": "tablet"
          },
          {
            "data": "Débardeur pour l'été",
            "locale": "fr_FR",
            "scope": "ecommerce"
          },
          {
            "data": "Débardeur",
            "locale": "fr_FR",
            "scope": "tablet"
          }
        ],
        "price": [
          {
            "locale": null,
            "scope": null,
            "data": [
              {
                "amount": "15.5",
                "currency": "EUR"
              },
              {
                "amount": "15",
                "currency": "USD"
              }
            ]
          }
        ],
        "color": [
          {
            "locale": null,
            "scope": null,
            "data": "black"
          }
        ],
        "size": [
          {
            "locale": null,
            "scope": null,
            "data": "m"
          }
        ]
      },
      "created": "2016-06-23T18:24:44+02:00",
      "updated": "2016-06-25T17:56:12+02:00",
      "associations": {
        "PACK": {
          "products": [
            "sunglass"
          ],
          "product_models": [],
          "groups": []
        }
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Catalog structure

Family

Get list of families

This endpoint allows you to get a list of families. Families are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/families

Path parameters

Ø

Query parameters

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return families paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Family code
          attribute_as_label (string) • Attribute code used as label
          attribute_as_image (string) • Attribute code used as the main picture in the user interface (only since v2.0)
          attributes (array [string ]) • Attributes codes that compose the family
          attribute_requirements (object) : {
              channelCode (array [string ]) • • Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
          }
          labels (object) : {
              localeCode (string) • Family label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/families?page=2&limit=2"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/families?page=3&limit=2"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/families/tshirt"
              }
            },
            "code": "tshirt",
            "attributes": [
              "sku",
              "name",
              "description",
              "price",
              "size",
              "color",
              "picture"
            ],
            "attribute_as_label": "name",
            "attribute_as_image": "picture",
            "attribute_requirements": {
              "ecommerce": [
                "sku",
                "name",
                "description",
                "price",
                "size",
                "color"
              ],
              "tablet": [
                "sku",
                "name",
                "description",
                "price"
              ]
            },
            "labels": {
              "en_US": "Tshirt",
              "fr_FR": "Tshirt"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/families/caps"
              }
            },
            "code": "caps",
            "attributes": [
              "sku",
              "name",
              "description",
              "price",
              "color",
              "picture"
            ],
            "attribute_as_label": "name",
            "attribute_as_image": "picture",
            "attribute_requirements": {
              "ecommerce": [
                "sku",
                "name",
                "description",
                "price",
                "color"
              ],
              "tablet": [
                "sku",
                "name",
                "description",
                "price"
              ]
            },
            "labels": {
              "en_US": "Caps",
              "fr_FR": "Casquettes"
            }
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new family

This endpoint allows you to create a new family.

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


REQUEST

post /api/rest/v1/families

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attribute_as_image (string , null by default) • Attribute code used as the main picture in the user interface (only since v2.0)

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{
      "code": "caps",
      "attributes": [
        "sku",
        "name",
        "description",
        "price",
        "color",
        "picture"
      ],
      "attribute_as_label": "name",
      "attribute_as_image": "picture",
      "attribute_requirements": {
        "ecommerce": [
          "sku",
          "name",
          "description",
          "price",
          "color"
        ],
        "tablet": [
          "sku",
          "name",
          "description",
          "price"
        ]
      },
      "labels": {
        "en_US": "Caps",
        "fr_FR": "Casquettes"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several families

This endpoint allows you to update and/or create several families at once.

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


REQUEST

patch /api/rest/v1/families

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attribute_as_image (string , null by default) • Attribute code used as the main picture in the user interface (only since v2.0)

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{"code":"tshirt","attributes":["description","size"]}
    {"code":"cap","attribute_as_label":"descripion"}
    {"code":"mug","attributes":["description","short_description"]}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"tshirt","status_code":201}
    {"line":2,"code":"cap","status_code":422,"message":"Attribute \"descripion\" does not exist."}
    {"line":3,"code":"mug","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a family

This endpoint allows you to get the information about a given family.

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


REQUEST

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

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 family in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attribute_as_image (string ) • Attribute code used as the main picture in the user interface (only since v2.0)

attributes (array [string] ) • Attributes codes that compose the family

attribute_requirements (object ) : {
    channelCode (array [string] ) • Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
  }

labels (object ) : {
    localeCode (string ) • Family label for the locale `localeCode`
  }

}

Example

{
      "code": "caps",
      "attributes": [
        "sku",
        "name",
        "description",
        "price",
        "color",
        "picture"
      ],
      "attribute_as_label": "name",
      "attribute_as_image": "picture",
      "attribute_requirements": {
        "ecommerce": [
          "sku",
          "name",
          "description",
          "price",
          "color"
        ],
        "tablet": [
          "sku",
          "name",
          "description",
          "price"
        ]
      },
      "labels": {
        "en_US": "Caps",
        "fr_FR": "Casquettes"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a family

This endpoint allows you to update a given family. Know more about Update behavior. Note that if no family exists for the given code, it creates it.

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


REQUEST

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

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

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attribute_as_image (string , null by default) • Attribute code used as the main picture in the user interface (only since v2.0)

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{
      "code": "caps",
      "attributes": [
        "sku",
        "name",
        "description",
        "price",
        "color",
        "picture"
      ],
      "attribute_as_label": "name",
      "attribute_as_image": "picture",
      "attribute_requirements": {
        "ecommerce": [
          "sku",
          "name",
          "description",
          "price",
          "color"
        ],
        "tablet": [
          "sku",
          "name",
          "description",
          "price"
        ]
      },
      "labels": {
        "en_US": "Caps",
        "fr_FR": "Casquettes"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new family variant

This endpoint allows you to create a family variant.

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


REQUEST

post /api/rest/v1/families/{family_code}/variants

Path parameters

family_code (string) • Code of the family

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Family variant code

variant_attribute_sets (array [object] ) : [
        {
            level (integer ) • Enrichment level
            axes (array [string ]) • Codes of attributes used as variant axes
            attributes (array [string ]) • Codes of attributes bind to this enrichment level
        }
    ]

labels (object { localeCode : string } , [] by default) • Family variant labels for each locale

}

Example

{
      "code": "shoesVariant",
      "labels": {
        "en_US": "Shoes variant",
        "fr_FR": "Variante de chaussures"
      },
      "variant_attribute_sets": [
        {
          "level": 1,
          "attributes": [
            "color",
            "material"
          ],
          "axes": [
            "color"
          ]
        },
        {
          "level": 2,
          "attributes": [
            "sku",
            "size"
          ],
          "axes": [
            "size"
          ]
        }
      ]
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Family variant

Get list of family variants

This endpoint allows you to get a list of family variants. Family variants are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/families/{family_code}/variants

Path parameters

family_code (string) • Code of the family

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return family variants paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Family variant code
          variant_attribute_sets (array [object ]) • Attributes distribution according to the enrichment level
          labels (object) : {
              localeCode (string) • Family variant label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "code": "shoesVariant",
      "labels": {
        "en_US": "Shoes variant",
        "fr_FR": "Variante de chaussures"
      },
      "variant_attribute_sets": [
        {
          "level": 1,
          "attributes": [
            "color",
            "material"
          ],
          "axes": [
            "color"
          ]
        },
        {
          "level": 2,
          "attributes": [
            "sku",
            "size"
          ],
          "axes": [
            "size"
          ]
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several family variants

This endpoint allows you to update and/or create several family variants at once, for a given family.

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


REQUEST

patch /api/rest/v1/families/{family_code}/variants

Path parameters

family_code (string) • Code of the family

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • Family variant code

variant_attribute_sets (array [object] ) : [
        {
            level (integer ) • Enrichment level
            axes (array [string ]) • Codes of attributes used as variant axes
            attributes (array [string ]) • Codes of attributes bind to this enrichment level
        }
    ]

labels (object { localeCode : string } , [] by default) • Family variant labels for each locale

}

Example

{"code": "shoes_by_size", "variant_attribute_sets": [{"level": 1, "axes": ["size"], "attributes": ["color"]}]}
    {"code": "shoes_by_color","labels": {"en_US": "Shoes by color"}}
    {"code": "shoes_without_axes", "variant_attribute_sets": [{"level": 1, "axes": [], "attributes": ["color"]}]}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"shoes_by_size","status_code":201}
    {"line":2,"code":"shoes_by_color","status_code":204}
    {"line":3,"code":"mug","status_code":422, "message":"There should be at least one attribute defined as axis for the attribute set for level \"1\""}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a family variant

This endpoint allows you to get the information about a given family variant.

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


REQUEST

get /api/rest/v1/families/{family_code}/variants/{code}

Path parameters

family_code (string) • Code of the family

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 family variant in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Family variant code

variant_attribute_sets (array [object] ) : [
        {
          level (integer) • Enrichment level
          axes (array) • Codes of attributes used as variant axes
          attributes (array) • Codes of attributes bind to this enrichment level
        }
    ]

labels (object ) : {
    localeCode (string ) • Family variant label for the locale `localeCode`
  }

}

Example

{
      "code": "shoesVariant",
      "labels": {
        "en_US": "Shoes variant",
        "fr_FR": "Variante de chaussures"
      },
      "variant_attribute_sets": [
        {
          "level": 1,
          "attributes": [
            "color",
            "material"
          ],
          "axes": [
            "color"
          ]
        },
        {
          "level": 2,
          "attributes": [
            "sku",
            "size"
          ],
          "axes": [
            "size"
          ]
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a family variant

This endpoint allows you to update a given family variant. Know more about Update behavior. Note that if no family variant exists for the given code, it creates it.

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


REQUEST

patch /api/rest/v1/families/{family_code}/variants/{code}

Path parameters

family_code (string) • Code of the family

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

{

code (string ) • Family variant code

variant_attribute_sets (array [object] ) : [
        {
            level (integer ) • Enrichment level
            axes (array [string ]) • Codes of attributes used as variant axes
            attributes (array [string ]) • Codes of attributes bind to this enrichment level
        }
    ]

labels (object { localeCode : string } , [] by default) • Family variant labels for each locale

}

Example

{
      "code": "shoesVariant",
      "labels": {
        "en_US": "Shoes variant",
        "fr_FR": "Variante de chaussures"
      },
      "variant_attribute_sets": [
        {
          "level": 1,
          "attributes": [
            "color",
            "material"
          ],
          "axes": [
            "color"
          ]
        },
        {
          "level": 2,
          "attributes": [
            "sku",
            "size"
          ],
          "axes": [
            "size"
          ]
        }
      ]
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Attribute

Get list of attributes

This endpoint allows you to get a list of attributes. Attributes are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/attributes

Path parameters

Ø

Query parameters

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return attributes paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Attribute code
          type (string) • Attribute type. See type section for more details.
          labels (object) : {
              localeCode (string) • Attribute label for the locale `localeCode`
          }
          group (string) • Attribute group
          group_labels (object) : {
              localeCode (string) • Group label for the locale `localeCode`
          }
          sort_order (integer) • Order of the attribute in its group
          localizable (boolean) • Whether the attribute is localizable, i.e. can have one value by locale
          scopable (boolean) • Whether the attribute is scopable, i.e. can have one value by channel
          available_locales (array [string ]) • To make the attribute locale specfic, specify here for which locales it is specific
          unique (boolean) • Whether two values for the attribute cannot be the same
          useable_as_grid_filter (boolean) • Whether the attribute can be used as a filter for the product grid in the PIM user interface
          max_characters (integer) • Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`
          validation_rule (string) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
          validation_regexp (string) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
          wysiwyg_enabled (boolean) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
          number_min (string) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          number_max (string) • Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          decimals_allowed (boolean) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          negative_allowed (boolean) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
          metric_family (string) • Metric family when the attribute type is `pim_catalog_metric`
          default_metric_unit (string) • Default metric unit when the attribute type is `pim_catalog_metric`
          date_min (string) • Minimum date allowed when the attribute type is `pim_catalog_date`
          date_max (string) • Maximum date allowed when the attribute type is `pim_catalog_date`
          allowed_extensions (array [string ]) • Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`
          max_file_size (string) • Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`
          reference_data_name (string) • Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`
          table_configuration (array [object ]) • Configuration of the Table attribute (columns)
          is_main_identifier (boolean) • Is this attribute main identifier when attribute type is `pim_catalog_identifier`
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=3&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=2&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=4&limit=3"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attributes/sku"
              }
            },
            "code": "sku",
            "type": "pim_catalog_identifier",
            "group": "other",
            "group_labels": {
              "en_US": "Other",
              "fr_FR": "Autre"
            },
            "unique": true,
            "useable_as_grid_filter": true,
            "allowed_extensions": [],
            "metric_family": null,
            "default_metric_unit": null,
            "reference_data_name": null,
            "available_locales": [],
            "max_characters": null,
            "validation_rule": null,
            "validation_regexp": null,
            "wysiwyg_enabled": false,
            "number_min": null,
            "number_max": null,
            "decimals_allowed": false,
            "negative_allowed": false,
            "date_min": null,
            "date_max": null,
            "max_file_size": null,
            "minimum_input_length": null,
            "sort_order": 1,
            "localizable": false,
            "scopable": false,
            "default_value": null,
            "labels": {
              "en_US": "Identifier",
              "fr_FR": "Identifiant"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attributes/release_date"
              }
            },
            "code": "release_date",
            "type": "pim_catalog_date",
            "group": "marketing",
            "unique": false,
            "useable_as_grid_filter": true,
            "allowed_extensions": [],
            "metric_family": null,
            "default_metric_unit": null,
            "reference_data_name": null,
            "available_locales": [],
            "max_characters": null,
            "validation_rule": null,
            "validation_regexp": null,
            "wysiwyg_enabled": false,
            "number_min": null,
            "number_max": null,
            "decimals_allowed": false,
            "negative_allowed": false,
            "date_min": "2017-06-28T08:00:00",
            "date_max": "2017-08-08T22:00:00",
            "max_file_size": null,
            "minimum_input_length": null,
            "sort_order": 1,
            "localizable": false,
            "scopable": false,
            "default_value": null,
            "labels": {
              "en_US": "Sale date",
              "fr_FR": "Date des soldes"
            }
          },
          {
            "_links": {
              "self": {
                "href": "http://localhost:8080/api/rest/v1/attributes/food_composition"
              }
            },
            "code": "food_composition",
            "type": "pim_catalog_table",
            "group": "product",
            "unique": false,
            "useable_as_grid_filter": false,
            "allowed_extensions": [],
            "metric_family": null,
            "default_metric_unit": null,
            "reference_data_name": null,
            "available_locales": [],
            "max_characters": null,
            "validation_rule": null,
            "validation_regexp": null,
            "wysiwyg_enabled": null,
            "number_min": null,
            "number_max": null,
            "decimals_allowed": null,
            "negative_allowed": null,
            "date_min": null,
            "date_max": null,
            "max_file_size": null,
            "minimum_input_length": null,
            "sort_order": 0,
            "localizable": false,
            "scopable": false,
            "labels": {
              "en_US": "Composition",
              "fr_FR": "Composition"
            },
            "guidelines": {},
            "auto_option_sorting": null,
            "is_read_only": null,
            "default_value": null,
            "table_configuration": [
              {
                "code": "ingredient",
                "data_type": "select",
                "labels": {
                  "en_US": "Ingredient",
                  "fr_FR": "Ingrédient"
                },
                "validations": {},
                "is_required_for_completeness": true
              },
              {
                "code": "percentage",
                "data_type": "number",
                "labels": {
                  "en_US": "%",
                  "fr_FR": "%"
                },
                "validations": {
                  "max": 100,
                  "min": 0,
                  "decimals_allowed": true
                },
                "is_required_for_completeness": true
              },
              {
                "code": "allergen",
                "data_type": "boolean",
                "labels": {
                  "en_US": "Allergen",
                  "fr_FR": "Allergène"
                },
                "validations": {},
                "is_required_for_completeness": false
              }
            ]
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new attribute

This endpoint allows you to create a new attribute.

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


REQUEST

post /api/rest/v1/attributes

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Attribute code

type (string ) • Attribute type. See type section for more details.

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

sort_order (integer , 0 by default) • Order of the attribute in its group

localizable (boolean , false by default) • Whether the attribute is localizable, i.e. can have one value by locale

scopable (boolean , false by default) • Whether the attribute is scopable, i.e. can have one value by channel

available_locales (array [string] ) • To make the attribute locale specfic, specify here for which locales it is specific

unique (boolean ) • Whether two values for the attribute cannot be the same

useable_as_grid_filter (boolean ) • Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters (integer ) • Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`

validation_rule (string ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • Maximum date allowed when the attribute type is `pim_catalog_date`

allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`

max_file_size (string ) • Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`

reference_data_name (string ) • Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`

table_configuration (array [object] ) : [
        {
            code (string ) • Column code
            data_type (string ) • Column data type
            validations (object ) • User defined validation constraints on the cell content
            labels (object ) • Column labels for each locale
            is_required_for_completeness (boolean ) • Defines if the column should be entirely filled for the attribute to be considered complete
        }
    ]

is_main_identifier (boolean ) • Is this attribute main identifier when attribute type is `pim_catalog_identifier`

}

Example

{
      "code": "release_date",
      "type": "pim_catalog_date",
      "group": "marketing",
      "unique": false,
      "useable_as_grid_filter": true,
      "allowed_extensions": [],
      "metric_family": null,
      "default_metric_unit": null,
      "reference_data_name": null,
      "available_locales": [],
      "max_characters": null,
      "validation_rule": null,
      "validation_regexp": null,
      "wysiwyg_enabled": null,
      "number_min": null,
      "number_max": null,
      "decimals_allowed": null,
      "negative_allowed": null,
      "date_min": "2017-06-28T08:00:00",
      "date_max": "2017-08-08T22:00:00",
      "max_file_size": null,
      "minimum_input_length": null,
      "sort_order": 1,
      "localizable": false,
      "scopable": false,
      "default_value": null,
      "labels": {
        "en_US": "Sale date",
        "fr_FR": "Date des soldes"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several attributes

This endpoint allows you to update and/or create several attributes at once.

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


REQUEST

patch /api/rest/v1/attributes

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Contains several lines, each line is an attribute in JSON standard format

{

code (string ) • Attribute code

type (string ) • Attribute type. See type section for more details.

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

group_labels (object { localeCode : string } , [] by default) • Group labels for each locale

sort_order (integer , 0 by default) • Order of the attribute in its group

localizable (boolean , false by default) • Whether the attribute is localizable, i.e. can have one value by locale

scopable (boolean , false by default) • Whether the attribute is scopable, i.e. can have one value by channel

available_locales (array [string] ) • To make the attribute locale specfic, specify here for which locales it is specific

unique (boolean ) • Whether two values for the attribute cannot be the same

useable_as_grid_filter (boolean ) • Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters (integer ) • Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`

validation_rule (string ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • Maximum date allowed when the attribute type is `pim_catalog_date`

allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`

max_file_size (string ) • Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`

reference_data_name (string ) • Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`

table_configuration (array [object] ) : [
        {
            code (string ) • Column code
            data_type (string ) • Column data type
            validations (object ) • User defined validation constraints on the cell content
            labels (object ) • Column labels for each locale
            is_required_for_completeness (boolean ) • Defines if the column should be entirely filled for the attribute to be considered complete
        }
    ]

is_main_identifier (boolean ) • Is this attribute main identifier when attribute type is `pim_catalog_identifier`

}

Example

{"code":"description","useable_as_grid_filter":true}
    {"code":"short_description","group":"marketig"}
    {"code":"release_date","date_min":"2017-06-28T08:00:00"}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"description","status_code":201}
    {"line":2,"code":"short_description","status_code":422,"message":"Group \"marketig\" does not exist."}
    {"line":3,"code":"release_date","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get an attribute

This endpoint allows you to get the information about a given attribute.

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


REQUEST

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

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 attribute in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Attribute code

type (string ) • Attribute type. See type section for more details.

labels (object ) : {
    localeCode (string ) • Attribute label for the locale `localeCode`
  }

group (string ) • Attribute group

group_labels (object ) : {
    localeCode (string ) • Group label for the locale `localeCode`
  }

sort_order (integer ) • Order of the attribute in its group

localizable (boolean ) • Whether the attribute is localizable, i.e. can have one value by locale

scopable (boolean ) • Whether the attribute is scopable, i.e. can have one value by channel

available_locales (array [string] ) • To make the attribute locale specfic, specify here for which locales it is specific

unique (boolean ) • Whether two values for the attribute cannot be the same

useable_as_grid_filter (boolean ) • Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters (integer ) • Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`

validation_rule (string ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • Maximum date allowed when the attribute type is `pim_catalog_date`

allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`

max_file_size (string ) • Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`

reference_data_name (string ) • Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`

table_configuration (array [object] ) : [
        {
          code (string) • Column code
          data_type (string) • Column data type
          validations (object) • User defined validation constraints on the cell content
          labels (object) • Column labels for each locale
          is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
        }
    ]

is_main_identifier (boolean ) • Is this attribute main identifier when attribute type is `pim_catalog_identifier`

}

Example

{
      "code": "release_date",
      "type": "pim_catalog_date",
      "group": "marketing",
      "group_labels": {
        "en_US": "Marketing",
        "fr_FR": "Marketing"
      },
      "unique": false,
      "useable_as_grid_filter": true,
      "allowed_extensions": [],
      "metric_family": null,
      "default_metric_unit": null,
      "reference_data_name": null,
      "available_locales": [],
      "max_characters": null,
      "validation_rule": null,
      "validation_regexp": null,
      "wysiwyg_enabled": null,
      "number_min": null,
      "number_max": null,
      "decimals_allowed": null,
      "negative_allowed": null,
      "date_min": "2017-06-28T08:00:00",
      "date_max": "2017-08-08T22:00:00",
      "max_file_size": null,
      "minimum_input_length": null,
      "sort_order": 1,
      "localizable": false,
      "scopable": false,
      "default_value": null,
      "labels": {
        "en_US": "Sale date",
        "fr_FR": "Date des soldes"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create an attribute

This endpoint allows you to update a given attribute. Know more about Update behavior. Note that if no attribute exists for the given code, it creates it.

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


REQUEST

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

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

{

code (string ) • Attribute code

type (string ) • Attribute type. See type section for more details.

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

group_labels (object { localeCode : string } , [] by default) • Group labels for each locale

sort_order (integer , 0 by default) • Order of the attribute in its group

localizable (boolean , false by default) • Whether the attribute is localizable, i.e. can have one value by locale

scopable (boolean , false by default) • Whether the attribute is scopable, i.e. can have one value by channel

available_locales (array [string] ) • To make the attribute locale specfic, specify here for which locales it is specific

unique (boolean ) • Whether two values for the attribute cannot be the same

useable_as_grid_filter (boolean ) • Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters (integer ) • Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`

validation_rule (string ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • Maximum date allowed when the attribute type is `pim_catalog_date`

allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`

max_file_size (string ) • Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`

reference_data_name (string ) • Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`

table_configuration (array [object] ) : [
        {
            code (string ) • Column code
            data_type (string ) • Column data type
            validations (object ) • User defined validation constraints on the cell content
            labels (object ) • Column labels for each locale
            is_required_for_completeness (boolean ) • Defines if the column should be entirely filled for the attribute to be considered complete
        }
    ]

is_main_identifier (boolean ) • Is this attribute main identifier when attribute type is `pim_catalog_identifier`

}

Example

{
      "code": "release_date",
      "type": "pim_catalog_date",
      "group": "marketing",
      "group_labels": {
        "en_US": "Marketing",
        "fr_FR": "Marketing"
      },
      "unique": false,
      "useable_as_grid_filter": true,
      "allowed_extensions": [],
      "metric_family": null,
      "default_metric_unit": null,
      "reference_data_name": null,
      "available_locales": [],
      "max_characters": null,
      "validation_rule": null,
      "validation_regexp": null,
      "wysiwyg_enabled": null,
      "number_min": null,
      "number_max": null,
      "decimals_allowed": null,
      "negative_allowed": null,
      "date_min": "2017-06-28T08:00:00",
      "date_max": "2017-08-08T22:00:00",
      "max_file_size": null,
      "minimum_input_length": null,
      "sort_order": 1,
      "localizable": false,
      "scopable": false,
      "default_value": null,
      "labels": {
        "en_US": "Sale date",
        "fr_FR": "Date des soldes"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Attribute option

Get list of attribute options

This endpoint allows you to get a list of attribute options. Attribute options are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/attributes/{attribute_code}/options

Path parameters

attribute_code (string) • Code of the attribute

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return attribute options paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Code of option
          attribute (string) • Code of attribute related to the attribute option
          sort_order (integer) • Order of attribute option
          labels (object) : {
              localeCode (string) • Attribute option label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=3&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=2&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=4&limit=3"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/red"
              }
            },
            "code": "red",
            "attribute": "a_simple_select",
            "sort_order": 1,
            "labels": {
              "en_US": "Red",
              "fr_FR": "Rouge"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/black"
              }
            },
            "code": "black",
            "attribute": "a_simple_select",
            "sort_order": 2,
            "labels": {
              "en_US": "Black",
              "fr_FR": "Noir"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/purple"
              }
            },
            "code": "purple",
            "attribute": "a_simple_select",
            "sort_order": 3,
            "labels": {
              "en_US": "Purple",
              "fr_FR": "Violet"
            }
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new attribute option

This endpoint allows you to create a new attribute option.

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


REQUEST

post /api/rest/v1/attributes/{attribute_code}/options

Path parameters

attribute_code (string) • Code of the attribute

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 ) • Code of option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object { localeCode : string } , [] by default) • Attribute option labels for each locale

}

Example

{
      "code": "black",
      "attribute": "a_simple_select",
      "sort_order": 2,
      "labels": {
        "en_US": "Black",
        "fr_FR": "Noir"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several attribute options

This endpoint allows you to update several attribute options at once. Please note that this endpoint applies a rate limit of 3 concurrent API requests per second.

Available in PIM versions: 2.1 2.2 2.3 3.x 4.0 5.0 6.0 7.0 SaaS


REQUEST

patch /api/rest/v1/attributes/{attribute_code}/options

Path parameters

attribute_code (string) • Code of the attribute

Query parameters

Ø

Headers

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

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

Body

Contains several lines, each line is an attribute option in JSON standard format

{

code (string ) • Code of option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object { localeCode : string } , [] by default) • Attribute option labels for each locale

}

Example

{"code":"black", "attribute":"a_simple_select", "labels":{"en_US": "Black","fr_FR": "Noir"}}
    {"code":"red", "label":{"en_US": "Red","fr_FR": "Rouge"}}
    {"code":"yellow", "labels":{"en_US": "Yellow","fr_FR": "Jaune"}}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"black","status_code":201}
    {"line":2,"code":"red","status_code":422,"message":"Property \"label\" does not exist. Check the API format documentation."}
    {"line":3,"code":"yellow","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Too many requests

There are too many requests on this endpoint

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 429,
      "message": "You have exceeded the limit of API requests per second."
    }

Get an attribute option

This endpoint allows you to get the information about a given attribute option.

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


REQUEST

get /api/rest/v1/attributes/{attribute_code}/options/{code}

Path parameters

attribute_code (string) • Code of the attribute

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 attribute option in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Code of option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object ) : {
    localeCode (string ) • Attribute option label for the locale `localeCode`
  }

}

Example

{
      "code": "black",
      "attribute": "a_simple_select",
      "sort_order": 2,
      "labels": {
        "en_US": "Black",
        "fr_FR": "Noir"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create an attribute option

This endpoint allows you to update a given attribute option. Know more about Update behavior. Note that if no attribute option exists for the given code, it creates it. Please note that this endpoint applies a rate limit of 3 concurrent API requests per second.

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


REQUEST

patch /api/rest/v1/attributes/{attribute_code}/options/{code}

Path parameters

attribute_code (string) • Code of the attribute

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

{

code (string ) • Code of option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object { localeCode : string } , [] by default) • Attribute option labels for each locale

}

Example

{
      "code": "black",
      "attribute": "a_simple_select",
      "sort_order": 2,
      "labels": {
        "en_US": "Black",
        "fr_FR": "Noir"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Too many requests

There are too many requests on this endpoint

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 429,
      "message": "You have exceeded the limit of API requests per second."
    }

Attribute group

Get list of attribute groups

This endpoint allows you to get a list of attribute groups. Attribute groups are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/attribute-groups

Path parameters

Ø

Query parameters

search (string ) • Filter attribute groups, for more details see the Filters section.

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return attribute groups paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Attribute group code
          sort_order (integer) • Attribute group order among other attribute groups
          attributes (array [string ]) • Attribute codes that compose the attribute group
          labels (object) : {
              localeCode (string) • Attribute group label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=3&limit=2"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=1&limit=2"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=2&limit=2"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=4&limit=2"
        }
      },
      "current_page": 3,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/marketing"
              }
            },
            "code": "marketing",
            "sort_order": 4,
            "attributes": [
              "sku",
              "name",
              "description",
              "response_time",
              "release_date",
              "price"
            ],
            "labels": {
              "en_US": "Marketing",
              "fr_FR": "Marketing"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/technical"
              }
            },
            "code": "technical",
            "sort_order": 5,
            "attributes": [
              "weight",
              "maximum_scan_size",
              "color_scanning",
              "power_requirements",
              "maximum_print_size",
              "sensor_type",
              "total_megapixels",
              "optical_zoom",
              "camera_type"
            ],
            "labels": {
              "en_US": "Technical",
              "fr_FR": "Technique"
            }
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new attribute group

This endpoint allows you to create a new attribute group.

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


REQUEST

post /api/rest/v1/attribute-groups

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Attribute group code

sort_order (integer , 0 by default) • Attribute group order among other attribute groups

attributes (array [string] , [] by default) • Attribute codes that compose the attribute group

labels (object { localeCode : string } , [] by default) • Attribute group labels for each locale

}

Example

{
      "code": "marketing",
      "sort_order": 4,
      "attributes": [
        "sku",
        "name",
        "description",
        "response_time",
        "release_date",
        "price"
      ],
      "labels": {
        "en_US": "Marketing",
        "fr_FR": "Marketing"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several attribute groups

This endpoint allows you to update and/or create several attribute groups at once.

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


REQUEST

patch /api/rest/v1/attribute-groups

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Contains several lines, each line is an attribute group in JSON standard format

{

code (string ) • Attribute group code

sort_order (integer , 0 by default) • Attribute group order among other attribute groups

attributes (array [string] , [] by default) • Attribute codes that compose the attribute group

labels (object { localeCode : string } , [] by default) • Attribute group labels for each locale

}

Example

{"code":"technical","labels":{"en_US": "Technical", "fr_FR": "Technique"}}
    {"code":"marketing","type":"bar"}
    {"code":"design","sort_order":7}

RESPONSES

OK

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

Body Format application/json

Follow the standard format of the entity

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"technical","status_code":201}
    {"line":2,"code":"marketing","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_attribute_groups__code_"}}}
    {"line":3,"code":"design","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get an attribute group

This endpoint allows you to get the information about a given attribute group.

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


REQUEST

get /api/rest/v1/attribute-groups/{code}

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 attribute group in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Attribute group code

sort_order (integer ) • Attribute group order among other attribute groups

attributes (array [string] ) • Attribute codes that compose the attribute group

labels (object ) : {
    localeCode (string ) • Attribute group label for the locale `localeCode`
  }

}

Example

{
      "code": "marketing",
      "sort_order": 4,
      "attributes": [
        "sku",
        "name",
        "description",
        "response_time",
        "release_date",
        "price"
      ],
      "labels": {
        "en_US": "Marketing",
        "fr_FR": "Marketing"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create an attribute group

This endpoint allows you to update a given attribute group. Know more about Update behavior. Note that if no attribute group exists for the given code, it creates it.

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


REQUEST

patch /api/rest/v1/attribute-groups/{code}

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

{

code (string ) • Attribute group code

sort_order (integer , 0 by default) • Attribute group order among other attribute groups

attributes (array [string] , [] by default) • Attribute codes that compose the attribute group

labels (object { localeCode : string } , [] by default) • Attribute group labels for each locale

}

Example

{
      "code": "marketing",
      "sort_order": 4,
      "attributes": [
        "sku",
        "name",
        "description",
        "response_time",
        "release_date",
        "price"
      ],
      "labels": {
        "en_US": "Marketing",
        "fr_FR": "Marketing"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Association type

Get a list of association types

This endpoint allows you to get a list of association types. Association types are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/association-types

Path parameters

Ø

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return association types paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Association type code
          labels (object) : {
              localeCode (string) • Association type label for the locale `localeCode`
          }
          is_quantified (boolean) • When true, the association is a quantified association (Only available in the PIM Serenity version.)
          is_two_way (boolean) • When true, the association is a two-way association (Only available in the PIM Serenity version.)
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
        }
      },
      "current_page": 1,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/association-types/X_SELL"
              }
            },
            "code": "X_SELL",
            "labels": {
              "en_US": "Cross sell",
              "fr_FR": "Vente croisée"
            },
            "is_quantified": false,
            "is_two_way": false
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/association-types/UPSELL"
              }
            },
            "code": "UPSELL",
            "labels": {
              "en_US": "Upsell",
              "fr_FR": "Vente incitative"
            },
            "is_quantified": false,
            "is_two_way": false
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/association-types/SUBSTITUTION"
              }
            },
            "code": "SUBSTITUTION",
            "labels": {
              "en_US": "Substitution",
              "fr_FR": "Remplacement"
            },
            "is_quantified": false,
            "is_two_way": false
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new association type

This endpoint allows you to create a new association type.

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


REQUEST

post /api/rest/v1/association-types

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Association type code

labels (object { localeCode : string } , [] by default) • Association type labels for each locale

is_quantified (boolean , false by default) • When true, the association is a quantified association (Only available in the PIM Serenity version.)

is_two_way (boolean , false by default) • When true, the association is a two-way association (Only available in the PIM Serenity version.)

}

Example

{
      "code": "upsell",
      "labels": {
        "en_US": "Upsell",
        "fr_FR": "Vente incitative"
      },
      "is_quantified": false,
      "is_two_way": false
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several association types

This endpoint allows you to update and/or create several association types at once.

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


REQUEST

patch /api/rest/v1/association-types

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Contains several lines, each line is an association type in JSON standard format

{

code (string ) • Association type code

labels (object { localeCode : string } , [] by default) • Association type labels for each locale

is_quantified (boolean , false by default) • When true, the association is a quantified association (Only available in the PIM Serenity version.)

is_two_way (boolean , false by default) • When true, the association is a two-way association (Only available in the PIM Serenity version.)

}

Example

{"code":"new_sell"}
    {"code":"substitution", "type":"bar"}
    {"code":"x_cross_sell", "is_two_way": true, "is_quantified": false}

RESPONSES

OK

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

Body Format application/json

Follow the standard format of the entity

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"new_sell","status_code":201}
    {"line":2,"code":"substitution","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_association_types__code_"}}}
    {"line":3,"code":"x_cross_sell","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get an association type

This endpoint allows you to get the information about a given association type.

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


REQUEST

get /api/rest/v1/association-types/{code}

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 association type in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Association type code

labels (object ) : {
    localeCode (string ) • Association type label for the locale `localeCode`
  }

is_quantified (boolean ) • When true, the association is a quantified association (Only available in the PIM Serenity version.)

is_two_way (boolean ) • When true, the association is a two-way association (Only available in the PIM Serenity version.)

}

Example

{
      "code": "upsell",
      "labels": {
        "en_US": "Upsell",
        "fr_FR": "Vente incitative"
      },
      "is_quantified": false,
      "is_two_way": false
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create an association type

This endpoint allows you to update a given association type. Know more about Update behavior. Note that if no association type exists for the given code, it creates it.

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


REQUEST

patch /api/rest/v1/association-types/{code}

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

{

code (string ) • Association type code

labels (object { localeCode : string } , [] by default) • Association type labels for each locale

is_quantified (boolean , false by default) • When true, the association is a quantified association (Only available in the PIM Serenity version.)

is_two_way (boolean , false by default) • When true, the association is a two-way association (Only available in the PIM Serenity version.)

}

Example

{
      "code": "upsell",
      "labels": {
        "en_US": "Upsell",
        "fr_FR": "Vente incitative"
      },
      "is_quantified": false,
      "is_two_way": false
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Category

Get list of categories

This endpoint allows you to get a list of categories. Categories are paginated and sorted by `root/left`.

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


REQUEST

get /api/rest/v1/categories

Path parameters

Ø

Query parameters

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return categories paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Category code
          parent (string) • Category code of the parent's category
          updated (string) • Date of the last update
          position (integer) • Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")
          labels (object) : {
              localeCode (string) • Category label for the locale `localeCode`
          }
          values (object) : {
              attributeCode|attributeUuid|channelCode|localeCode (array [object ]) • : [
                  {
                    data (object ) • Attribute value
                    type (string ) • The attribute type
                    locale (string )Locale code of the attribute value
                    channel (string )Channel code of the attribute value
                    attribute_code (string ) • The attribute code with its uuid (attributeCode|attributeUuid)
                   }
              ]
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/categories/winter_collection"
              }
            },
            "code": "winter_collection",
            "parent": null,
            "updated": "2021-05-21T11:32:00+02:00",
            "position": 1,
            "labels": {
              "en_US": "Winter collection",
              "fr_FR": "Collection hiver",
              "de_DE": "Winter-Kollektion"
            },
            "values": {
              "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
                "data": "<p>Winter collection description</p>\n",
                "type": "textarea",
                "channel": "ecommerce",
                "locale": "en_US",
                "attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
              },
              "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
                "data": {
                  "size": 1401359,
                  "extension": "jpg",
                  "file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
                  "mime_type": "image/jpeg",
                  "original_filename": "IMG_7860.jpg"
                },
                "type": "image",
                "channel": "ecommerce",
                "locale": "en_US",
                "attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
              }
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/categories/woman"
              }
            },
            "code": "woman",
            "parent": "winter_collection",
            "updated": "2021-04-21T10:41:02+02:00",
            "position": 1,
            "labels": {
              "en_US": "Woman",
              "fr_FR": "Femme",
              "de_DE": "Damen"
            },
            "values": {}
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/categories/man"
              }
            },
            "code": "man",
            "parent": "winter_collection",
            "updated": "2021-03-02T12:59:59+02:00",
            "position": 2,
            "labels": {
              "en_US": "Man",
              "fr_FR": "Homme",
              "de_DE": "Herren"
            },
            "values": {}
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/categories/kids"
              }
            },
            "code": "kids",
            "parent": "winter_collection",
            "updated": "2021-01-03T12:40:00+02:00",
            "position": 3,
            "labels": {
              "en_US": "Kids",
              "fr_FR": "Enfant",
              "de_DE": "Kinder"
            },
            "values": {}
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/categories/summer_collection"
              }
            },
            "code": "summer_collection",
            "parent": null,
            "updated": "2021-04-04T09:42:00+02:00",
            "position": 1,
            "labels": {
              "en_US": "Summer collection",
              "fr_FR": "Collection été",
              "de_DE": "Sommer-Kollektion"
            },
            "values": {}
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new category

This endpoint allows you to create a new category.

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


REQUEST

post /api/rest/v1/categories

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Category code

parent (string , null by default) • Category code of the parent's category

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{
      "code": "winter_collection",
      "parent": null,
      "labels": {
        "en_US": "Winter collection",
        "fr_FR": "Collection hiver"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several categories

This endpoint allows you to update several categories at once.

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


REQUEST

patch /api/rest/v1/categories

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • Category code

parent (string , null by default) • Category code of the parent's category

updated (string ) • Date of the last update

position (integer ) • Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{"code":"spring_collection","parent":null}
    {"code":"woman","parent":"spring_collectionn"}
    {"code":"man","parent":"spring_collection"}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"spring_collection","status_code":201}
    {"line":2,"code":"woman","status_code":422,"message":"Category \"spring_collectionn\" does not exist."}
    {"line":3,"code":"man","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a category

This endpoint allows you to get the information about a given category.

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


REQUEST

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

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 category in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Category code

parent (string ) • Category code of the parent's category

updated (string ) • Date of the last update

position (integer ) • Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")

labels (object ) : {
    localeCode (string ) • Category label for the locale `localeCode`
  }

values (object ) : {
    attributeCode|attributeUuid|channelCode|localeCode (array [object] ) : [
        {
            data (object ) • Attribute value
            type (string ) • The attribute type
            locale (string ) Locale code of the attribute value
            channel (string ) Channel code of the attribute value
            attribute_code (string ) • The attribute code with its uuid (attributeCode|attributeUuid)
        }
    ]
  }

}

Example

{
      "code": "winter_collection",
      "parent": null,
      "updated": "2021-05-22T12:48:00+02:00",
      "position": 1,
      "labels": {
        "en_US": "Winter collection",
        "fr_FR": "Collection hiver"
      },
      "values": {
        "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
          "data": "<p>Winter collection description</p>\n",
          "type": "textarea",
          "channel": "ecommerce",
          "locale": "en_US",
          "attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
        },
        "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
          "data": {
            "size": 1401359,
            "extension": "jpg",
            "file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
            "mime_type": "image/jpeg",
            "original_filename": "IMG_7860.jpg"
          },
          "type": "image",
          "channel": "ecommerce",
          "locale": "en_US",
          "attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
        }
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a category

This endpoint allows you to update a given category. Know more about Update behavior. Note that if no category exists for the given code, it creates it.

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


REQUEST

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

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

{

code (string ) • Category code

parent (string , null by default) • Category code of the parent's category

updated (string ) • Date of the last update

position (integer ) • Position of the category in its level, start from 1 (only available since the 7.0 version and when query parameter "with_position" is set to "true")

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{
      "code": "winter_collection",
      "parent": null,
      "updated": "2021-05-22T12:48:00+02:00",
      "position": 1,
      "labels": {
        "en_US": "Winter collection",
        "fr_FR": "Collection hiver"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Target market settings

Channel

Get a list of channels

This endpoint allows you to get a list of channels. Channels are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/channels

Path parameters

Ø

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return channels paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Channel code
          locales (array [string ]) • Codes of activated locales for the channel
          currencies (array [string ]) • Codes of activated currencies for the channel
          category_tree (string) • Code of the category tree linked to the channel
          conversion_units (object) : {
              attributeCode (string) • Conversion unit code used to convert the values of the attribute `attributeCode` when exporting via the channel
          }
          labels (object) : {
              localeCode (string) • Channel label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3"
        }
      },
      "current_page": 1,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/channels/ecommerce"
              }
            },
            "code": "ecommerce",
            "currencies": [
              "USD",
              "EUR"
            ],
            "locales": [
              "en_US",
              "fr_FR",
              "de_DE"
            ],
            "category_tree": "master",
            "conversion_units": {
              "a_metric": "KILOWATT",
              "a_metric_negative": "CELSIUS",
              "a_metric_to_not_convert": null
            },
            "labels": {
              "en_US": "Ecommerce",
              "fr_FR": "E-commerce",
              "de_DE": "E-commerce"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/channels/mobile"
              }
            },
            "code": "mobile",
            "currencies": [
              "USD",
              "EUR"
            ],
            "locales": [
              "en_US",
              "fr_FR",
              "de_DE"
            ],
            "category_tree": "master",
            "conversion_units": {
              "a_metric": "KILOWATT",
              "a_metric_negative": "CELSIUS",
              "a_metric_to_not_convert": null
            },
            "labels": {
              "en_US": "Mobile",
              "fr_FR": "Mobile",
              "de_DE": "Mobile"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/channels/print"
              }
            },
            "code": "print",
            "currencies": [
              "USD",
              "EUR"
            ],
            "locales": [
              "en_US",
              "fr_FR",
              "de_DE"
            ],
            "category_tree": "master",
            "conversion_units": {},
            "labels": {
              "en_US": "Print",
              "fr_FR": "Print",
              "de_DE": "Print"
            }
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new channel

This endpoint allows you to create a new channel.

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


REQUEST

post /api/rest/v1/channels

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • Channel code

locales (array [string] ) • Codes of activated locales for the channel

currencies (array [string] ) • Codes of activated currencies for the channel

category_tree (string ) • Code of the category tree linked to the channel

conversion_units (object { attributeCode : string } ) • Units to which the given metric attributes should be converted when exporting products

labels (object { localeCode : string } , [] by default) • Channel labels for each locale

}

Example

{
      "code": "ecommerce",
      "currencies": [
        "USD",
        "EUR"
      ],
      "locales": [
        "de_DE",
        "en_US",
        "fr_FR"
      ],
      "category_tree": "master",
      "conversion_units": {
        "weight": "KILOGRAM"
      },
      "labels": {
        "en_US": "Ecommerce",
        "de_DE": "Ecommerce",
        "fr_FR": "Ecommerce"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several channels

This endpoint allows you to update and/or create several channels at once.

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


REQUEST

patch /api/rest/v1/channels

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • Channel code

locales (array [string] ) • Codes of activated locales for the channel

currencies (array [string] ) • Codes of activated currencies for the channel

category_tree (string ) • Code of the category tree linked to the channel

conversion_units (object { attributeCode : string } ) • Units to which the given metric attributes should be converted when exporting products

labels (object { localeCode : string } , [] by default) • Channel labels for each locale

}

Example

{"code":"ecommerce_fr", "category_tree": "master", "currencies": ["EUR"], "locales": ["fr_FR"], "labels":{"fr_FR": "Ecommerce Fr"}}
    {"code":"ecommerce_ch", "type":"bar"}
    {"code":"tablet", "labels":{"en_US": "Tablet", "fr_FR": "Tablette"}}

RESPONSES

OK

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

Body Format application/json

Follow the standard format of the entity

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"ecommerce_fr","status_code":201}
    {"line":2,"code":"ecommerce_ch","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_channels__code_"}}}
    {"line":3,"code":"tablet","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a channel

This endpoint allows you to get the information about a given channel.

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


REQUEST

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

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 channel in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Channel code

locales (array [string] ) • Codes of activated locales for the channel

currencies (array [string] ) • Codes of activated currencies for the channel

category_tree (string ) • Code of the category tree linked to the channel

conversion_units (object ) : {
    attributeCode (string ) • Conversion unit code used to convert the values of the attribute `attributeCode` when exporting via the channel
  }

labels (object ) : {
    localeCode (string ) • Channel label for the locale `localeCode`
  }

}

Example

{
      "code": "ecommerce",
      "currencies": [
        "USD",
        "EUR"
      ],
      "locales": [
        "de_DE",
        "en_US",
        "fr_FR"
      ],
      "category_tree": "master",
      "conversion_units": {
        "weight": "KILOGRAM"
      },
      "labels": {
        "en_US": "Ecommerce",
        "de_DE": "Ecommerce",
        "fr_FR": "Ecommerce"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a channel

This endpoint allows you to update a given channel. Know more about Update behavior. Note that if no channel exists for the given code, it creates it.

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


REQUEST

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

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

{

code (string ) • Channel code

locales (array [string] ) • Codes of activated locales for the channel

currencies (array [string] ) • Codes of activated currencies for the channel

category_tree (string ) • Code of the category tree linked to the channel

conversion_units (object { attributeCode : string } ) • Units to which the given metric attributes should be converted when exporting products

labels (object { localeCode : string } , [] by default) • Channel labels for each locale

}

Example

{
      "code": "ecommerce",
      "currencies": [
        "USD",
        "EUR"
      ],
      "locales": [
        "de_DE",
        "en_US",
        "fr_FR"
      ],
      "category_tree": "master",
      "conversion_units": {
        "weight": "KILOGRAM"
      },
      "labels": {
        "en_US": "Ecommerce",
        "de_DE": "Ecommerce",
        "fr_FR": "Ecommerce"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Locale

Get a list of locales

This endpoint allows you to get a list of locales. Locales are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/locales

Path parameters

Ø

Query parameters

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return locales paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Locale code
          enabled (boolean) • Whether the locale is enabled
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/locales?page=2&limit=4"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=4"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=4"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/locales?page=2&limit=4"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/locales/en_US"
              }
            },
            "code": "en_US",
            "enabled": true
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/locales/fr_FR"
              }
            },
            "code": "fr_FR",
            "enabled": true
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/locales/de_DE"
              }
            },
            "code": "de_DE",
            "enabled": true
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/locales/af_ZA"
              }
            },
            "code": "af_ZA",
            "enabled": false
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a locale

This endpoint allows you to get the information about a given locale.

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


REQUEST

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

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 locale in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Locale code

enabled (boolean ) • Whether the locale is enabled

}

Example

{
      "code": "en_US",
      "enable": true
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Currency

Get a list of currencies

This endpoint allows you to get a list of currencies. Currencies are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/currencies

Path parameters

Ø

Query parameters

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return currencies paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Currency code
          enabled (boolean) • Whether the currency is enabled
          label (string) • Currency label
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3"
        }
      },
      "current_page": 1,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/currencies/ADP"
              }
            },
            "code": "ADP",
            "enabled": true,
            "label": "ADP (Andorran Peseta)"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/currencies/AED"
              }
            },
            "code": "AED",
            "enabled": true,
            "label": "AED (United Arab Emirates Dirham)"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/currencies/AFA"
              }
            },
            "code": "AFA",
            "enabled": false,
            "label": "AFA (Afghan Afghani (1927–2002))"
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a currency

This endpoint allows you to get the information about a given currency.

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


REQUEST

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

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 currency in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Currency code

enabled (boolean ) • Whether the currency is enabled

label (string ) • Currency label

}

Example

{
      "code": "EUR",
      "enabled": true,
      "label": "EUR (Euro)"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Measure family

Get list of measure familiy

This endpoint allows you to get a list of measure families. Measure families are paginated and sorted by code.

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


REQUEST

get /api/rest/v1/measure-families

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Ø


RESPONSES

Return measure families paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Measure family code
          standard (string) • Measure family standard
          units (array [object ]) • Family units
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/measure-families?page=1&limit=1"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/measure-families?page=1&limit=1"
        }
      },
      "current_page": 1,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/measure-families/Area"
              }
            },
            "code": "Area",
            "standard": "SQUARE_METER",
            "units": [
              {
                "code": "SQUARE_MILLIMETER",
                "convert": {
                  "mul": "0.000001"
                },
                "symbol": "mm²"
              },
              {
                "code": "SQUARE_CENTIMETER",
                "convert": {
                  "mul": "0.0001"
                },
                "symbol": "cm²"
              },
              {
                "code": "SQUARE_DECIMETER",
                "convert": {
                  "mul": "0.01"
                },
                "symbol": "dm²"
              },
              {
                "code": "SQUARE_METER",
                "convert": {
                  "mul": "1"
                },
                "symbol": "m²"
              },
              {
                "code": "CENTIARE",
                "convert": {
                  "mul": "1"
                },
                "symbol": "ca"
              },
              {
                "code": "SQUARE_DEKAMETER",
                "convert": {
                  "mul": "100"
                },
                "symbol": "dam²"
              },
              {
                "code": "ARE",
                "convert": {
                  "mul": "100"
                },
                "symbol": "a"
              },
              {
                "code": "SQUARE_HECTOMETER",
                "convert": {
                  "mul": "10000"
                },
                "symbol": "hm²"
              }
            ]
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a measure family

This endpoint allows you to get the information about a given measure family.

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


REQUEST

get /api/rest/v1/measure-families/{code}

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 measure family in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Measure family code

standard (string ) • Measure family standard

units (array [object] ) : [
        {
          code (string) • Measure code
          convert (object) • Mathematic operation to convert the unit into the standard unit
          symbol (string) • Measure symbol
        }
    ]

}

Example

{
      "code": "Area",
      "standard": "SQUARE_METER",
      "units": [
        {
          "code": "SQUARE_MILLIMETER",
          "convert": {
            "mul": "0.001"
          },
          "symbol": "mm²"
        },
        {
          "code": "SQUARE_CENTIMETER",
          "convert": {
            "mul": "0.001"
          },
          "symbol": "cm²"
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Reference entities

Reference entity

Get list of reference entities  EE only

This endpoint allows you to get a list of reference entities. Reference entities are paginated.

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


REQUEST

get /api/rest/v1/reference-entities

Path parameters

Ø

Query parameters

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

Headers

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

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

Body

Ø


RESPONSES

Return reference entities paginated

Body Format application/json

Follow the standard format of the entity

{

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

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
              image_download (object) : {
                  href (string ) • URI to download the binaries of the reference entity image file
              }
          }
          code (string) • Reference entity code
          labels (object) : {
              localeCode (string) • Reference entity label for the locale `localeCode`
          }
          image (string) • Code of the reference entity image
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities?search_after=2x055w%3D%3D"
        }
      },
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands"
              },
              "image_download": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
              }
            },
            "code": "brands",
            "labels": {
              "en_US": "Brands",
              "fr_FR": "Marque"
            },
            "image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/designers"
              }
            },
            "code": "designers",
            "labels": {
              "en_US": "Designers",
              "fr_FR": "Designers"
            },
            "image": null
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/colors"
              }
            },
            "code": "colors",
            "labels": {
              "en_US": "Colors",
              "fr_FR": "Couleurs"
            },
            "image": null
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a reference entity  EE only

This endpoint allows you to get the information about a given reference entity.

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


REQUEST

get /api/rest/v1/reference-entities/{code}

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 reference entity in JSON format.

Body Format application/json

Follow the standard format of the entity

{

_links (object) : {
    image_download (object ) : {
        href (string ) • URI to download the binaries of the reference entity image file
    }
  }

code (string) • Reference entity code

labels (object) : {
    localeCode (string ) • Reference entity label for the locale `localeCode`
  }

image (string) • Code of the reference entity image

}

Example

{
      "_links": {
        "image_download": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
        }
      },
      "code": "brands",
      "labels": {
        "en_US": "Brands",
        "fr_FR": "Marques"
      },
      "image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a reference entity  EE only

This endpoint allows you to update a given reference entity. Note that if the reference entity does not already exist, it creates it.

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


REQUEST

patch /api/rest/v1/reference-entities/{code}

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

{

code (string ) • Reference entity code

labels (object { localeCode : string } , [] by default) • Reference entity labels for each locale

image (string , null by default) • Code of the reference entity image

}

Example

{
      "code": "brands",
      "labels": {
        "en_US": "Brands",
        "fr_FR": "Marques"
      },
      "image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Reference entity attribute

Get the list of attributes of a given reference entity  EE only

This endpoint allows you to get the list of attributes of a given reference entity.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/attributes

Path parameters

reference_entity_code (string) • Code of the reference entity

Query parameters

Ø

Headers

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

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

Body

Ø


RESPONSES

Return the attributes of the given reference entity

Body Format application/json

[
    {
        code (string ) • Attribute code
        labels (object ) • Attribute labels for each locale
        type (string ) • Attribute type. See type section for more details.
        value_per_locale (boolean ) • Whether the attribute is localizable, i.e. can have one value by locale
        value_per_channel (boolean ) • Whether the attribute is scopable, i.e. can have one value by channel
        is_required_for_completeness (boolean ) • Whether the attribute should be part of the record's completeness calculation
        max_characters (integer ) • Maximum number of characters allowed for the value of the attribute when the attribute type is `text`
        is_textarea (boolean ) • Whether the UI should display a text area instead of a simple field when the attribute type is `text`
        is_rich_text_editor (boolean ) • Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`
        validation_rule (string ) • Validation rule type used to validate the attribute value when the attribute type is `text`
        validation_regexp (string ) • Regexp expression used to validate the attribute value when the attribute type is `text`
        allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `image`
        max_file_size (string ) • Max file size in MB when the attribute type is `image`
        reference_entity_code (string ) • Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`
        decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `number`
        min_value (string ) • Minimum value allowed when the attribute type is `number`
        max_value (string ) • Maximum value allowed when the attribute type is `number`
    }
]

Example

[
      {
        "code": "description",
        "labels": {
          "en_US": "Description",
          "fr_FR": "Description"
        },
        "type": "text",
        "value_per_locale": true,
        "value_per_channel": false,
        "is_required_for_completeness": true,
        "max_characters": null,
        "is_textarea": true,
        "is_rich_text_editor": true,
        "validation_rule": "none",
        "validation_regexp": null
      },
      {
        "code": "country",
        "labels": {
          "en_US": "Country",
          "fr_FR": "Pays"
        },
        "type": "text",
        "value_per_locale": false,
        "value_per_channel": false,
        "is_required_for_completeness": false
      },
      {
        "code": "creation_year",
        "labels": {
          "en_US": "Creation year",
          "fr_FR": "Année de création"
        },
        "type": "number",
        "value_per_locale": false,
        "value_per_channel": false,
        "is_required_for_completeness": false,
        "decimals_allowed": false,
        "min_value": "1800",
        "max_value": "2100"
      },
      {
        "code": "collection_overview",
        "labels": {
          "en_US": "Collection overview",
          "fr_FR": "Aperçu de la collection"
        },
        "type": "image",
        "value_per_locale": true,
        "value_per_channel": false,
        "is_required_for_completeness": true,
        "allowed_extensions": [
          "png"
        ],
        "max_file_size": "1000"
      }
    ]

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get an attribute of a given reference entity  EE only

This endpoint allows you to get the information about a given attribute for a given reference entity.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

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 reference entity attribute in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Attribute code

labels (object ) : {
    localeCode (string ) • Attribute label for the locale `localeCode`
  }

type (string ) • Attribute type. See type section for more details.

value_per_locale (boolean ) • Whether the attribute is localizable, i.e. can have one value by locale

value_per_channel (boolean ) • Whether the attribute is scopable, i.e. can have one value by channel

is_required_for_completeness (boolean ) • Whether the attribute should be part of the record's completeness calculation

max_characters (integer ) • Maximum number of characters allowed for the value of the attribute when the attribute type is `text`

is_textarea (boolean ) • Whether the UI should display a text area instead of a simple field when the attribute type is `text`

is_rich_text_editor (boolean ) • Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`

validation_rule (string ) • Validation rule type used to validate the attribute value when the attribute type is `text`

validation_regexp (string ) • Regexp expression used to validate the attribute value when the attribute type is `text`

allowed_extensions (array [string] ) • Extensions allowed when the attribute type is `image`

max_file_size (string ) • Max file size in MB when the attribute type is `image`

reference_entity_code (string ) • Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `number`

min_value (string ) • Minimum value allowed when the attribute type is `number`

max_value (string ) • Maximum value allowed when the attribute type is `number`

}

Example

{
      "code": "description",
      "labels": {
        "en_US": "Description",
        "fr_FR": "Description"
      },
      "type": "text",
      "value_per_locale": true,
      "value_per_channel": false,
      "is_required_for_completeness": true,
      "max_characters": null,
      "is_textarea": true,
      "is_rich_text_editor": true,
      "validation_rule": "none",
      "validation_regexp": null
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create an attribute of a given reference entity  EE only

This endpoint allows you to update a given attribute for a given renference entity. Note that if the attribute does not already exist for the given reference entity, it creates it.

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


REQUEST

patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

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

{

code (string ) • Attribute code

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

type (string ) • Attribute type. See type section for more details.

value_per_locale (boolean , false by default) • Whether the attribute is localizable, i.e. can have one value by locale

value_per_channel (boolean , false by default) • Whether the attribute is scopable, i.e. can have one value by channel

is_required_for_completeness (boolean , false by default) • Whether the attribute should be part of the record's completeness calculation

max_characters (integer ) • Maximum number of characters allowed for the value of the attribute when the attribute type is `text`

is_textarea (boolean , false by default) • Whether the UI should display a text area instead of a simple field when the attribute type is `text`

is_rich_text_editor (boolean ) • Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text`

validation_rule (string , none by default) • Validation rule type used to validate the attribute value when the attribute type is `text`

validation_regexp (string , null by default) • Regexp expression used to validate the attribute value when the attribute type is `text`

allowed_extensions (array [string] , [] by default) • Extensions allowed when the attribute type is `image`

max_file_size (string , null by default) • Max file size in MB when the attribute type is `image`

reference_entity_code (string , null by default) • Code of the linked reference entity when the attribute type is `reference_entity_single_link` or `reference_entity_multiple_links`

decimals_allowed (boolean , false by default) • Whether decimals are allowed when the attribute type is `number`

min_value (string , null by default) • Minimum value allowed when the attribute type is `number`

max_value (string , null by default) • Maximum value allowed when the attribute type is `number`

}

Example

{
      "code": "description",
      "labels": {
        "en_US": "Description",
        "fr_FR": "Description"
      },
      "type": "text",
      "value_per_locale": true,
      "value_per_channel": false,
      "is_required_for_completeness": true,
      "max_characters": null,
      "is_textarea": true,
      "is_rich_text_editor": true,
      "validation_rule": "none",
      "validation_regexp": null
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Reference entity attribute option

Get a list of attribute options of a given attribute for a given reference entity  EE only

This endpoint allows you to get a list of attribute options for a given reference entity.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options

Path parameters

reference_entity_code (string) • Code of the reference entity

attribute_code (string) • Code of the attribute

Query parameters

Ø

Headers

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

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

Body

Ø


RESPONSES

Return the options of the given attributes of the given reference entity

Body Format application/json

[
    {
        code (string ) • Attribute's option code
        labels (object ) • Attribute labels for each locale
    }
]

Example

[
      {
        "code": "woodland_retreat",
        "labels": {
          "en_US": "Woodland Retreat",
          "fr_FR": "Retraite dans les Bois"
        }
      },
      {
        "code": "new_nordic",
        "labels": {
          "en_US": "New Nordic",
          "fr_FR": "Renouveau Scandinave"
        }
      },
      {
        "code": "global_nomad",
        "labels": {
          "en_US": "Global Nomad",
          "fr_FR": "Nomade du Monde"
        }
      }
    ]

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get an attribute option for a given attribute of a given reference entity  EE only

This endpoint allows you to get the information about a given attribute option.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

attribute_code (string) • Code of the attribute

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 reference entity attribute option in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Attribute's option code

labels (object ) : {
    localeCode (string ) • Attribute label for the locale `localeCode`
  }

}

Example

{
      "code": "global_nomad",
      "labels": {
        "en_US": "Global Nomad",
        "fr_FR": "Nomade du Monde"
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a reference entity attribute option  EE only

This endpoint allows you to update a given option for a given attribute and a given reference entity. Learn more about Update behavior. Note that if the option does not already exist for the given attribute of the given reference entity, it creates it.

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


REQUEST

patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

attribute_code (string) • Code of the attribute

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

{

code (string ) • Attribute's option code

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

}

Example

{
      "code": "global_nomad",
      "labels": {
        "en_US": "Global Nomad",
        "fr_FR": "Nomade du Monde"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Reference entity record

Get the list of the records of a reference entity  EE only

This endpoint allows you to get a list of records of a given reference entity. Records are paginated and can be filtered.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/records

Path parameters

reference_entity_code (string) • Code of the reference entity

Query parameters

search (string ) • Filter records of the reference entity, for more details see the Filters section

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Return the records of the given reference entity paginated

Body Format application/json

Follow the standard format of the entity

{

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

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • Code of the record
          values (object) : {
              attributeCode (array [object ]) • : [
                  {
                    channel (string ) • Channel code of the reference entity record value
                    locale (string ) • Locale code of the reference entity record value
                    data (object ) • Reference entity record value. See the `data` format section for more details.
                   }
              ]
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records?search_after=2x088w%3D%3D"
        }
      },
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/kartell"
              }
            },
            "code": "kartell",
            "values": {
              "label": [
                {
                  "locale": "en_US",
                  "channel": null,
                  "data": "Kartell"
                }
              ],
              "image": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
                }
              ],
              "description": [
                {
                  "data": "The contemporary Italian furniture brand",
                  "locale": "en_US",
                  "channel": null
                },
                {
                  "data": "L'éditeur de meubles comtemporain italien",
                  "locale": "fr_FR",
                  "channel": null
                }
              ],
              "country": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "italy"
                }
              ]
            },
            "created": "2021-01-01T01:23:34+00:00",
            "updated": "2021-02-03T23:45:60+00:00"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/usm"
              }
            },
            "code": "usm",
            "values": {
              "label": [
                {
                  "locale": "en_US",
                  "channel": null,
                  "data": "USM"
                }
              ],
              "image": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "9/c/g/1/0cb0c0e115dedba76f8d1ad8343ec897abc43bv4_image.jpg"
                }
              ],
              "description": [
                {
                  "data": "Modular furniture from Switzerland for your home and office",
                  "locale": "en_US",
                  "channel": null
                },
                {
                  "data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises",
                  "locale": "fr_FR",
                  "channel": null
                }
              ],
              "country": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "switzerland"
                }
              ]
            },
            "created": "2021-01-01T01:23:34+00:00",
            "updated": "2021-02-03T23:45:60+00:00"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/ligneroset"
              }
            },
            "code": "ligneroset",
            "values": {
              "label": [
                {
                  "locale": "en_US",
                  "channel": null,
                  "data": "Ligne Roset"
                }
              ],
              "image": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "4/b/0/1/0cb0c0e115dedde78b8d1ad8343ec980cd5daa54_image.jpg"
                }
              ],
              "description": [
                {
                  "data": "Very well known French brand of modern and luxury furniture",
                  "locale": "en_US",
                  "channel": null
                },
                {
                  "data": "La marque renommée des meubles de luxe à la française",
                  "locale": "fr_FR",
                  "channel": null
                }
              ],
              "country": [
                {
                  "locale": null,
                  "channel": null,
                  "data": "france"
                }
              ]
            },
            "created": "2021-01-01T01:23:34+00:00",
            "updated": "2021-02-03T23:45:60+00:00"
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create several reference entity records  EE only

This endpoint allows you to update and/or create several records of one given reference entity at once. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.

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


REQUEST

patch /api/rest/v1/reference-entities/{reference_entity_code}/records

Path parameters

reference_entity_code (string) • Code of the reference entity

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

   [

       code (string ) • Code of the record

       values (object { attributeCode : array [ object { channel : string , locale : string , data : object } ] } ) • Record attributes values, see Reference entity record values section for more details

   ]

}

Example

[
      {
        "code": "kartell",
        "values": {
          "label": [
            {
              "locale": "en_US",
              "channel": null,
              "data": "Kartell"
            }
          ],
          "image": [
            {
              "locale": null,
              "channel": null,
              "data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
            }
          ],
          "description": [
            {
              "locale": "en_US",
              "channel": null,
              "data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
            },
            {
              "locale": "fr_FR",
              "channel": null,
              "data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
            }
          ],
          "country": [
            {
              "locale": null,
              "channel": null,
              "data": "italy"
            }
          ],
          "collection_overview": [
            {
              "locale": null,
              "channel": null,
              "data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
            }
          ],
          "creation_year": [
            {
              "locale": null,
              "channel": null,
              "data": "1949"
            }
          ]
        }
      },
      {
        "code": "ligneroset",
        "values": {
          "label": [
            {
              "locale": "en_US",
              "channel": null,
              "data": "Ligne Roset"
            }
          ],
          "image": [
            {
              "locale": null,
              "channel": null,
              "data": "4/b/0/1/0cb0c0e115dedde78b8d1ad8343ec980cd5daa54_image.jpg"
            }
          ],
          "description": [
            {
              "data": "Very well known French brand of modern and luxury furniture",
              "locale": "en_US",
              "channel": null
            },
            {
              "data": "La marque renommée des meubles de luxe à la française",
              "locale": "fr_FR",
              "channel": null
            }
          ],
          "country": [
            {
              "locale": null,
              "channel": null,
              "data": "france"
            }
          ],
          "creation_year": [
            {
              "locale": null,
              "channel": null,
              "data": "1860"
            }
          ]
        }
      },
      {
        "code": "usm",
        "values": {
          "label": [
            {
              "locale": "en_US",
              "channel": null,
              "data": "USM"
            }
          ],
          "image": [
            {
              "locale": null,
              "channel": null,
              "data": "9/c/g/1/0cb0c0e115dedba76f8d1ad8343ec897abc43bv4_image.jpg"
            }
          ],
          "description": [
            {
              "data": "Modular furniture from Switzerland for your home and office",
              "locale": "en_US",
              "channel": null
            },
            {
              "data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises",
              "locale": "fr_FR",
              "channel": null
            }
          ],
          "country": [
            {
              "locale": null,
              "channel": null,
              "data": "switzerland"
            }
          ],
          "creation_year": [
            {
              "locale": null,
              "channel": null,
              "data": "1885"
            }
          ]
        }
      }
    ]

RESPONSES

OK

Returns an JSON array in which each object gives you the status of each record creation or update

Body Format application/json

[
    {
        code (string ) • Resource code
        status_code (integer ) • HTTP status code, see Client errors to understand the meaning of each code
        message (string ) • Message explaining the error
    }
]

Example

[
      {
        "code": "kartell",
        "status_code": 204
      },
      {
        "code": "ligneroset",
        "status_code": 422,
        "message": "Property 'group' does not exist."
      },
      {
        "code": "usm",
        "status_code": 201
      }
    ]

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a record of a given reference entity  EE only

This endpoint allows you to get the information about a given record for a given reference entity.

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


REQUEST

get /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

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 product in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Code of the record

values (object ) : {
    attributeCode (array [object] ) : [
        {
            channel (string ) • Channel code of the reference entity record value
            locale (string ) • Locale code of the reference entity record value
            data (object ) • Reference entity record value. See the `data` format section for more details.
        }
    ]
  }

}

Example

{
      "code": "kartell",
      "values": {
        "label": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell"
          }
        ],
        "image": [
          {
            "locale": null,
            "channel": null,
            "data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
          }
        ],
        "country": [
          {
            "locale": null,
            "channel": null,
            "data": "italy"
          }
        ],
        "collection_overview": [
          {
            "locale": null,
            "channel": null,
            "data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
          }
        ],
        "creation_year": [
          {
            "locale": null,
            "channel": null,
            "data": "1949"
          }
        ]
      },
      "created": "2021-01-01T01:23:34+00:00",
      "updated": "2021-02-03T23:45:60+00:00"
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a record of a given reference entity  EE only

This endpoint allows you to update a given record of a given renference entity. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.

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


REQUEST

patch /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}

Path parameters

reference_entity_code (string) • Code of the reference entity

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

{

code (string ) • Code of the record

values (object { attributeCode : array [ object { channel : string , locale : string , data : object } ] } ) • Record attributes values, see Reference entity record values section for more details

}

Example

{
      "code": "kartell",
      "values": {
        "label": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell"
          }
        ],
        "image": [
          {
            "locale": null,
            "channel": null,
            "data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
          }
        ],
        "description": [
          {
            "locale": "en_US",
            "channel": null,
            "data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
          },
          {
            "locale": "fr_FR",
            "channel": null,
            "data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
          }
        ],
        "country": [
          {
            "locale": null,
            "channel": null,
            "data": "italy"
          }
        ],
        "collection_overview": [
          {
            "locale": null,
            "channel": null,
            "data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
          }
        ],
        "creation_year": [
          {
            "locale": null,
            "channel": null,
            "data": "1949"
          }
        ]
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Reference entity media file

Create a new media file for a reference entity or a record  EE only

This endpoint allows you to create a new media file and associate it to the image of a reference entity, or to the main image or to an attribute value of a record.

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


REQUEST

post /api/rest/v1/reference-entities-media-files

Path parameters

Ø

Query parameters

Ø

Headers

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

Content-type • Equal to 'multipart/form-data', no other value allowed

Body

Given as form-data

file (string / binary) • The binary of the media file


RESPONSES

Created

Means that the media file creation was successful

Headers

Location • URI of the created resource

Reference-entities-media-file-code • Code of the media file

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

The `Content-type` header has to be `multipart/form-data`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Download the media file associated to a reference entity or a record  EE only

This endpoint allows you to download a given media file that is associated with a reference entity or a record.

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


REQUEST

get /api/rest/v1/reference-entities-media-files/{code}

Path parameters

code (string) • Code of the resource

Query parameters

Ø

Headers

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

Body

Ø


RESPONSES

OK

Returns the binary of the media file

Body Format Mime-type of the media file
Media file binary

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."
    }

PAM - Deprecated

With the introduction of our new way to handle assets, the Asset Manager, the PAM feature will be removed from the v4.0 of the PIM. As a result, from now on, all the endpoints regarding the PAM assets are deprecated. They will not be available anymore starting from the v4.0.
To understand why, we recommend you to read this Medium post, we wrote on this special occasion.
Also, don't hesitate to take a look at the Asset Manager documentation to discover this new feature and how much more efficient it will be to handle your precious assets.

PAM asset - Deprecated

Get list of PAM assets  EE only deprecated

This endpoint allows you to get a list of PAM assets. PAM assets are paginated.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets

Path parameters

Ø

Query parameters

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

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

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Returns PAM assets 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) • PAM asset code
          categories (array [string ]) • Codes of the PAM asset categories in which the asset is classified
          description (string) • Description of the PAM asset
          localizable (boolean) • Whether the asset is localized or not, meaning if you want to have different reference files for each of your locale
          tags (array [string ]) • Tags of the PAM asset
          end_of_use (string) • Date on which the PAM asset expire
          variation_files (array [object ]) • Variations of the PAM asset
          reference_files (array [object ]) • Reference files of the PAM asset
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets?page=2&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets?page=1&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets?page=3&limit=3"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture"
              }
            },
            "code": "tshirt_artemis_main_picture",
            "categories": [
              "tshirts_assets"
            ],
            "description": "The main picture of the Artemis t-shirt",
            "localizable": false,
            "tags": [
              "tshirts",
              "red",
              "summer"
            ],
            "end_of_use": "2019-09-01T00:00:00+0200",
            "variation_files": [
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale"
                  }
                },
                "locale": null,
                "scope": "e_commerce",
                "code": "7/5/8/e/758e39d48va7b42a55001434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_ecommerce.jpg"
              },
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale"
                  }
                },
                "locale": null,
                "scope": "print",
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_print.jpg"
              }
            ],
            "reference_files": [
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale"
                  }
                },
                "locale": null,
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture.jpg"
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture"
              }
            },
            "code": "tshirt_artemis_profile_picture",
            "categories": [
              "tshirts_assets"
            ],
            "description": "The profile picture of the Artemis t-shirt",
            "localizable": false,
            "tags": [
              "tshirts",
              "red",
              "summer",
              "profile_views"
            ],
            "end_of_use": "2019-09-01T00:00:00+0200",
            "variation_files": [
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/variation-files/ecommerce/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/variation-files/ecommerce/no_locale"
                  }
                },
                "locale": null,
                "scope": "e_commerce",
                "code": "7/5/8/e/758e39d48va7b42a55001434fd3d7b6cf3189b7f_tshirt_artemis_profile_picture_ecommerce.jpg"
              },
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/variation-files/print/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/variation-files/print/no_locale"
                  }
                },
                "locale": null,
                "scope": "print",
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_profile_picture_print.jpg"
              }
            ],
            "reference_files": [
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/reference-files/no_locale/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_profile_picture/reference-files/no_locale"
                  }
                },
                "locale": null,
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_profile_picture.jpg"
              }
            ]
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_maintenance_manual"
              }
            },
            "code": "tshirt_artemis_maintenance_manual",
            "categories": [
              "tshirts_assets"
            ],
            "description": "The maintenance manual of the Artemis t-shirt",
            "localizable": true,
            "tags": [
              "tshirts",
              "manuals"
            ],
            "end_of_use": null,
            "variation_files": [],
            "reference_files": [
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_maintenance_manual/reference-files/en_US/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_maintenance_manual/reference-files/en_US"
                  }
                },
                "locale": "en_US",
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_maintenance_manual_en_US.pdf"
              },
              {
                "_link": {
                  "download": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_maintenance_manual/reference-files/fr_FR/download"
                  },
                  "self": {
                    "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_maintenance_manual/reference-files/fr_FR"
                  }
                },
                "locale": "fr_FR",
                "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_maintenance_manual_fr_FR.pdf"
              }
            ]
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new PAM asset  EE only deprecated

This endpoint allows you to create a new PAM asset.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

post /api/rest/v1/assets

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 ) • PAM asset code

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

description (string , null by default) • Description of the PAM asset

localizable (boolean , false by default) • Whether the asset is localized or not, meaning if you want to have different reference files for each of your locale

tags (array [string] , [] by default) • Tags of the PAM asset

end_of_use (string , null by default) • Date on which the PAM asset expire

}

Example

{
      "code": "tshirt_artemis_main_picture",
      "categories": [
        "tshirts_assets"
      ],
      "description": "The main picture of the Artemis t-shirt",
      "localizable": false,
      "tags": [
        "tshirts",
        "red",
        "summer"
      ],
      "end_of_use": "2019-09-01T00:00:00+0200"
    }

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 PAM assets  EE only deprecated

This endpoint allows you to update several PAM assets at once.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

patch /api/rest/v1/assets

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 PAM asset in JSON format

{

code (string ) • PAM asset code

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

description (string , null by default) • Description of the PAM asset

localizable (boolean , false by default) • Whether the asset is localized or not, meaning if you want to have different reference files for each of your locale

tags (array [string] , [] by default) • Tags of the PAM asset

end_of_use (string , null by default) • Date on which the PAM asset expire

variation_files (array [object] ) : [
        {
            _link (object ) • Links to get and download the variation file
            locale (string ) • Locale code of the variation
            scope (string ) • Channel code of the variation
            code (string ) • Code of the variation
        }
    ]

reference_files (array [object] ) : [
        {
            _link (object ) • Links to get and download the reference file
            locale (string ) • Locale code of the reference file
            code (string ) • Code of the reference file
        }
    ]

}

Example

{"code":"tshirt_aria_main_picture","categories":["tshirts_assets"],"tags":["tshirts", "red", "summer"]}
    {"code":"tshirt_artemis_maintenance_manual","categories":["tshirts_assets","short_sleeve"]}
    {"code":"tshirt_artemis_main_picture","tags":["tshirts", "red", "summer","short_sleeve"]}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"tshirt_aria_main_picture","status_code":201}
    {"line":2,"code":"tshirt_artemis_maintenance_manual","status_code":422,"message":"Category "short_sleeve" does not exist."}
    {"line":3,"code":"tshirt_artemis_main_picture","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a PAM asset  EE only deprecated

This endpoint allows you to get the information about a given PAM asset.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets/{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

OK

Returns the content of the PAM asset in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • PAM asset code

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

description (string ) • Description of the PAM asset

localizable (boolean ) • Whether the asset is localized or not, meaning if you want to have different reference files for each of your locale

tags (array [string] ) • Tags of the PAM asset

end_of_use (string ) • Date on which the PAM asset expire

variation_files (array [object] ) : [
        {
          _link (object) • Links to get and download the variation file
          locale (string) • Locale code of the variation
          scope (string) • Channel code of the variation
          code (string) • Code of the variation
        }
    ]

reference_files (array [object] ) : [
        {
          _link (object) • Links to get and download the reference file
          locale (string) • Locale code of the reference file
          code (string) • Code of the reference file
        }
    ]

}

Example

{
      "code": "tshirt_artemis_main_picture",
      "categories": [
        "tshirts_assets"
      ],
      "description": "The main picture of the Artemis t-shirt",
      "localizable": false,
      "tags": [
        "tshirts",
        "red",
        "summer"
      ],
      "end_of_use": "2019-09-01T00:00:00+0200",
      "variation_files": [
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale"
            }
          },
          "locale": null,
          "scope": "e_commerce",
          "code": "7/5/8/e/758e39d48va7b42a55001434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_ecommerce.jpg"
        },
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale"
            }
          },
          "locale": null,
          "scope": "print",
          "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_print.jpg"
        }
      ],
      "reference_files": [
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale"
            }
          },
          "locale": null,
          "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture.jpg"
        }
      ]
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Resource not found

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Update/create a PAM asset  EE only deprecated

This endpoint allows you to update a given PAM asset. Know more about Update behavior. Note that if no asset exists for the given code, it creates it.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

patch /api/rest/v1/assets/{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

{

code (string ) • PAM asset code

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

description (string , null by default) • Description of the PAM asset

localizable (boolean , false by default) • Whether the asset is localized or not, meaning if you want to have different reference files for each of your locale

tags (array [string] , [] by default) • Tags of the PAM asset

end_of_use (string , null by default) • Date on which the PAM asset expire

variation_files (array [object] ) : [
        {
            _link (object ) • Links to get and download the variation file
            locale (string ) • Locale code of the variation
            scope (string ) • Channel code of the variation
            code (string ) • Code of the variation
        }
    ]

reference_files (array [object] ) : [
        {
            _link (object ) • Links to get and download the reference file
            locale (string ) • Locale code of the reference file
            code (string ) • Code of the reference file
        }
    ]

}

Example

{
      "code": "tshirt_artemis_main_picture",
      "categories": [
        "tshirts_assets"
      ],
      "description": "The main picture of the Artemis t-shirt",
      "localizable": false,
      "tags": [
        "tshirts",
        "red",
        "summer"
      ],
      "end_of_use": "2019-09-01T00:00:00+0200",
      "variation_files": [
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale"
            }
          },
          "locale": null,
          "scope": "e_commerce",
          "code": "7/5/8/e/758e39d48va7b42a55001434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_ecommerce.jpg"
        },
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/print/no_locale"
            }
          },
          "locale": null,
          "scope": "print",
          "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_print.jpg"
        }
      ],
      "reference_files": [
        {
          "_link": {
            "download": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale/download"
            },
            "self": {
              "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale"
            }
          },
          "locale": null,
          "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture.jpg"
        }
      ]
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

PAM asset reference file - Deprecated

Get a reference file  EE only deprecated

This endpoint allows you to get the information about a reference file of a given PAM asset.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets/{asset_code}/reference-files/{locale_code}

Path parameters

asset_code (string) • Code of the asset

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

Query parameters

Ø

Headers

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

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

Body

Ø


RESPONSES

OK

Returns the content of the reference file in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Code of the PAM asset reference file

locale (string ) • Locale of the PAM asset reference file, equal to `null` if the asset is not localizable

_link (object ) : {
    download (object ) : {
        href (string ) • URI to download the reference file
    }
  }

}

Example

{
      "code": "7/5/8/e/759e39d48va7b42a55002434fd3d7b6cf3189b7f_tshirt_artemis_main_picture.jpg",
      "locale": null,
      "_link": {
        "download": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/reference-files/no_locale/download"
        }
      }
    }

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."
    }

Upload a new reference file  EE only deprecated

This endpoint allows you to upload a new reference file for a given PAM asset and locale. It will also automatically generate all the variation files corresponding to this reference file.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

post /api/rest/v1/assets/{asset_code}/reference-files/{locale_code}

Path parameters

asset_code (string) • Code of the asset

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

Query parameters

Ø

Headers

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

Content-type • Equal to 'multipart/form-data', no other value allowed

Body

Given as form-data

file (string / binary) • The binaries of the file


RESPONSES

Uploaded

Means that the reference file upload was successful. Beware that even if the reference file upload is complete, some variation files generations could have failed. If so, you will see a warning message in the response body.

Headers

Location • URI of the created resource

Body Format application/json

{

message (string ) • Message explaining the warning

errors (array [object] ) : [
        {
          channel (string) • Channel for which the variation file generation failed
          locale (string) • Locale for which the variation file generation failed
          message (string) • Message explaining why the variation file generation failed
        }
    ]

}

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."
    }

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."
    }

Unsupported Media type

The `Content-type` header has to be `multipart/form-data`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Download a reference file  EE only deprecated

This endpoint allows you to download a given reference file.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets/{asset_code}/reference-files/{locale_code}/download

Path parameters

asset_code (string) • Code of the asset

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

Query parameters

Ø

Headers

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

Body

Ø


RESPONSES

OK

Returns the binary of the reference file

Body Format Mime-type of the reference file
Media file binary

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."
    }

PAM asset variation file - Deprecated

Get a variation file  EE only deprecated

This endpoint allows you to get the information about a variation file of a given PAM asset.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets/{asset_code}/variation-files/{channel_code}/{locale_code}

Path parameters

asset_code (string) • Code of the asset

channel_code (string) • Code of the channel

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

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 variation file in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Code of the PAM asset variation file

locale (string ) • Locale of the PAM asset variation file, equal to `null` if the asset is not localizable

scope (string ) • Channel of the PAM asset variation file

_link (object ) : {
    download (object ) : {
        href (string ) • URI to download the variation file
    }
  }

}

Example

{
      "code": "7/5/8/e/758e39d48va7b42a55001434fd3d7b6cf3189b7f_tshirt_artemis_main_picture_ecommerce.jpg",
      "locale": null,
      "scope": "ecommerce",
      "_link": {
        "download": {
          "href": "https://demo.akeneo.com/api/rest/v1/assets/tshirt_artemis_main_picture/variation-files/ecommerce/no_locale/download"
        }
      }
    }

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."
    }

Upload a new variation file  EE only deprecated

This endpoint allows you to upload a new variation file for a given PAM asset, channel and locale.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

post /api/rest/v1/assets/{asset_code}/variation-files/{channel_code}/{locale_code}

Path parameters

asset_code (string) • Code of the asset

channel_code (string) • Code of the channel

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

Query parameters

Ø

Headers

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

Content-type • Equal to 'multipart/form-data', no other value allowed

Body

Given as form-data

file (string / binary) • The binaries of the file


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."
    }

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."
    }

Unsupported Media type

The `Content-type` header has to be `multipart/form-data`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Download a variation file  EE only deprecated

This endpoint allows you to download a given variation file.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/assets/{asset_code}/variation-files/{channel_code}/{locale_code}/download

Path parameters

asset_code (string) • Code of the asset

channel_code (string) • Code of the channel

locale_code (string) • Code of the locale if the asset is localizable or equal to `no-locale` if the asset is not localizable

Query parameters

Ø

Headers

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

Body

Ø


RESPONSES

OK

Returns the binary of the variation file

Body Format Mime-type of the variation file
Media file binary

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."
    }

PAM asset category - Deprecated

Get list of PAM asset categories  EE only deprecated

This endpoint allows you to get a list of PAM asset categories. PAM asset categories are paginated and sorted by `root/left`.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/asset-categories

Path parameters

Ø

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Returns PAM asset categories paginated

Body Format application/json

Follow the standard format of the entity

{

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

current_page (integer) • Current page number

_embedded (object) : {
    items (array ) : [
        {
          _links (object) : {
              self (object) : {
                  href (string ) • URI of the resource
              }
          }
          code (string) • PAM asset category code
          parent (string) • PAM ssset category code of the parent's asset category
          labels (object) : {
              localeCode (string) • PAM asset category label for the locale `localeCode`
          }
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-categories?page=2&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-categories?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-categories?page=1&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-categories?page=3&limit=3"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-categories/pictures"
              }
            },
            "code": "pictures",
            "parent": null,
            "labels": {
              "en_US": "Pictures",
              "fr_FR": "Images",
              "de_DE": "Bilder"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-categories/front_views"
              }
            },
            "code": "front_views",
            "parent": "pictures",
            "labels": {
              "en_US": "Front views",
              "fr_FR": "Vues de face",
              "de_DE": "Vorderansichten"
            }
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-categories/side_views"
              }
            },
            "code": "side_views",
            "parent": "pictures",
            "labels": {
              "en_US": "Side views",
              "fr_FR": "Vues de profil",
              "de_DE": "Profilansichten"
            }
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Create a new PAM asset category  EE only deprecated

This endpoint allows you to create a new PAM asset category.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

post /api/rest/v1/asset-categories

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

Follow the standard format of the entity

{

code (string ) • PAM asset category code

parent (string , null by default) • PAM ssset category code of the parent's asset category

labels (object { localeCode : string } , [] by default) • PAM asset category labels for each locale

}

Example

{
      "code": "front_views",
      "parent": "pictures",
      "labels": {
        "en_US": "Front views",
        "fr_FR": "Vues de face"
      }
    }

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 PAM asset categories  EE only deprecated

This endpoint allows you to update several PAM asset categories at once.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

patch /api/rest/v1/asset-categories

Path parameters

Ø

Query parameters

Ø

Headers

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

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

Body

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

{

code (string ) • PAM asset category code

parent (string , null by default) • PAM ssset category code of the parent's asset category

labels (object { localeCode : string } , [] by default) • PAM asset category labels for each locale

}

Example

{"code":"pictures","parent":null}
    {"code":"front_views","parent":"pitures"}
    {"code":"other_views","parent":"pictures"}

RESPONSES

OK

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

Body Format application/json

{

line (integer ) • Line number

identifier (string ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is not a product

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

message (string ) • Message explaining the error

}

Example

{"line":1,"code":"spring_collection","status_code":201}
    {"line":2,"code":"front_views","status_code":422,"message":"Asset category "pitures" does not exist."}
    {"line":3,"code":"other_views","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Request Entity Too Large

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a PAM asset category  EE only deprecated

This endpoint allows you to get the information about a given PAM asset category.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/asset-categories/{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

OK

Returns the content of the asset category in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • PAM asset category code

parent (string ) • PAM ssset category code of the parent's asset category

labels (object ) : {
    localeCode (string ) • PAM asset category label for the locale `localeCode`
  }

}

Example

{
      "code": "front_views",
      "parent": "pictures",
      "labels": {
        "en_US": "Front views",
        "fr_FR": "Vues de face"
      }
    }

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 PAM asset category  EE only deprecated

This endpoint allows you to update a given PAM asset category. Know more about Update behavior. Note that if no category exists for the given code, it creates it.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

patch /api/rest/v1/asset-categories/{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

{

code (string ) • PAM asset category code

parent (string , null by default) • PAM ssset category code of the parent's asset category

labels (object { localeCode : string } , [] by default) • PAM asset category labels for each locale

}

Example

{
      "code": "front_views",
      "parent": "pictures",
      "labels": {
        "en_US": "Front views",
        "fr_FR": "Vues de face"
      }
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unprocessable entity

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

PAM asset tag - Deprecated

Get list of PAM asset tags  EE only deprecated

This endpoint allows you to get a list of PAM asset tags. PAM asset tags are paginated.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/asset-tags

Path parameters

Ø

Query parameters

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

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

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

Headers

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

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

Body

Ø


RESPONSES

Returns PAM asset tags 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) • PAM asset tag code
        }
    ]
  }

}

Example

{
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-tags?page=2&limit=3"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-tags?page=1&limit=3"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-tags?page=1&limit=3"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/asset-tags?page=3&limit=3"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-tags/tshirt"
              }
            },
            "code": "tshirt"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-tags/belt"
              }
            },
            "code": "belt"
          },
          {
            "_links": {
              "self": {
                "href": "https://demo.akeneo.com/api/rest/v1/asset-tags/red"
              }
            },
            "code": "red"
          }
        ]
      }
    }

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Not Acceptable

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Get a PAM asset tag  EE only deprecated

This endpoint allows you to get the information about a given PAM asset tag.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

get /api/rest/v1/asset-tags/{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

OK

Returns the content of the asset tag in JSON format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • PAM asset tag code

}

Example

{
      "code": "tshirt"
    }

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 PAM asset tag  EE only deprecated

This endpoint allows you to update a given PAM asset tag. Know more about Update behavior. Note that if no tag exists for the given code, it creates it.

Available in PIM versions: 2.1 2.2 2.3 3.x


REQUEST

patch /api/rest/v1/asset-tags/{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

{

code (string ) • PAM asset tag code

}

Example

{
      "code": "tshirt"
    }

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Access forbidden

The user does not have the permission to execute this request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

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

Unsupported Media type

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

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/json’ is allowed."
    }

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 422,
      "message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
      "_links": {
        "documentation": {
          "href": "http://api.akeneo.com/api-reference.html"
        }
      }
    }

Utilities

Overview

Get list of all endpoints

This endpoint allows you to get the list of all the available endpoints. No need to be authenticated to use this endpoint.

Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS


REQUEST

get /api/rest/v1

Path parameters

Ø

Query parameters

Ø

Headers

Accept • Equal to 'application/json', no other value allowed

Body

Ø


RESPONSES

Return the list of all available endpoints

Body Format application/json

{

host (string ) • Host name

authentication (object ) • Endpoint to get the authentication token

routes (object ) • All the availables endpoints

}

Example

{
      "host": "https://demo.akeneo.com",
      "authentication": {
        "fos_oauth_server_token": {
          "route": "/api/oauth/v1/token",
          "methods": [
            "POST"
          ]
        }
      },
      "routes": {
        "pim_api_category_list": {
          "route": "/api/rest/v1/categories",
          "methods": [
            "GET"
          ]
        },
        "pim_api_category_get": {
          "route": "/api/rest/v1/categories/{code}",
          "methods": [
            "GET"
          ]
        },
        "pim_api_category_create": {
          "route": "/api/rest/v1/categories",
          "methods": [
            "POST"
          ]
        },
        "pim_api_category_partial_update": {
          "route": "/api/rest/v1/categories/{code}",
          "methods": [
            "PATCH"
          ]
        }
      }
    }

Not Acceptable

The `Accept` header is not `application/json` but it should

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 406,
      "message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
    }

Authentication

Get authentication token

This endpoint allows you to get an authentication token. No need to be authenticated to use this endpoint.

Available in PIM versions: 1.7 2.x 3.x 4.0 5.0 6.0 7.0 SaaS


REQUEST

post /api/oauth/v1/token

Path parameters

Ø

Query parameters

Ø

Headers

Content-type • Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed

Authorization • Equal to 'Basic xx', where 'xx' is the base 64 encoding of the client id and secret. Find out how to generate them in the Client ID/secret generation section.

Body

Given as form-data

username (string ) • Your PIM username

password (string ) • Your PIM password

grant_type (string ) • Always equal to "password"


RESPONSES

Return an authentication token

Body Format application/json

{

access_token (string ) • Authentication token that should be given in every authenticated request to the API

expires_in (integer ) • Validity of the token given in seconds, 3600s = 1h by default

token_type (string ) • Token type, always equal to "bearer"

scope (string ) • Unused, always equal to "null"

refresh_token (string ) • Use this token when your access token has expired. See Refresh an expired token section for more details.

}

Example

{
      "access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
      "expires_in": 3600,
      "token_type": "bearer",
      "scope": null,
      "refresh_token": "M2FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
    }

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 400,
      "message": "Invalid JSON message received"
    }

Unsupported Media type

The `Content-type` header has to be `application/json`

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/json’ is allowed."
    }

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
      "code": 422,
      "message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
      "_links": {
        "documentation": {
          "href": "http://api.akeneo.com/api-reference.html"
        }
      }
    }