API reference

Complete reference on how to handle Akeneo PIM resources

Product entities

Products

Get list of products

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

Available in PIM versions: 1.7 2.0 2.1


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 on product values 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 on product values 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 products 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 enable
          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 in 2.x)
          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
              }
          }
          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 (only available in the v2.x Enterprise Edition)
          }
        }
    ]
}

}

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"
            }
          ]
        },
        "created": "2016-06-23T18:24:44+02:00",
        "updated": "2016-06-25T17:56:12+02:00",
        "associations": {
          "PACK": {
            "products": [
              "sunglasses"
            ],
            "groups": []
          }
        }
      },
      {
        "_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"
            ],
            "groups": []
          }
        }
      },
      {
        "_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": {}
      }
    ]
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new product

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

Available in PIM versions: 1.7 2.0 2.1


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 enable

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 in 2.x)

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] } } ) • Several associations related to groups 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"
      }
    ],
    "size": [
      {
        "locale": null,
        "scope": null,
        "data": "m"
      }
    ]
  },
  "associations": {
    "PACK": {
      "products": [
        "sunglass"
      ],
      "groups": []
    }
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several products

This endpoint allows you to update and/or create several products at once. Know more about Update behavior. Note that if no product exists for the given identifier, it creates it. If you are using a v2.0 Enterprise Edition PIM, 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.0 2.1


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 enable

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 in 2.x)

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] } } ) • Several associations related to groups 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 in the v2.x 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 a category, a family or an attribute

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a product

This endpoint allows you to get the information about a given product. If you are using a v2.0 Enterprise Edition PIM, permissions based on your user groups are applied to the product you request.

Available in PIM versions: 1.7 2.0 2.1


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 enable

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 in 2.x)

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

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 (only available in the v2.x 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"
      }
    ],
    "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"
      ],
      "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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create a product

This endpoint allows you to update a given product. Know more about Update behavior. Note that if no product exists for the given identifier, it creates it. If you are using a v2.0 Enterprise Edition PIM, 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.0 2.1


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 enable

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 in 2.x)

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] } } ) • Several associations related to groups 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 in the v2.x 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"
      }
    ],
    "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"
      ],
      "groups": []
    }
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Delete a product

This endpoint allows you to delete a given product. If you are using a v2.0 Enterprise Edition PIM, permissions based on your user groups are applied to the product you try to delete.

Available in PIM versions: 1.7 2.0 2.1


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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Submit a draft for approval  EE only

This endpoint allows you to submit a draft for approval.

Available in PIM versions: 2.0 2.1


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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a draft  EE only

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

Available in PIM versions: 2.0 2.1


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 enable

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 in 2.x)

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

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 (only available in the v2.x 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"
      }
    ],
    "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"
      ],
      "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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Product models

Get list of product models

This endpoint allows you to get a list of product models. Product models are paginated.

Available in PIM versions: 2.0 2.1


REQUEST

get /api/rest/v1/product-models

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 products 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
          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
                   }
              ]
          }
          created (string) • Date of creation
          updated (string) • Date of the last update
        }
    ]
}

}

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/shoes"
          }
        },
        "code": "shoes",
        "family_variant": "familyVariantA1",
        "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!"
            }
          ]
        },
        "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/tshirt"
          }
        },
        "code": "tshirt",
        "family_variant": "familyVariantA1",
        "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!"
            }
          ]
        },
        "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/trousers"
          }
        },
        "code": "trousers",
        "family_variant": "familyVariantA1",
        "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!"
            }
          ]
        },
        "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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new product model

This endpoint allows you to create a new product model.

Available in PIM versions: 2.0 2.1


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

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

}

Example

{
  "code": "model-biker-jacket-leather",
  "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"
      }
    ]
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several product models

This endpoint allows you to update and/or create several product models at once. Know more about Update behavior. Note that if no product models exists for the given code, it creates it.

Available in PIM versions: 2.0 2.1


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

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

created (string ) • Date of creation

updated (string ) • Date of the last update

}

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 a category, a family or an attribute

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a product model

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

Available in PIM versions: 2.0 2.1


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

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

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{
  "code": "model-biker-jacket-leather",
  "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"
      }
    ]
  },
  "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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create a product model

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

Available in PIM versions: 2.0 2.1


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

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

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{
  "code": "model-biker-jacket-leather",
  "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"
      }
    ]
  },
  "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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Published products

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


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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a published product  EE only

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

Available in PIM versions: 2.0 2.1


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

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Catalog modeling entities

Categories

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


REQUEST

get /api/rest/v1/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 products 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
          labels (object) : {
              localeCode (string) • Category label for the locale `localeCode`
          }
        }
    ]
}

}

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,
        "labels": {
          "en_US": "Winter collection",
          "fr_FR": "Collection hiver",
          "de_DE": "Winter-Kollektion"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/woman"
          }
        },
        "code": "woman",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Woman",
          "fr_FR": "Femme",
          "de_DE": "Damen"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/man"
          }
        },
        "code": "man",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Man",
          "fr_FR": "Homme",
          "de_DE": "Herren"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/kids"
          }
        },
        "code": "kids",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Kids",
          "fr_FR": "Enfant",
          "de_DE": "Kinder"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/summer_collection"
          }
        },
        "code": "summer_collection",
        "parent": null,
        "labels": {
          "en_US": "Summer collection",
          "fr_FR": "Collection été",
          "de_DE": "Sommer-Kollektion"
        }
      }
    ]
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new category

This endpoint allows you to create a new category.

Available in PIM versions: 1.7 2.0 2.1


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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several categories

This endpoint allows you to update several categories at once.

Available in PIM versions: 1.7 2.0 2.1


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

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 a category, a family or an attribute

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a category

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

Available in PIM versions: 1.7 2.0 2.1


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

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

}

Example

{
  "code": "winter_collection",
  "parent": null,
  "labels": {
    "en_US": "Winter collection",
    "fr_FR": "Collection hiver"
  }
}

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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


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

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

Ø

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Families

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


REQUEST

get /api/rest/v1/families

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 products 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
          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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new family

This endpoint allows you to create a new family.

Available in PIM versions: 1.7 2.0 2.1


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

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several families

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

Available in PIM versions: 1.7 2.0 2.1


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

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 a category, a family or an attribute

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a family

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

Available in PIM versions: 1.7 2.0 2.1


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

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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


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

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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


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 products 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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new family variant

This endpoint allows you to create a family variant.

Available in PIM versions: 2.0 2.1


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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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


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 a category, a family or an attribute

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

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a family variant

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

Available in PIM versions: 2.0 2.1


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