Skip to content

Instantly share code, notes, and snippets.

@codingforfun

codingforfun/akeneo-web-api.json

Last active September 8, 2023 01:19
Show Gist options
  • Save codingforfun/efae264dff6151e90ba6795e53dda3c0 to your computer and use it in GitHub Desktop.
Save codingforfun/efae264dff6151e90ba6795e53dda3c0 to your computer and use it in GitHub Desktop.
Download ZIP
Modified Akeneo Swagger Definition
Raw
akeneo-web-api.json
This file has been truncated, but you can view the full file.
{
"swagger": "2.0",
"info": {
"title": "Akeneo PIM REST API",
"version": "1.0.0"
},
"host": "demo.akeneo.com",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"securityDefinitions": {
"bearer": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"description": "You need to prefix the value with `ApiKey` to indicate the custom authorization type"
},
"request_token": {
"type": "basic",
"description": "Use the client_id as the username, and the secret as the password."
}
},
"security": [
{
"bearer": []
}
],
"paths": {
"/api/rest/v1/products": {
"get": {
"summary": "Get list of products",
"operationId": "get_products",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.",
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter products, for more details see the <a href=\"/documentation/filter.html\">Filters</a> section",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi"
},
{
"name": "scope",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-channel\">Filter product values via channel</a> section",
"required": false
},
{
"name": "locales",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-locale\">Filter product values via locale</a> section",
"required": false
},
{
"name": "attributes",
"in": "query",
"type": "string",
"description": "Filter product values to only return those concerning the given attributes, for more details see the <a href=\"/documentation/filter.html#filter-product-values\">Filter on product values</a> section",
"required": false
},
{
"name": "pagination_type",
"in": "query",
"description": "Pagination method type, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "page",
"x-validation-rules": "One of the following values",
"enum": [
"page",
"search_after"
]
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "search_after",
"in": "query",
"description": "Cursor when using the `search_after` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "cursor to the first page"
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
},
{
"name": "with_attribute_options",
"in": "query",
"description": "Return labels of attribute options in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product quality scores in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_completenesses",
"in": "query",
"description": "Return product completenesses in the response. (Only available since the 6.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "Return products paginated",
"schema": {
"title": "Products",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"type": "object",
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
]
}
}
}
}
}
}
]
},
"x-examples-per-version": [
{
"x-version": "1.7",
"x-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": [],
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
]
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
]
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/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": []
}
},
"quantified_associations": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/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": {},
"quantified_associations": {}
}
]
}
}
},
{
"x-version": "2.0",
"x-example": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
]
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
]
}
}
},
{
"_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": []
}
},
"quantified_associations": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {}
}
]
}
}
},
{
"x-version": "2.1",
"x-example": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
]
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/cap"
}
},
"identifier": "cap",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {}
}
]
}
}
},
{
"x-version": "5.0",
"x-example": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_quality_scores=true&with_attribute_options=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_quality_scores=true&with_attribute_options=true"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/cap"
}
},
"identifier": "cap",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": {}
}
]
}
}
},
{
"x-version": "SaaS",
"x-example": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/top"
}
},
"uuid": "aaf518b2-f91e-40f1-a53a-78ce5e81a6f9",
"identifier": "top",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"identifier": "cap",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": {},
"completenesses": []
}
]
}
}
}
]
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"post": {
"summary": "Create a new product",
"operationId": "post_products",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to create a new product. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to create.",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several products",
"operationId": "patch_products",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several products at once. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product exists for the given identifier, it creates it. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.",
"x-body-by-line": "Contains several lines, each line is a product in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"identifier\":\"cap\",\"values\":{\"description\":[{\"scope\":\"ecommerce\",\"locale\":\"en_US\",\"data\":\"My amazing cap\"}]}}",
"x-example-2": "{\"identifier\":\"mug\",\"group\":[\"promotion\"]}",
"x-example-3": "{\"identifier\":\"tshirt\",\"family\":\"clothes\"}"
},
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"identifier\":\"cap\",\"status_code\":204}",
"x-example-2": "{\"line\":2,\"identifier\":\"mug\",\"status_code\":422,\"message\":\"Property \"group\" does not exist.\"}",
"x-example-3": "{\"line\":3,\"identifier\":\"tshirt\",\"status_code\":201}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/products/{code}": {
"get": {
"summary": "Get a product",
"operationId": "get_products__code_",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get the information about a given product. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product you request.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "with_attribute_options",
"in": "query",
"description": "Return labels of attribute options in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product quality scores in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_completenesses",
"in": "query",
"description": "Return product completenesses in the response. (Only available since the 6.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the product in JSON standard format",
"schema": {
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create a product",
"operationId": "patch_products__code_",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given product. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product exists for the given identifier, it creates it. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}
}
}
},
"delete": {
"summary": "Delete a product",
"operationId": "delete_products__code_",
"tags": [
"Product [identifier]"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to delete a given product. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the product you try to delete.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"204": {
"description": "No content to return",
"x-details": "Means that the deletion was successful"
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
}
}
}
},
"/api/rest/v1/products/{code}/proposal": {
"post": {
"summary": "Submit a draft for approval",
"operationId": "post_proposal",
"tags": [
"Product [identifier]"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to submit a draft for approval.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"201": {
"description": "Submitted",
"x-details": "Means that the draft submission was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/products/{code}/draft": {
"get": {
"summary": "Get a draft",
"operationId": "get_draft__code_",
"tags": [
"Product [identifier]"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to get the information about a given draft.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the draft in JSON standard format",
"schema": {
"type": "object",
"required": [
"identifier"
],
"properties": {
"uuid": {
"type": "string",
"description": "Product UUID",
"x-from-version": "7.0"
},
"identifier": {
"type": "string",
"description": "Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
}
},
"/api/rest/v1/products-uuid": {
"get": {
"summary": "Get list of products",
"operationId": "get_products_uuid",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get a list of products. Products are paginated and they can be filtered. In the Enterprise Edition, permissions based on your user groups are applied to the set of products you request.",
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter products, for more details see the <a href=\"/documentation/filter.html\">Filters</a> section",
"required": false,
"type": "string"
},
{
"name": "scope",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-channel\">Filter product values via channel</a> section",
"required": false
},
{
"name": "locales",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-locale\">Filter product values via locale</a> section",
"required": false
},
{
"name": "attributes",
"in": "query",
"type": "string",
"description": "Filter product values to only return those concerning the given attributes, for more details see the <a href=\"/documentation/filter.html#filter-product-values\">Filter on product values</a> section",
"required": false
},
{
"name": "pagination_type",
"in": "query",
"description": "Pagination method type, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "page",
"x-validation-rules": "One of the following values",
"enum": [
"page",
"search_after"
]
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "search_after",
"in": "query",
"description": "Cursor when using the `search_after` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "cursor to the first page"
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
},
{
"name": "with_attribute_options",
"in": "query",
"description": "Return labels of attribute options in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product quality scores in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_completenesses",
"in": "query",
"description": "Return product completenesses in the response. (Only available since the 6.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "Return products paginated",
"schema": {
"title": "Products",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
]
}
}
}
}
}
}
]
},
"x-examples-per-version": [
{
"x-version": "SaaS",
"x-example": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-uuid/25566245-55c3-42ce-86d9-8610ac459fa8"
}
},
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"family": "tshirt",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product/fc24e6c3-933c-4a93-8a81-e5c703d134d5"
}
},
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "cap",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-uuid/fa0b115e-46ec-4527-beab-7207452f1b47"
}
},
"uuid": "fa0b115e-46ec-4527-beab-7207452f1b47",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "sweat",
"locale": null,
"scope": null
}
]
},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": {},
"completenesses": []
}
]
}
}
}
]
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"post": {
"summary": "Create a new product",
"operationId": "post_products_uuid",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to create a new product. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to create. If no uuid is provided, the PIM will generate one for you.",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several products",
"operationId": "patch_products_uuid",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several products at once. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product exists for the given uuid, it creates it. In the Enterprise Edition, permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.",
"x-body-by-line": "Contains several lines, each line is a product in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"required": [
"uuid"
],
"x-examples": {
"x-example-1": "{\"uuid\":\"fc24e6c3-933c-4a93-8a81-e5c703d134d5\",\"values\":{\"description\":[{\"scope\":\"ecommerce\",\"locale\":\"en_US\",\"data\":\"My amazing cap\"}]}}",
"x-example-2": "{\"uuid\":\"573dd613-0c7f-4143-83d5-63cc5e535966\",\"values\":{\"sku\":[{\"data\":\"updated_sku\",\"locale\":null,\"scope\":null}]}, \"group\":[\"promotion\"]}",
"x-example-3": "{\"uuid\":\"25566245-55c3-42ce-86d9-8610ac459fa8\",\"values\":{\"sku\":[{\"data\":\"new_product\",\"locale\":null,\"scope\":null}]},\"family\":\"clothes\"}"
},
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"uuid": {
"type": "string",
"description": "Product uuid"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"uuid\":\"fc24e6c3-933c-4a93-8a81-e5c703d134d5\",\"status_code\":204}",
"x-example-2": "{\"line\":2,\"uuid\":\"573dd613-0c7f-4143-83d5-63cc5e535966\",\"status_code\":422,\"message\":\"Property \"group\" does not exist.\"}",
"x-example-3": "{\"line\":3,\"uuid\":\"25566245-55c3-42ce-86d9-8610ac459fa8\",\"status_code\":201}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/products-uuid/{uuid}": {
"get": {
"summary": "Get a product",
"operationId": "get_products_uuid__uuid_",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get the information about a given product. In the Entreprise Edition, permissions based on your user groups are applied to the product you request.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Uuid of the resource",
"required": true,
"type": "string"
},
{
"name": "with_attribute_options",
"in": "query",
"description": "Return labels of attribute options in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product quality scores in the response. (Only available since the 5.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "5.0"
},
{
"name": "with_completenesses",
"in": "query",
"description": "Return product completenesses in the response. (Only available since the 6.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the product in JSON standard format",
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create a product",
"operationId": "patch_products_uuid__uuid_",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given product. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product exists for the given uuid, it creates it. In the Entreprise Edition, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Uuid of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}
}
}
},
"delete": {
"summary": "Delete a product",
"operationId": "delete_products_uuid__uuid_",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"description": "This endpoint allows you to delete a given product. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to delete.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Uuid of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"204": {
"description": "No content to return",
"x-details": "Means that the deletion was successful"
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
}
}
}
},
"/api/rest/v1/products-uuid/{uuid}/proposal": {
"post": {
"summary": "Submit a draft for approval",
"operationId": "post_proposal_uuid",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to submit a draft for approval.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Uuid of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"201": {
"description": "Submitted",
"x-details": "Means that the draft submission was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/products-uuid/{uuid}/draft": {
"get": {
"summary": "Get a draft",
"operationId": "get_draft_uuid__uuid_",
"tags": [
"Product [uuid]"
],
"x-versions": [
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to get the information about a given draft.",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Uuid of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the draft in JSON standard format",
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Product uuid"
},
"enabled": {
"type": "boolean",
"description": "Whether the product is enabled",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements.",
"x-validation-rules": "It is equal to an existing family code. In the case of variant product, the given family should be the same as the product model family.",
"default": "null only in the case of a non variant product"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a> when the product is a variant (only available since the 2.0). This parent can be modified since the 2.3.",
"x-validation-rules": "It is equal to an existing product model code only if the product is variant otherwise it's equal to null",
"default": "null",
"x-from-version": "2.0"
},
"values": {
"type": "object",
"description": "Product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "Product value. See <a href='/concepts/products.html#the-data-format'>the `data` format</a> section for more details."
},
"linked_data": {
"type": "object",
"x-read-only": true,
"description": "Object containing labels of attribute options (only available since the 5.0 and when query parameter \"with_attribute_options\" is set to \"true\"). See <a href='/concepts/products.html#the-linked_data-format'>the `linked_data` format</a> section for more details.",
"x-from-version": "5.0",
"properties": {
"attribute": {
"type": "string"
},
"code": {
"type": "string"
},
"labels": {
"type": "object"
}
}
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product models and/or other products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the uuid of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product uuids with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the uuid of an existing product and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product uuids and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product (only available since the v2.0 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.0",
"properties": {
"workflow_status": {
"description": "Status of the product regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product quality scores for each channel/locale combination (only available since the 5.0 and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "5.0"
},
"completenesses": {
"type": "array",
"description": "Product completenesses for each channel/locale combination (only available since the 7.0 version, and when the \"with_completenesses\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string"
},
"locale": {
"type": "string"
},
"data": {
"type": "integer"
}
}
}
}
},
"example": {
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
}
},
"/api/rest/v1/product-models": {
"get": {
"summary": "Get list of product models",
"operationId": "get_product_models",
"tags": [
"Product model"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get a list of product models. Product models are paginated. In the Enterprise Edition, since the 2.0, permissions based on your user groups are applied to the set of products you request.",
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter product models, for more details see the <a href=\"/documentation/filter.html\">Filters</a> section",
"required": false,
"type": "string"
},
{
"name": "scope",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-channel\">Filter product values via channel</a> section",
"required": false
},
{
"name": "locales",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#via-locale\">Filter product values via locale</a> section",
"required": false
},
{
"name": "attributes",
"in": "query",
"type": "string",
"description": "Filter product values to only return those concerning the given attributes, for more details see the <a href=\"/documentation/filter.html#filter-product-values\">Filter on product values</a> section and the <a href=\"/documentation/filter.html#filter-on-product-model-properties\">Filter on product model properties</a> section",
"required": false
},
{
"name": "pagination_type",
"in": "query",
"description": "Pagination method type, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "page",
"x-validation-rules": "One of the following values",
"enum": [
"page",
"search_after"
]
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "search_after",
"in": "query",
"description": "Cursor when using the `search_after` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "cursor to the first page"
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product model quality scores in the response. <strong>(Only available since the 6.0 version)</strong>",
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "Return product models paginated",
"schema": {
"title": "Product Models",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=qg%3D%3D"
},
"first": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3"
},
"next": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models?pagination_type=search_after&limit=3&search_after=rw%3D%3D"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/amarisshoe"
}
},
"code": "amarisshoe",
"family": "shoes",
"family_variant": "shoes_VariantA1",
"parent": null,
"categories": [
"clothing",
"shoes"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like shoes!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/Abiloitshirt"
}
},
"code": "Abiloitshirt",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"parent": null,
"categories": [
"clothing",
"tshirt"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like tshirt!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
}
],
"product_models": []
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/product-models/Astertrousers"
}
},
"code": "Astertrousers",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"parent": null,
"categories": [
"clothing",
"trousers"
],
"values": {
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like trousers!"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"post": {
"summary": "Create a new product model",
"operationId": "post_product_models",
"tags": [
"Product model"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to create a new product model. In the Enterprise Edition, since the v2.3, permissions based on your user groups are applied to the product model you try to create.",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several product models",
"operationId": "patch_product_models",
"tags": [
"Product model"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several product models at once. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product models exists for the given code, it creates it. In the Enterprise Edition, since the v2.3, permissions based on your user groups are applied to the product models you try to update. It may result in the creation of drafts if you only have edit rights through the product model's categories.",
"x-body-by-line": "Contains several lines, each line is a product model in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\": \"sub_sweat_option_a\", \"parent\": \"sweat\", \"values\": {\"a_simple_select\": [{\"locale\": null, \"scope\": null, \"data\": \"optionA\"}]}}",
"x-example-2": "{\"code\": \"sub_sweat_option_b\", \"parent\": \"sweat\", \"values\": {\"a_simple_select\": [{\"locale\": null, \"scope\": null, \"data\": \"optionA\"}]}}",
"x-example-3": "{\"code\":\"tshirt\", \"parent\": \"root_tshirt\", \"family_variant\":\"clothesvariant\",\"values\":{\"description\":[{\"scope\":\"ecommerce\",\"locale\":\"en_US\",\"data\":\"My amazing tshirt\"}]}}"
},
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"sub_sweat_option_a\",\"status_code\":204}",
"x-example-2": "{\"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\"}]}",
"x-example-3": "{\"line\":3,\"code\":\"tshirt\",\"status_code\":201}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/product-models/{code}": {
"get": {
"summary": "Get a product model",
"operationId": "get_product_models__code_",
"tags": [
"Product model"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to get the information about a given product model. In the Entreprise Edition, since the v2.0, permissions based on your user groups are applied to the product model you request.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "with_quality_scores",
"in": "query",
"description": "Return product model quality scores in the response. <strong>(Only available since the 6.0 version)</strong>",
"type": "boolean",
"required": false,
"x-from-version": "6.0"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the product model in JSON standard format.",
"schema": {
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create a product model",
"operationId": "patch_product_models__code_",
"tags": [
"Product model"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given product model. Learn more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no product model exists for the given code, it creates it. In the Enterprise Edition PIM since the 2.3, permissions based on your user groups are applied to the product model you try to update. It may result in the creation of a draft if you only have edit rights through the product model's categories.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 422,
"message": "Property \"labels\" expects an array as data, \"NULL\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}
}
}
},
"delete": {
"summary": "Delete a product model",
"operationId": "delete_product_models__code_",
"tags": [
"Product model"
],
"x-versions": [
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to delete a given product model. All its children, product models and variant products, will be also deleted. In the Enterprise Edition, the permissions based on your connection user group are applied to the product model you try to delete.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"204": {
"description": "No content to return",
"x-details": "Means that the deletion was successful"
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
}
}
}
},
"/api/rest/v1/product-models/{code}/proposal": {
"post": {
"summary": "Submit a draft for approval",
"operationId": "post_product_model_proposal",
"tags": [
"Product model"
],
"x-versions": [
"2.3",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to submit a product model draft for approval.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"201": {
"description": "Submitted",
"x-details": "Means that the draft submission was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/product-models/{code}/draft": {
"get": {
"summary": "Get a draft",
"operationId": "get_product_model_draft__code_",
"tags": [
"Product model"
],
"x-versions": [
"2.3",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to get the information about a given product model draft.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the draft in JSON standard format",
"schema": {
"type": "object",
"required": [
"code",
"family_variant"
],
"properties": {
"code": {
"type": "string",
"description": "Product model code",
"x-immutable": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the product inherits its attributes and attributes requirements (since the 3.2)",
"x-validation-rules": "It is equal to an existing family code",
"x-immutable": true,
"x-from-version": "3.2"
},
"family_variant": {
"type": "string",
"description": "Family variant code from which the product model inherits its attributes and variant attributes",
"x-validation-rules": "It is equal to an existing family variant code that belong to the family given in the `family` field",
"x-immutable": true
},
"parent": {
"type": "string",
"description": "Code of the parent <a href='api-reference.html#Productmodel'>product model</a>. This parent can be modified since the 2.3.",
"x-validation-rules": "&bull; It is equal to an existing product model code&#10;&bull; This product model has the same family variant as the one given in the `family_variant field`",
"default": "null",
"x-from-version": "2.3"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the product model is categorized",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Product model attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups, product and/or other product models, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Each string in the array of the property `product_models` is the code of an existing product model.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of product identifiers with which the product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Several quantified associations related to products and/or product models, grouped by quantified association types (only available since the 5.0)",
"x-validation-rules": "&bull; The `quantifiedAssociationTypeCode` is the code of an existing association type which provides quantity information. &#10;&bull; Each object in the array of the property `products` contains the identifier of an existing product and the quantity of it. &#10;&bull; Each object in the array of the property `product_models` contains the code of an existing product model and the quantity of it.",
"x-from-version": "5.0",
"properties": {
"quantifiedAssociationTypeCode": {
"type": "object",
"properties": {
"products": {
"type": "array",
"description": "Array of objects containing product identifiers and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
},
"product_models": {
"type": "array",
"description": "Array of objects containing product model codes and quantities with which the product model is in relation",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}
}
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
},
"metadata": {
"type": "object",
"description": "More information around the product model (only available since the v2.3 in the Enterprise Edition)",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "2.3",
"properties": {
"workflow_status": {
"description": "Status of the product model regarding the user permissions",
"type": "string",
"enum": [
"read_only",
"draft_in_progress",
"proposal_waiting_for_approval",
"working_copy"
]
}
}
},
"quality_scores": {
"type": "object",
"description": "Product model quality scores for each channel/locale combination (<strong>only available since the 7.0 version</strong> and when the \"with_quality_scores\" query parameter is set to \"true\")",
"x-immutable": true,
"x-read-only": true,
"x-from-version": "7.0"
}
},
"example": {
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"locale": null,
"scope": null,
"data": "antique_white"
}
],
"material": [
{
"locale": null,
"scope": null,
"data": "leather"
}
],
"variation_name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket leather"
}
],
"name": [
{
"locale": "en_US",
"scope": null,
"data": "Biker jacket"
}
],
"collection": [
{
"locale": null,
"scope": null,
"data": [
"summer_2017"
]
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"code": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
}
},
"/api/rest/v1/published-products": {
"get": {
"summary": "Get list of published products",
"operationId": "get_published_products",
"description": "This endpoint allows you to get a list of published products. Published products are paginated and they can be filtered.",
"tags": [
"Published product"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter published products, for more details see the <a href=\"/documentation/filter.html\">Filters</a> section",
"required": false,
"type": "string"
},
{
"name": "scope",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#filter-published-product-values\">Filter on published product values</a> section",
"required": false
},
{
"name": "locales",
"in": "query",
"type": "string",
"description": "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 <a href=\"/documentation/filter.html#filter-published-product-values\">Filter on published product values</a> section",
"required": false
},
{
"name": "attributes",
"in": "query",
"type": "string",
"description": "Filter published product values to only return those concerning the given attributes, for more details see the <a href=\"/documentation/filter.html#filter-product-values\">Filter on product values</a> section",
"required": false
},
{
"name": "pagination_type",
"in": "query",
"description": "Pagination method type, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "page",
"x-validation-rules": "One of the following values",
"enum": [
"page",
"search_after"
]
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "search_after",
"in": "query",
"description": "Cursor when using the `search_after` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "string",
"default": "cursor to the first page"
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return published products paginated",
"schema": {
"title": "Published products",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"identifier"
],
"properties": {
"identifier": {
"type": "string",
"description": "Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the published product is enable",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the published product inherits its attributes and attributes requirements",
"x-validation-rules": "It is equal to an existing family code",
"default": "null"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the published product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the published product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Published product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups and/or other published products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Identifiers used in the array of the property `products` cannot be equal to the published product identifier.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the published product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of published product identifiers with which the published product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Warning: associations with quantities are not compatible with the published products. The response will always be empty."
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
}
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/top"
}
},
"identifier": "top",
"family": "tshirt",
"groups": [],
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/cap"
}
},
"identifier": "cap",
"family": "caps",
"groups": [],
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/published-products/sweat"
}
},
"identifier": "sweat",
"family": null,
"groups": [],
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {}
}
]
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/published-products/{code}": {
"get": {
"summary": "Get a published product",
"operationId": "get_published_products__code_",
"tags": [
"Published product"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"x-ee": true,
"description": "This endpoint allows you to get the information about a given published product.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the published product in JSON standard format",
"schema": {
"type": "object",
"required": [
"identifier"
],
"properties": {
"identifier": {
"type": "string",
"description": "Published product identifier, i.e. the value of the only `pim_catalog_identifier` attribute"
},
"enabled": {
"type": "boolean",
"description": "Whether the published product is enable",
"default": true
},
"family": {
"type": "string",
"description": "<a href='api-reference.html#Family'>Family</a> code from which the published product inherits its attributes and attributes requirements",
"x-validation-rules": "It is equal to an existing family code",
"default": "null"
},
"categories": {
"type": "array",
"description": "Codes of the <a href='api-reference.html#Category'>categories</a> in which the published product is classified",
"x-validation-rules": "Each string of the array is equal to an existing category code",
"items": {
"type": "string"
},
"default": []
},
"groups": {
"type": "array",
"description": "Codes of the groups to which the published product belong",
"x-validation-rules": "Each string of the array is equal to an existing group code",
"items": {
"type": "string"
},
"default": []
},
"values": {
"type": "object",
"description": "Published product attributes values, see <a href='/concepts/products.html#focus-on-the-product-values'>Product values</a> section for more details",
"x-validation-rules": "Validation rules detailed in Product values section",
"properties": {
"attributeCode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"description": "<a href='api-reference.html#Channel'>Channel</a> code of the product value"
},
"locale": {
"type": "string",
"description": "<a href='api-reference.html#Locale'>Locale</a> code of the product value"
},
"data": {
"type": "object",
"description": "<a href='api-reference.html#Productuuid'>Product</a> value"
}
}
}
}
}
},
"associations": {
"type": "object",
"description": "Several associations related to groups and/or other published products, grouped by association types",
"x-validation-rules": "&bull; The `associationTypeCode` is the code of an existing association type. &#10;&bull; Each string in the array of the property `groups` is the code of an existing group. &#10;&bull; Each string in the array of the property `products` is the identifier of an existing product. &#10;&bull; Identifiers used in the array of the property `products` cannot be equal to the published product identifier.",
"properties": {
"associationTypeCode": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"description": "Array of groups codes with which the published product is in relation",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"description": "Array of published product identifiers with which the published product is in relation",
"items": {
"type": "string"
}
},
"product_models": {
"type": "array",
"description": "Array of product model codes with which the product is in relation (only available since the v2.1)",
"x-from-version": "2.1",
"items": {
"type": "string"
}
}
}
}
}
},
"quantified_associations": {
"type": "object",
"description": "Warning: associations with quantities are not compatible with the published products. The response will always be empty."
},
"created": {
"type": "string",
"description": "Date of creation",
"format": "dateTime",
"x-immutable": true,
"x-read-only": true
},
"updated": {
"type": "string",
"description": "Date of the last update",
"format": "dateTime",
"x-read-only": true
}
},
"example": {
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"locale": null,
"scope": null,
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"locale": null,
"scope": null,
"data": "black"
}
],
"size": [
{
"locale": null,
"scope": null,
"data": "m"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
}
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
}
},
"/api/rest/v1/media-files": {
"get": {
"summary": "Get a list of product media files",
"operationId": "get_media_files",
"description": "This endpoint allows you to get a list of media files that are used as attribute values in products or product models.",
"tags": [
"Product media file"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return media files paginated",
"schema": {
"title": "MediaFiles",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI to get the metadata of the media file"
}
}
},
"download": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI to download the binaries of the media file"
}
}
}
}
}
}
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Media file code",
"x-immutable": true
},
"original_filename": {
"type": "string",
"description": "Original filename of the media file"
},
"mime_type": {
"type": "string",
"description": "Mime type of the media file",
"x-read-only": true
},
"size": {
"type": "integer",
"description": "Size of the media file",
"x-read-only": true
},
"extension": {
"type": "string",
"description": "Extension of the media file",
"x-read-only": true
}
},
"example": {
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
}
},
"current_page": 2,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg/download"
}
},
"code": "d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg",
"original_filename": "10734346-1480.jpg",
"mime_type": "image/jpeg",
"size": 16454,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg/download"
}
},
"code": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg",
"original_filename": "12431976-8797.jpg",
"mime_type": "image/jpeg",
"size": 19725,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg/download"
}
},
"code": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg",
"original_filename": "107406-9841.jpg",
"mime_type": "image/jpeg",
"size": 17639,
"extension": "jpg"
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new product media file",
"operationId": "post_media_files",
"description": "This endpoint allows you to create a new media file and associate it to an attribute value of a given product or product model.",
"tags": [
"Product media file"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "Content-type",
"in": "header",
"type": "string",
"description": "Equal to 'multipart/form-data', no other value allowed",
"required": true
},
{
"name": "body",
"in": "body",
"x-form-data": true,
"schema": {
"required": [
"file"
],
"properties": {
"product": {
"type": "string",
"description": "The product to which the media file will be associated. It is a JSON string that follows this format '{\"identifier\":\"product_identifier\", \"attribute\":\"attribute_code\", \"scope\":\"channel_code\",\"locale\":\"locale_code\"}'. You have to either use this field or the `product_model` field, but not both at the same time."
},
"product_model": {
"type": "string",
"description": "The product model to which the media file will be associated. It is a JSON string that follows this format '{\"code\":\"product_model_code\", \"attribute\":\"attribute_code\", \"scope\":\"channel_code\",\"locale\":\"locale_code\"}'. You have to either use this field or the `product` field, but not both at the same time."
},
"file": {
"type": "string",
"description": "The binaries of the file",
"format": "binary"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `multipart/form-data`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘multipart/form-data’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/media-files/{code}": {
"get": {
"summary": "Get a product media file",
"operationId": "get_media_files__code_",
"description": "This endpoint allows you to get the information about a given media file that is used as an attribute value of a product or a product model.",
"tags": [
"Product media file"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the media file in JSON standard format",
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"x-read-only": true,
"properties": {
"download": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI to download the binaries of the media file"
}
}
}
}
}
}
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Media file code",
"x-immutable": true
},
"original_filename": {
"type": "string",
"description": "Original filename of the media file"
},
"mime_type": {
"type": "string",
"description": "Mime type of the media file",
"x-read-only": true
},
"size": {
"type": "integer",
"description": "Size of the media file",
"x-read-only": true
},
"extension": {
"type": "string",
"description": "Extension of the media file",
"x-read-only": true
}
},
"example": {
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}
}
],
"example": {
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
}
},
"/api/rest/v1/media-files/{code}/download": {
"get": {
"summary": "Download a product media file",
"operationId": "get_media_files__code__download",
"description": "This endpoint allows you to download a given media file that is used as an attribute value of a product or a product model.",
"x-content-type": "Mime-type of the media file",
"tags": [
"Product media file"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the binary of the media file",
"x-content-type": "Mime-type of the media file"
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
}
}
}
},
"/api/rest/v1/families": {
"get": {
"summary": "Get list of families",
"operationId": "get_families",
"description": "This endpoint allows you to get a list of families. Families are paginated and sorted by code.",
"tags": [
"Family"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter families, for more details see the <a href=\"/documentation/filter.html#filter-families\">Filters</a> section.",
"required": false,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return families paginated",
"schema": {
"title": "Families",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code",
"attribute_as_label"
],
"properties": {
"code": {
"type": "string",
"description": "Family code",
"x-immutable": true
},
"attribute_as_label": {
"type": "string",
"description": "Attribute code used as label",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is either `pim_catalog_identifier` or `pim_catalog_text`"
},
"attribute_as_image": {
"type": "string",
"description": "Attribute code used as the main picture in the user interface (only since v2.0)",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is `pim_catalog_image`. Since v2.1, you can also use a `pim_assets_collection` attribute type",
"default": "null",
"x-from-version": "2.0"
},
"attributes": {
"type": "array",
"description": "Attributes codes that compose the family",
"x-validation-rules": "Each string of the array is an existing attribute code",
"items": {
"type": "string"
},
"default": []
},
"attribute_requirements": {
"type": "object",
"description": "Attributes codes of the family that are required for the completeness calculation for each channel",
"x-validation-rules": "&bull; Each string of these arrays is an existing attribute code &#10;&bull; These attribute codes are in the array of the property `attributes` &#10;&bull; The `channelCode` is the code of an existing and activated channel",
"properties": {
"channelCode": {
"type": "array",
"items": {
"type": "string",
"description": "Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`"
}
}
}
},
"labels": {
"type": "object",
"description": "Family labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
}
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_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"
}
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new family",
"operationId": "post_families",
"description": "This endpoint allows you to create a new family.",
"tags": [
"Family"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code",
"attribute_as_label"
],
"properties": {
"code": {
"type": "string",
"description": "Family code",
"x-immutable": true
},
"attribute_as_label": {
"type": "string",
"description": "Attribute code used as label",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is either `pim_catalog_identifier` or `pim_catalog_text`"
},
"attribute_as_image": {
"type": "string",
"description": "Attribute code used as the main picture in the user interface (only since v2.0)",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is `pim_catalog_image`. Since v2.1, you can also use a `pim_assets_collection` attribute type",
"default": "null",
"x-from-version": "2.0"
},
"attributes": {
"type": "array",
"description": "Attributes codes that compose the family",
"x-validation-rules": "Each string of the array is an existing attribute code",
"items": {
"type": "string"
},
"default": []
},
"attribute_requirements": {
"type": "object",
"description": "Attributes codes of the family that are required for the completeness calculation for each channel",
"x-validation-rules": "&bull; Each string of these arrays is an existing attribute code &#10;&bull; These attribute codes are in the array of the property `attributes` &#10;&bull; The `channelCode` is the code of an existing and activated channel",
"properties": {
"channelCode": {
"type": "array",
"items": {
"type": "string",
"description": "Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`"
}
}
}
},
"labels": {
"type": "object",
"description": "Family labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several families",
"operationId": "patch_families",
"tags": [
"Family"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several families at once.",
"x-body-by-line": "Contains several lines, each line is a family in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\":\"tshirt\",\"attributes\":[\"description\",\"size\"]}",
"x-example-2": "{\"code\":\"cap\",\"attribute_as_label\":\"descripion\"}",
"x-example-3": "{\"code\":\"mug\",\"attributes\":[\"description\",\"short_description\"]}"
},
"type": "object",
"required": [
"code",
"attribute_as_label"
],
"properties": {
"code": {
"type": "string",
"description": "Family code",
"x-immutable": true
},
"attribute_as_label": {
"type": "string",
"description": "Attribute code used as label",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is either `pim_catalog_identifier` or `pim_catalog_text`"
},
"attribute_as_image": {
"type": "string",
"description": "Attribute code used as the main picture in the user interface (only since v2.0)",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is `pim_catalog_image`. Since v2.1, you can also use a `pim_assets_collection` attribute type",
"default": "null",
"x-from-version": "2.0"
},
"attributes": {
"type": "array",
"description": "Attributes codes that compose the family",
"x-validation-rules": "Each string of the array is an existing attribute code",
"items": {
"type": "string"
},
"default": []
},
"attribute_requirements": {
"type": "object",
"description": "Attributes codes of the family that are required for the completeness calculation for each channel",
"x-validation-rules": "&bull; Each string of these arrays is an existing attribute code &#10;&bull; These attribute codes are in the array of the property `attributes` &#10;&bull; The `channelCode` is the code of an existing and activated channel",
"properties": {
"channelCode": {
"type": "array",
"items": {
"type": "string",
"description": "Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`"
}
}
}
},
"labels": {
"type": "object",
"description": "Family labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"tshirt\",\"status_code\":201}",
"x-example-2": "{\"line\":2,\"code\":\"cap\",\"status_code\":422,\"message\":\"Attribute \"descripion\" does not exist.\"}",
"x-example-3": "{\"line\":3,\"code\":\"mug\",\"status_code\":204}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/families/{code}": {
"get": {
"summary": "Get a family",
"operationId": "get_families__code_",
"description": "This endpoint allows you to get the information about a given family.",
"tags": [
"Family"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the family in JSON standard format",
"schema": {
"type": "object",
"required": [
"code",
"attribute_as_label"
],
"properties": {
"code": {
"type": "string",
"description": "Family code",
"x-immutable": true
},
"attribute_as_label": {
"type": "string",
"description": "Attribute code used as label",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is either `pim_catalog_identifier` or `pim_catalog_text`"
},
"attribute_as_image": {
"type": "string",
"description": "Attribute code used as the main picture in the user interface (only since v2.0)",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is `pim_catalog_image`. Since v2.1, you can also use a `pim_assets_collection` attribute type",
"default": "null",
"x-from-version": "2.0"
},
"attributes": {
"type": "array",
"description": "Attributes codes that compose the family",
"x-validation-rules": "Each string of the array is an existing attribute code",
"items": {
"type": "string"
},
"default": []
},
"attribute_requirements": {
"type": "object",
"description": "Attributes codes of the family that are required for the completeness calculation for each channel",
"x-validation-rules": "&bull; Each string of these arrays is an existing attribute code &#10;&bull; These attribute codes are in the array of the property `attributes` &#10;&bull; The `channelCode` is the code of an existing and activated channel",
"properties": {
"channelCode": {
"type": "array",
"items": {
"type": "string",
"description": "Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`"
}
}
}
},
"labels": {
"type": "object",
"description": "Family labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
}
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create a family",
"operationId": "patch_families__code_",
"tags": [
"Family"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given family. Know more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no family exists for the given code, it creates it.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code",
"attribute_as_label"
],
"properties": {
"code": {
"type": "string",
"description": "Family code",
"x-immutable": true
},
"attribute_as_label": {
"type": "string",
"description": "Attribute code used as label",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is either `pim_catalog_identifier` or `pim_catalog_text`"
},
"attribute_as_image": {
"type": "string",
"description": "Attribute code used as the main picture in the user interface (only since v2.0)",
"x-validation-rules": "&bull; It is equal to an existing attribute code &#10;&bull; This attribute code is in the array of the property `attributes` &#10;&bull; The type of this attribute is `pim_catalog_image`. Since v2.1, you can also use a `pim_assets_collection` attribute type",
"default": "null",
"x-from-version": "2.0"
},
"attributes": {
"type": "array",
"description": "Attributes codes that compose the family",
"x-validation-rules": "Each string of the array is an existing attribute code",
"items": {
"type": "string"
},
"default": []
},
"attribute_requirements": {
"type": "object",
"description": "Attributes codes of the family that are required for the completeness calculation for each channel",
"x-validation-rules": "&bull; Each string of these arrays is an existing attribute code &#10;&bull; These attribute codes are in the array of the property `attributes` &#10;&bull; The `channelCode` is the code of an existing and activated channel",
"properties": {
"channelCode": {
"type": "array",
"items": {
"type": "string",
"description": "Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`"
}
}
}
},
"labels": {
"type": "object",
"description": "Family labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/families/{family_code}/variants": {
"get": {
"summary": "Get list of family variants",
"operationId": "get_families__family_code__variants",
"description": "This endpoint allows you to get a list of family variants. Family variants are paginated and sorted by code.",
"tags": [
"Family variant"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "family_code",
"in": "path",
"description": "Code of the family",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return family variants paginated",
"schema": {
"title": "Family Variants",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code",
"variant_attribute_sets"
],
"properties": {
"code": {
"type": "string",
"description": "Family variant code",
"x-immutable": true
},
"variant_attribute_sets": {
"type": "array",
"description": "Attributes distribution according to the enrichment level",
"items": {
"type": "object",
"required": [
"level",
"axes"
],
"description": "Enrichment level",
"properties": {
"level": {
"type": "integer",
"description": "Enrichment level",
"x-immutable": true,
"x-validation-rules": "&bull; Number representing the level of the attribute set. &#10;&bull; It should be equal to 1 or 2. &#10;&bull; If you specify the level 2, you have to specify the level 1 as well."
},
"axes": {
"type": "array",
"description": "Codes of attributes used as variant axes",
"x-immutable": true,
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of maximum 5 existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Only the following attribute types are allowed: `simple select`, `multi select`, `reference data`, `metric`, `boolean` &#10;&bull; Attributes cannot be scopable, nor localizable nor locale specific &#10;&bull; Attributes used as axes in one level cannot be used as axes or as attributes in the other level"
},
"attributes": {
"type": "array",
"description": "Codes of attributes bind to this enrichment level",
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Attributes used as attribute in one level cannot be used as axes or as attributes in the other level &#10;&bull; Attributes that are `unique value` or `identifier` are automatically distributed to the lower level."
}
}
}
},
"labels": {
"type": "object",
"description": "Family variant labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
]
}
]
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"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"
]
}
]
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new family variant",
"operationId": "post_families__family_code__variants",
"tags": [
"Family"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to create a family variant.",
"parameters": [
{
"name": "family_code",
"in": "path",
"description": "Code of the family",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code",
"variant_attribute_sets"
],
"properties": {
"code": {
"type": "string",
"description": "Family variant code",
"x-immutable": true
},
"variant_attribute_sets": {
"type": "array",
"description": "Attributes distribution according to the enrichment level",
"items": {
"type": "object",
"required": [
"level",
"axes"
],
"description": "Enrichment level",
"properties": {
"level": {
"type": "integer",
"description": "Enrichment level",
"x-immutable": true,
"x-validation-rules": "&bull; Number representing the level of the attribute set. &#10;&bull; It should be equal to 1 or 2. &#10;&bull; If you specify the level 2, you have to specify the level 1 as well."
},
"axes": {
"type": "array",
"description": "Codes of attributes used as variant axes",
"x-immutable": true,
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of maximum 5 existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Only the following attribute types are allowed: `simple select`, `multi select`, `reference data`, `metric`, `boolean` &#10;&bull; Attributes cannot be scopable, nor localizable nor locale specific &#10;&bull; Attributes used as axes in one level cannot be used as axes or as attributes in the other level"
},
"attributes": {
"type": "array",
"description": "Codes of attributes bind to this enrichment level",
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Attributes used as attribute in one level cannot be used as axes or as attributes in the other level &#10;&bull; Attributes that are `unique value` or `identifier` are automatically distributed to the lower level."
}
}
}
},
"labels": {
"type": "object",
"description": "Family variant labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
]
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several family variants",
"operationId": "patch_families__family_code__variants",
"tags": [
"Family variant"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several family variants at once, for a given family.",
"x-body-by-line": "Contains several lines, each line is a family in JSON standard format",
"parameters": [
{
"name": "family_code",
"in": "path",
"description": "Code of the family",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\": \"shoes_by_size\", \"variant_attribute_sets\": [{\"level\": 1, \"axes\": [\"size\"], \"attributes\": [\"color\"]}]}",
"x-example-2": "{\"code\": \"shoes_by_color\",\"labels\": {\"en_US\": \"Shoes by color\"}}",
"x-example-3": "{\"code\": \"shoes_without_axes\", \"variant_attribute_sets\": [{\"level\": 1, \"axes\": [], \"attributes\": [\"color\"]}]}"
},
"type": "object",
"required": [
"code",
"variant_attribute_sets"
],
"properties": {
"code": {
"type": "string",
"description": "Family variant code",
"x-immutable": true
},
"variant_attribute_sets": {
"type": "array",
"description": "Attributes distribution according to the enrichment level",
"items": {
"type": "object",
"required": [
"level",
"axes"
],
"description": "Enrichment level",
"properties": {
"level": {
"type": "integer",
"description": "Enrichment level",
"x-immutable": true,
"x-validation-rules": "&bull; Number representing the level of the attribute set. &#10;&bull; It should be equal to 1 or 2. &#10;&bull; If you specify the level 2, you have to specify the level 1 as well."
},
"axes": {
"type": "array",
"description": "Codes of attributes used as variant axes",
"x-immutable": true,
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of maximum 5 existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Only the following attribute types are allowed: `simple select`, `multi select`, `reference data`, `metric`, `boolean` &#10;&bull; Attributes cannot be scopable, nor localizable nor locale specific &#10;&bull; Attributes used as axes in one level cannot be used as axes or as attributes in the other level"
},
"attributes": {
"type": "array",
"description": "Codes of attributes bind to this enrichment level",
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Attributes used as attribute in one level cannot be used as axes or as attributes in the other level &#10;&bull; Attributes that are `unique value` or `identifier` are automatically distributed to the lower level."
}
}
}
},
"labels": {
"type": "object",
"description": "Family variant labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
]
}
]
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"shoes_by_size\",\"status_code\":201}",
"x-example-2": "{\"line\":2,\"code\":\"shoes_by_color\",\"status_code\":204}",
"x-example-3": "{\"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\"\"}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/families/{family_code}/variants/{code}": {
"get": {
"summary": "Get a family variant",
"operationId": "get_families__family_code__variants__code__",
"description": "This endpoint allows you to get the information about a given family variant.",
"tags": [
"Family variant"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "family_code",
"in": "path",
"description": "Code of the family",
"required": true,
"type": "string"
},
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the family variant in JSON standard format",
"schema": {
"type": "object",
"required": [
"code",
"variant_attribute_sets"
],
"properties": {
"code": {
"type": "string",
"description": "Family variant code",
"x-immutable": true
},
"variant_attribute_sets": {
"type": "array",
"description": "Attributes distribution according to the enrichment level",
"items": {
"type": "object",
"required": [
"level",
"axes"
],
"description": "Enrichment level",
"properties": {
"level": {
"type": "integer",
"description": "Enrichment level",
"x-immutable": true,
"x-validation-rules": "&bull; Number representing the level of the attribute set. &#10;&bull; It should be equal to 1 or 2. &#10;&bull; If you specify the level 2, you have to specify the level 1 as well."
},
"axes": {
"type": "array",
"description": "Codes of attributes used as variant axes",
"x-immutable": true,
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of maximum 5 existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Only the following attribute types are allowed: `simple select`, `multi select`, `reference data`, `metric`, `boolean` &#10;&bull; Attributes cannot be scopable, nor localizable nor locale specific &#10;&bull; Attributes used as axes in one level cannot be used as axes or as attributes in the other level"
},
"attributes": {
"type": "array",
"description": "Codes of attributes bind to this enrichment level",
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Attributes used as attribute in one level cannot be used as axes or as attributes in the other level &#10;&bull; Attributes that are `unique value` or `identifier` are automatically distributed to the lower level."
}
}
}
},
"labels": {
"type": "object",
"description": "Family variant labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
]
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create a family variant",
"operationId": "patch_families__family_code__variants__code__",
"tags": [
"Family variant"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given family variant. Know more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no family variant exists for the given code, it creates it.",
"parameters": [
{
"name": "family_code",
"in": "path",
"description": "Code of the family",
"required": true,
"type": "string"
},
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code",
"variant_attribute_sets"
],
"properties": {
"code": {
"type": "string",
"description": "Family variant code",
"x-immutable": true
},
"variant_attribute_sets": {
"type": "array",
"description": "Attributes distribution according to the enrichment level",
"items": {
"type": "object",
"required": [
"level",
"axes"
],
"description": "Enrichment level",
"properties": {
"level": {
"type": "integer",
"description": "Enrichment level",
"x-immutable": true,
"x-validation-rules": "&bull; Number representing the level of the attribute set. &#10;&bull; It should be equal to 1 or 2. &#10;&bull; If you specify the level 2, you have to specify the level 1 as well."
},
"axes": {
"type": "array",
"description": "Codes of attributes used as variant axes",
"x-immutable": true,
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of maximum 5 existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Only the following attribute types are allowed: `simple select`, `multi select`, `reference data`, `metric`, `boolean` &#10;&bull; Attributes cannot be scopable, nor localizable nor locale specific &#10;&bull; Attributes used as axes in one level cannot be used as axes or as attributes in the other level"
},
"attributes": {
"type": "array",
"description": "Codes of attributes bind to this enrichment level",
"items": {
"type": "string"
},
"default": [],
"x-validation-rules": "&bull; Should be an array of existing attribute codes &#10;&bull; These attributes should belong to the family of the family variant &#10;&bull; Attributes used as attribute in one level cannot be used as axes or as attributes in the other level &#10;&bull; Attributes that are `unique value` or `identifier` are automatically distributed to the lower level."
}
}
}
},
"labels": {
"type": "object",
"description": "Family variant labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "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"
]
}
]
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/attributes": {
"get": {
"summary": "Get list of attributes",
"operationId": "get_attributes",
"description": "This endpoint allows you to get a list of attributes. Attributes are paginated and sorted by code.",
"tags": [
"Attribute"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter attributes, for more details see the <a href=\"/documentation/filter.html#filter-attributes\">Filters</a> section.",
"required": false,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
},
{
"name": "with_table_select_options",
"in": "query",
"description": "Return the options of 'select' column types (of a table attribute) in the response. (Only available since the 7.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "7.0"
}
],
"responses": {
"200": {
"description": "Return attributes paginated",
"schema": {
"title": "Attributes",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code",
"type",
"group"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute code",
"x-immutable": true
},
"type": {
"type": "string",
"description": "Attribute type. See <a href='/concepts/catalog-structure.html#attribute'>type</a> section for more details.",
"x-validation-rules": "The type is one of the following values",
"enum": [
"pim_catalog_identifier",
"pim_catalog_metric",
"pim_catalog_number",
"pim_catalog_reference_data_multi_select",
"pim_catalog_reference_data_simple_select",
"pim_catalog_simpleselect",
"pim_catalog_multiselect",
"pim_catalog_date",
"pim_catalog_textarea",
"pim_catalog_text",
"pim_catalog_file",
"pim_catalog_image",
"pim_catalog_price_collection",
"pim_catalog_boolean",
"akeneo_reference_entity",
"akeneo_reference_entity_collection",
"pim_catalog_asset_collection"
],
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Attribute labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute label for the locale `localeCode`"
}
}
},
"group": {
"type": "string",
"description": "Attribute group",
"x-validation-rules": "It is the code of an existing group"
},
"group_labels": {
"type": "object",
"description": "Group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"x-read-only": true,
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Group label for the locale `localeCode`"
}
}
},
"sort_order": {
"type": "integer",
"description": "Order of the attribute in its group",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"localizable": {
"type": "boolean",
"description": "Whether the attribute is localizable, i.e. can have one value by locale",
"default": false,
"x-immutable": true
},
"scopable": {
"type": "boolean",
"description": "Whether the attribute is scopable, i.e. can have one value by channel",
"default": false,
"x-immutable": true
},
"available_locales": {
"type": "array",
"description": "To make the attribute locale specfic, specify here for which locales it is specific",
"x-validation-rules": "Each string of the array is an existing and activated locale",
"items": {
"type": "string"
}
},
"unique": {
"type": "boolean",
"description": "Whether two values for the attribute cannot be the same",
"x-immutable": true
},
"useable_as_grid_filter": {
"type": "boolean",
"description": "Whether the attribute can be used as a filter for the product grid in the PIM user interface"
},
"max_characters": {
"type": "integer",
"description": "Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier` attribute types"
},
"validation_rule": {
"type": "string",
"description": "Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Equal to `regexp` when the attribute type is equal to `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"validation_regexp": {
"type": "string",
"description": "Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Required when the property `validation_rule` is equal to `regexp`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"wysiwyg_enabled": {
"type": "boolean",
"description": "Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`",
"x-warning": "Only for `pim_catalog_textarea` attribute type"
},
"number_min": {
"type": "string",
"description": "Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"number_max": {
"type": "string",
"description": "Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"decimals_allowed": {
"type": "boolean",
"description": "Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"negative_allowed": {
"type": "boolean",
"description": "Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric` or `pim_catalog_number` attribute types"
},
"metric_family": {
"type": "string",
"description": "Metric family when the attribute type is `pim_catalog_metric`",
"x-immutable": true,
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"default_metric_unit": {
"type": "string",
"description": "Default metric unit when the attribute type is `pim_catalog_metric`",
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"date_min": {
"type": "string",
"description": "Minimum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"date_max": {
"type": "string",
"description": "Maximum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"allowed_extensions": {
"type": "array",
"description": "Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types",
"items": {
"type": "string"
}
},
"max_file_size": {
"type": "string",
"description": "Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types"
},
"reference_data_name": {
"type": "string",
"description": "Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`",
"x-validation-rules": "Required only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types",
"x-warning": "Only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types"
},
"default_value": {
"type": "boolean",
"description": "Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)",
"x-warning": "Only for `pim_catalog_boolean` attribute type",
"x-from-version": "5.0"
},
"table_configuration": {
"type": "array",
"description": "Configuration of the Table attribute (columns)",
"x-validation-rules": "Required only for `pim_catalog_table` attribute type",
"x-warning": "Only for `pim_catalog_table` attribute type",
"items": {
"type": "object",
"required": [
"code",
"data_type"
],
"properties": {
"code": {
"type": "string",
"description": "Column code"
},
"data_type": {
"type": "string",
"enum": [
"select",
"text",
"number",
"boolean"
],
"description": "Column data type"
},
"validations": {
"type": "object",
"description": "User defined validation constraints on the cell content",
"default": {},
"properties": {
"min": {
"type": "number",
"description": "minimum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"max": {
"type": "number",
"description": "maximum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"decimals_allowed": {
"type": "boolean",
"description": "whether the value of a numeric cell can hold a decimal part",
"x-validation-rules": "only for `number` data type columns"
},
"max_length": {
"type": "number",
"description": "maximum length of a text cell",
"x-validation-rules": "only for `text` data type columns"
}
}
},
"labels": {
"type": "object",
"description": "Column labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Column label for the locale `localeCode`"
}
}
},
"is_required_for_completeness": {
"type": "boolean",
"description": "Defines if the column should be entirely filled for the attribute to be considered complete",
"x-warning": "This value is always true for the first column in a table configuration",
"default": false
}
}
}
},
"is_main_identifier": {
"type": "boolean",
"description": "Is this attribute main identifier when attribute type is `pim_catalog_identifier`"
}
},
"example": {
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/sku"
}
},
"code": "sku",
"type": "pim_catalog_identifier",
"group": "other",
"group_labels": {
"en_US": "Other",
"fr_FR": "Autre"
},
"unique": true,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Identifier",
"fr_FR": "Identifiant"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/release_date"
}
},
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
},
{
"_links": {
"self": {
"href": "http://localhost:8080/api/rest/v1/attributes/food_composition"
}
},
"code": "food_composition",
"type": "pim_catalog_table",
"group": "product",
"unique": false,
"useable_as_grid_filter": false,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 0,
"localizable": false,
"scopable": false,
"labels": {
"en_US": "Composition",
"fr_FR": "Composition"
},
"guidelines": {},
"auto_option_sorting": null,
"is_read_only": null,
"default_value": null,
"table_configuration": [
{
"code": "ingredient",
"data_type": "select",
"labels": {
"en_US": "Ingredient",
"fr_FR": "Ingrédient"
},
"validations": {},
"is_required_for_completeness": true
},
{
"code": "percentage",
"data_type": "number",
"labels": {
"en_US": "%",
"fr_FR": "%"
},
"validations": {
"max": 100,
"min": 0,
"decimals_allowed": true
},
"is_required_for_completeness": true
},
{
"code": "allergen",
"data_type": "boolean",
"labels": {
"en_US": "Allergen",
"fr_FR": "Allergène"
},
"validations": {},
"is_required_for_completeness": false
}
]
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new attribute",
"operationId": "post_attributes",
"description": "This endpoint allows you to create a new attribute.",
"tags": [
"Attribute"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code",
"type",
"group"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute code",
"x-immutable": true
},
"type": {
"type": "string",
"description": "Attribute type. See <a href='/concepts/catalog-structure.html#attribute'>type</a> section for more details.",
"x-validation-rules": "The type is one of the following values",
"enum": [
"pim_catalog_identifier",
"pim_catalog_metric",
"pim_catalog_number",
"pim_catalog_reference_data_multi_select",
"pim_catalog_reference_data_simple_select",
"pim_catalog_simpleselect",
"pim_catalog_multiselect",
"pim_catalog_date",
"pim_catalog_textarea",
"pim_catalog_text",
"pim_catalog_file",
"pim_catalog_image",
"pim_catalog_price_collection",
"pim_catalog_boolean",
"akeneo_reference_entity",
"akeneo_reference_entity_collection",
"pim_catalog_asset_collection"
],
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Attribute labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute label for the locale `localeCode`"
}
}
},
"group": {
"type": "string",
"description": "Attribute group",
"x-validation-rules": "It is the code of an existing group"
},
"group_labels": {
"type": "object",
"description": "Group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"x-read-only": true,
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Group label for the locale `localeCode`"
}
}
},
"sort_order": {
"type": "integer",
"description": "Order of the attribute in its group",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"localizable": {
"type": "boolean",
"description": "Whether the attribute is localizable, i.e. can have one value by locale",
"default": false,
"x-immutable": true
},
"scopable": {
"type": "boolean",
"description": "Whether the attribute is scopable, i.e. can have one value by channel",
"default": false,
"x-immutable": true
},
"available_locales": {
"type": "array",
"description": "To make the attribute locale specfic, specify here for which locales it is specific",
"x-validation-rules": "Each string of the array is an existing and activated locale",
"items": {
"type": "string"
}
},
"unique": {
"type": "boolean",
"description": "Whether two values for the attribute cannot be the same",
"x-immutable": true
},
"useable_as_grid_filter": {
"type": "boolean",
"description": "Whether the attribute can be used as a filter for the product grid in the PIM user interface"
},
"max_characters": {
"type": "integer",
"description": "Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier` attribute types"
},
"validation_rule": {
"type": "string",
"description": "Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Equal to `regexp` when the attribute type is equal to `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"validation_regexp": {
"type": "string",
"description": "Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Required when the property `validation_rule` is equal to `regexp`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"wysiwyg_enabled": {
"type": "boolean",
"description": "Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`",
"x-warning": "Only for `pim_catalog_textarea` attribute type"
},
"number_min": {
"type": "string",
"description": "Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"number_max": {
"type": "string",
"description": "Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"decimals_allowed": {
"type": "boolean",
"description": "Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"negative_allowed": {
"type": "boolean",
"description": "Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric` or `pim_catalog_number` attribute types"
},
"metric_family": {
"type": "string",
"description": "Metric family when the attribute type is `pim_catalog_metric`",
"x-immutable": true,
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"default_metric_unit": {
"type": "string",
"description": "Default metric unit when the attribute type is `pim_catalog_metric`",
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"date_min": {
"type": "string",
"description": "Minimum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"date_max": {
"type": "string",
"description": "Maximum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"allowed_extensions": {
"type": "array",
"description": "Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types",
"items": {
"type": "string"
}
},
"max_file_size": {
"type": "string",
"description": "Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types"
},
"reference_data_name": {
"type": "string",
"description": "Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`",
"x-validation-rules": "Required only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types",
"x-warning": "Only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types"
},
"default_value": {
"type": "boolean",
"description": "Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)",
"x-warning": "Only for `pim_catalog_boolean` attribute type",
"x-from-version": "5.0"
},
"table_configuration": {
"type": "array",
"description": "Configuration of the Table attribute (columns)",
"x-validation-rules": "Required only for `pim_catalog_table` attribute type",
"x-warning": "Only for `pim_catalog_table` attribute type",
"items": {
"type": "object",
"required": [
"code",
"data_type"
],
"properties": {
"code": {
"type": "string",
"description": "Column code"
},
"data_type": {
"type": "string",
"enum": [
"select",
"text",
"number",
"boolean"
],
"description": "Column data type"
},
"validations": {
"type": "object",
"description": "User defined validation constraints on the cell content",
"default": {},
"properties": {
"min": {
"type": "number",
"description": "minimum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"max": {
"type": "number",
"description": "maximum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"decimals_allowed": {
"type": "boolean",
"description": "whether the value of a numeric cell can hold a decimal part",
"x-validation-rules": "only for `number` data type columns"
},
"max_length": {
"type": "number",
"description": "maximum length of a text cell",
"x-validation-rules": "only for `text` data type columns"
}
}
},
"labels": {
"type": "object",
"description": "Column labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Column label for the locale `localeCode`"
}
}
},
"is_required_for_completeness": {
"type": "boolean",
"description": "Defines if the column should be entirely filled for the attribute to be considered complete",
"x-warning": "This value is always true for the first column in a table configuration",
"default": false
}
}
}
},
"is_main_identifier": {
"type": "boolean",
"description": "Is this attribute main identifier when attribute type is `pim_catalog_identifier`"
}
},
"example": {
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several attributes",
"operationId": "patch_attributes",
"tags": [
"Attribute"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several attributes at once.",
"x-body-by-line": "Contains several lines, each line is an attribute in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\":\"description\",\"useable_as_grid_filter\":true}",
"x-example-2": "{\"code\":\"short_description\",\"group\":\"marketig\"}",
"x-example-3": "{\"code\":\"release_date\",\"date_min\":\"2017-06-28T08:00:00\"}"
},
"type": "object",
"required": [
"code",
"type",
"group"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute code",
"x-immutable": true
},
"type": {
"type": "string",
"description": "Attribute type. See <a href='/concepts/catalog-structure.html#attribute'>type</a> section for more details.",
"x-validation-rules": "The type is one of the following values",
"enum": [
"pim_catalog_identifier",
"pim_catalog_metric",
"pim_catalog_number",
"pim_catalog_reference_data_multi_select",
"pim_catalog_reference_data_simple_select",
"pim_catalog_simpleselect",
"pim_catalog_multiselect",
"pim_catalog_date",
"pim_catalog_textarea",
"pim_catalog_text",
"pim_catalog_file",
"pim_catalog_image",
"pim_catalog_price_collection",
"pim_catalog_boolean",
"akeneo_reference_entity",
"akeneo_reference_entity_collection",
"pim_catalog_asset_collection"
],
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Attribute labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute label for the locale `localeCode`"
}
}
},
"group": {
"type": "string",
"description": "Attribute group",
"x-validation-rules": "It is the code of an existing group"
},
"group_labels": {
"type": "object",
"description": "Group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"x-read-only": true,
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Group label for the locale `localeCode`"
}
}
},
"sort_order": {
"type": "integer",
"description": "Order of the attribute in its group",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"localizable": {
"type": "boolean",
"description": "Whether the attribute is localizable, i.e. can have one value by locale",
"default": false,
"x-immutable": true
},
"scopable": {
"type": "boolean",
"description": "Whether the attribute is scopable, i.e. can have one value by channel",
"default": false,
"x-immutable": true
},
"available_locales": {
"type": "array",
"description": "To make the attribute locale specfic, specify here for which locales it is specific",
"x-validation-rules": "Each string of the array is an existing and activated locale",
"items": {
"type": "string"
}
},
"unique": {
"type": "boolean",
"description": "Whether two values for the attribute cannot be the same",
"x-immutable": true
},
"useable_as_grid_filter": {
"type": "boolean",
"description": "Whether the attribute can be used as a filter for the product grid in the PIM user interface"
},
"max_characters": {
"type": "integer",
"description": "Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier` attribute types"
},
"validation_rule": {
"type": "string",
"description": "Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Equal to `regexp` when the attribute type is equal to `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"validation_regexp": {
"type": "string",
"description": "Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Required when the property `validation_rule` is equal to `regexp`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"wysiwyg_enabled": {
"type": "boolean",
"description": "Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`",
"x-warning": "Only for `pim_catalog_textarea` attribute type"
},
"number_min": {
"type": "string",
"description": "Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"number_max": {
"type": "string",
"description": "Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"decimals_allowed": {
"type": "boolean",
"description": "Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"negative_allowed": {
"type": "boolean",
"description": "Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric` or `pim_catalog_number` attribute types"
},
"metric_family": {
"type": "string",
"description": "Metric family when the attribute type is `pim_catalog_metric`",
"x-immutable": true,
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"default_metric_unit": {
"type": "string",
"description": "Default metric unit when the attribute type is `pim_catalog_metric`",
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"date_min": {
"type": "string",
"description": "Minimum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"date_max": {
"type": "string",
"description": "Maximum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"allowed_extensions": {
"type": "array",
"description": "Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types",
"items": {
"type": "string"
}
},
"max_file_size": {
"type": "string",
"description": "Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types"
},
"reference_data_name": {
"type": "string",
"description": "Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`",
"x-validation-rules": "Required only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types",
"x-warning": "Only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types"
},
"default_value": {
"type": "boolean",
"description": "Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)",
"x-warning": "Only for `pim_catalog_boolean` attribute type",
"x-from-version": "5.0"
},
"table_configuration": {
"type": "array",
"description": "Configuration of the Table attribute (columns)",
"x-validation-rules": "Required only for `pim_catalog_table` attribute type",
"x-warning": "Only for `pim_catalog_table` attribute type",
"items": {
"type": "object",
"required": [
"code",
"data_type"
],
"properties": {
"code": {
"type": "string",
"description": "Column code"
},
"data_type": {
"type": "string",
"enum": [
"select",
"text",
"number",
"boolean"
],
"description": "Column data type"
},
"validations": {
"type": "object",
"description": "User defined validation constraints on the cell content",
"default": {},
"properties": {
"min": {
"type": "number",
"description": "minimum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"max": {
"type": "number",
"description": "maximum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"decimals_allowed": {
"type": "boolean",
"description": "whether the value of a numeric cell can hold a decimal part",
"x-validation-rules": "only for `number` data type columns"
},
"max_length": {
"type": "number",
"description": "maximum length of a text cell",
"x-validation-rules": "only for `text` data type columns"
}
}
},
"labels": {
"type": "object",
"description": "Column labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Column label for the locale `localeCode`"
}
}
},
"is_required_for_completeness": {
"type": "boolean",
"description": "Defines if the column should be entirely filled for the attribute to be considered complete",
"x-warning": "This value is always true for the first column in a table configuration",
"default": false
}
}
}
},
"is_main_identifier": {
"type": "boolean",
"description": "Is this attribute main identifier when attribute type is `pim_catalog_identifier`"
}
},
"example": {
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"description\",\"status_code\":201}",
"x-example-2": "{\"line\":2,\"code\":\"short_description\",\"status_code\":422,\"message\":\"Group \"marketig\" does not exist.\"}",
"x-example-3": "{\"line\":3,\"code\":\"release_date\",\"status_code\":204}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/attributes/{code}": {
"get": {
"summary": "Get an attribute",
"operationId": "get_attributes__code_",
"description": "This endpoint allows you to get the information about a given attribute.",
"tags": [
"Attribute"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "with_table_select_options",
"in": "query",
"description": "Return the options of 'select' column types (of a table attribute) in the response. (Only available since the 7.0 version)",
"default": false,
"type": "boolean",
"required": false,
"x-from-version": "7.0"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the attribute in JSON standard format",
"schema": {
"type": "object",
"required": [
"code",
"type",
"group"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute code",
"x-immutable": true
},
"type": {
"type": "string",
"description": "Attribute type. See <a href='/concepts/catalog-structure.html#attribute'>type</a> section for more details.",
"x-validation-rules": "The type is one of the following values",
"enum": [
"pim_catalog_identifier",
"pim_catalog_metric",
"pim_catalog_number",
"pim_catalog_reference_data_multi_select",
"pim_catalog_reference_data_simple_select",
"pim_catalog_simpleselect",
"pim_catalog_multiselect",
"pim_catalog_date",
"pim_catalog_textarea",
"pim_catalog_text",
"pim_catalog_file",
"pim_catalog_image",
"pim_catalog_price_collection",
"pim_catalog_boolean",
"akeneo_reference_entity",
"akeneo_reference_entity_collection",
"pim_catalog_asset_collection"
],
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Attribute labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute label for the locale `localeCode`"
}
}
},
"group": {
"type": "string",
"description": "Attribute group",
"x-validation-rules": "It is the code of an existing group"
},
"group_labels": {
"type": "object",
"description": "Group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"x-read-only": true,
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Group label for the locale `localeCode`"
}
}
},
"sort_order": {
"type": "integer",
"description": "Order of the attribute in its group",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"localizable": {
"type": "boolean",
"description": "Whether the attribute is localizable, i.e. can have one value by locale",
"default": false,
"x-immutable": true
},
"scopable": {
"type": "boolean",
"description": "Whether the attribute is scopable, i.e. can have one value by channel",
"default": false,
"x-immutable": true
},
"available_locales": {
"type": "array",
"description": "To make the attribute locale specfic, specify here for which locales it is specific",
"x-validation-rules": "Each string of the array is an existing and activated locale",
"items": {
"type": "string"
}
},
"unique": {
"type": "boolean",
"description": "Whether two values for the attribute cannot be the same",
"x-immutable": true
},
"useable_as_grid_filter": {
"type": "boolean",
"description": "Whether the attribute can be used as a filter for the product grid in the PIM user interface"
},
"max_characters": {
"type": "integer",
"description": "Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier` attribute types"
},
"validation_rule": {
"type": "string",
"description": "Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Equal to `regexp` when the attribute type is equal to `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"validation_regexp": {
"type": "string",
"description": "Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Required when the property `validation_rule` is equal to `regexp`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"wysiwyg_enabled": {
"type": "boolean",
"description": "Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`",
"x-warning": "Only for `pim_catalog_textarea` attribute type"
},
"number_min": {
"type": "string",
"description": "Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"number_max": {
"type": "string",
"description": "Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"decimals_allowed": {
"type": "boolean",
"description": "Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"negative_allowed": {
"type": "boolean",
"description": "Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric` or `pim_catalog_number` attribute types"
},
"metric_family": {
"type": "string",
"description": "Metric family when the attribute type is `pim_catalog_metric`",
"x-immutable": true,
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"default_metric_unit": {
"type": "string",
"description": "Default metric unit when the attribute type is `pim_catalog_metric`",
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"date_min": {
"type": "string",
"description": "Minimum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"date_max": {
"type": "string",
"description": "Maximum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"allowed_extensions": {
"type": "array",
"description": "Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types",
"items": {
"type": "string"
}
},
"max_file_size": {
"type": "string",
"description": "Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types"
},
"reference_data_name": {
"type": "string",
"description": "Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`",
"x-validation-rules": "Required only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types",
"x-warning": "Only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types"
},
"default_value": {
"type": "boolean",
"description": "Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)",
"x-warning": "Only for `pim_catalog_boolean` attribute type",
"x-from-version": "5.0"
},
"table_configuration": {
"type": "array",
"description": "Configuration of the Table attribute (columns)",
"x-validation-rules": "Required only for `pim_catalog_table` attribute type",
"x-warning": "Only for `pim_catalog_table` attribute type",
"items": {
"type": "object",
"required": [
"code",
"data_type"
],
"properties": {
"code": {
"type": "string",
"description": "Column code"
},
"data_type": {
"type": "string",
"enum": [
"select",
"text",
"number",
"boolean"
],
"description": "Column data type"
},
"validations": {
"type": "object",
"description": "User defined validation constraints on the cell content",
"default": {},
"properties": {
"min": {
"type": "number",
"description": "minimum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"max": {
"type": "number",
"description": "maximum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"decimals_allowed": {
"type": "boolean",
"description": "whether the value of a numeric cell can hold a decimal part",
"x-validation-rules": "only for `number` data type columns"
},
"max_length": {
"type": "number",
"description": "maximum length of a text cell",
"x-validation-rules": "only for `text` data type columns"
}
}
},
"labels": {
"type": "object",
"description": "Column labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Column label for the locale `localeCode`"
}
}
},
"is_required_for_completeness": {
"type": "boolean",
"description": "Defines if the column should be entirely filled for the attribute to be considered complete",
"x-warning": "This value is always true for the first column in a table configuration",
"default": false
}
}
}
},
"is_main_identifier": {
"type": "boolean",
"description": "Is this attribute main identifier when attribute type is `pim_catalog_identifier`"
}
},
"example": {
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create an attribute",
"operationId": "patch_attributes__code_",
"tags": [
"Attribute"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given attribute. Know more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no attribute exists for the given code, it creates it.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code",
"type",
"group"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute code",
"x-immutable": true
},
"type": {
"type": "string",
"description": "Attribute type. See <a href='/concepts/catalog-structure.html#attribute'>type</a> section for more details.",
"x-validation-rules": "The type is one of the following values",
"enum": [
"pim_catalog_identifier",
"pim_catalog_metric",
"pim_catalog_number",
"pim_catalog_reference_data_multi_select",
"pim_catalog_reference_data_simple_select",
"pim_catalog_simpleselect",
"pim_catalog_multiselect",
"pim_catalog_date",
"pim_catalog_textarea",
"pim_catalog_text",
"pim_catalog_file",
"pim_catalog_image",
"pim_catalog_price_collection",
"pim_catalog_boolean",
"akeneo_reference_entity",
"akeneo_reference_entity_collection",
"pim_catalog_asset_collection"
],
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Attribute labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute label for the locale `localeCode`"
}
}
},
"group": {
"type": "string",
"description": "Attribute group",
"x-validation-rules": "It is the code of an existing group"
},
"group_labels": {
"type": "object",
"description": "Group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"x-read-only": true,
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Group label for the locale `localeCode`"
}
}
},
"sort_order": {
"type": "integer",
"description": "Order of the attribute in its group",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"localizable": {
"type": "boolean",
"description": "Whether the attribute is localizable, i.e. can have one value by locale",
"default": false,
"x-immutable": true
},
"scopable": {
"type": "boolean",
"description": "Whether the attribute is scopable, i.e. can have one value by channel",
"default": false,
"x-immutable": true
},
"available_locales": {
"type": "array",
"description": "To make the attribute locale specfic, specify here for which locales it is specific",
"x-validation-rules": "Each string of the array is an existing and activated locale",
"items": {
"type": "string"
}
},
"unique": {
"type": "boolean",
"description": "Whether two values for the attribute cannot be the same",
"x-immutable": true
},
"useable_as_grid_filter": {
"type": "boolean",
"description": "Whether the attribute can be used as a filter for the product grid in the PIM user interface"
},
"max_characters": {
"type": "integer",
"description": "Number maximum of characters allowed for the value of the attribute when the attribute type is `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text`, `pim_catalog_textarea` or `pim_catalog_identifier` attribute types"
},
"validation_rule": {
"type": "string",
"description": "Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Equal to `regexp` when the attribute type is equal to `pim_catalog_identifier`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"validation_regexp": {
"type": "string",
"description": "Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`",
"x-validation-rules": "Required when the property `validation_rule` is equal to `regexp`",
"x-warning": "Only for `pim_catalog_text` or `pim_catalog_identifier` attribute types"
},
"wysiwyg_enabled": {
"type": "boolean",
"description": "Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`",
"x-warning": "Only for `pim_catalog_textarea` attribute type"
},
"number_min": {
"type": "string",
"description": "Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"number_max": {
"type": "string",
"description": "Maximum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"decimals_allowed": {
"type": "boolean",
"description": "Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric`, `pim_catalog_price_collection` or `pim_catalog_number` attribute types"
},
"negative_allowed": {
"type": "boolean",
"description": "Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`",
"x-warning": "Only for `pim_catalog_metric` or `pim_catalog_number` attribute types"
},
"metric_family": {
"type": "string",
"description": "Metric family when the attribute type is `pim_catalog_metric`",
"x-immutable": true,
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"default_metric_unit": {
"type": "string",
"description": "Default metric unit when the attribute type is `pim_catalog_metric`",
"x-validation-rules": "Required for `pim_catalog_metric` attribute type",
"x-warning": "Only for `pim_catalog_metric` attribute type"
},
"date_min": {
"type": "string",
"description": "Minimum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"date_max": {
"type": "string",
"description": "Maximum date allowed when the attribute type is `pim_catalog_date`",
"x-validation-rules": "The datetime format follows the ISO-8601 norm",
"x-warning": "Only for `pim_catalog_date` attribute type",
"format": "date-time"
},
"allowed_extensions": {
"type": "array",
"description": "Extensions allowed when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types",
"items": {
"type": "string"
}
},
"max_file_size": {
"type": "string",
"description": "Max file size in MB when the attribute type is `pim_catalog_file` or `pim_catalog_image`",
"x-warning": "Only for `pim_catalog_file` or `pim_catalog_image` attribute types"
},
"reference_data_name": {
"type": "string",
"description": "Reference entity code when the attribute type is `akeneo_reference_entity` or `akeneo_reference_entity_collection` OR Asset family code when the attribute type is `pim_catalog_asset_collection`",
"x-validation-rules": "Required only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types",
"x-warning": "Only for `akeneo_reference_entity` or `akeneo_reference_entity_collection` or `pim_catalog_asset_collection` attribute types"
},
"default_value": {
"type": "boolean",
"description": "Default value for a Yes/No attribute, applied when creating a new product or product model (only available since the 5.0)",
"x-warning": "Only for `pim_catalog_boolean` attribute type",
"x-from-version": "5.0"
},
"table_configuration": {
"type": "array",
"description": "Configuration of the Table attribute (columns)",
"x-validation-rules": "Required only for `pim_catalog_table` attribute type",
"x-warning": "Only for `pim_catalog_table` attribute type",
"items": {
"type": "object",
"required": [
"code",
"data_type"
],
"properties": {
"code": {
"type": "string",
"description": "Column code"
},
"data_type": {
"type": "string",
"enum": [
"select",
"text",
"number",
"boolean"
],
"description": "Column data type"
},
"validations": {
"type": "object",
"description": "User defined validation constraints on the cell content",
"default": {},
"properties": {
"min": {
"type": "number",
"description": "minimum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"max": {
"type": "number",
"description": "maximum value of a numeric cell",
"x-validation-rules": "only for `number` data type columns"
},
"decimals_allowed": {
"type": "boolean",
"description": "whether the value of a numeric cell can hold a decimal part",
"x-validation-rules": "only for `number` data type columns"
},
"max_length": {
"type": "number",
"description": "maximum length of a text cell",
"x-validation-rules": "only for `text` data type columns"
}
}
},
"labels": {
"type": "object",
"description": "Column labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Column label for the locale `localeCode`"
}
}
},
"is_required_for_completeness": {
"type": "boolean",
"description": "Defines if the column should be entirely filled for the attribute to be considered complete",
"x-warning": "This value is always true for the first column in a table configuration",
"default": false
}
}
}
},
"is_main_identifier": {
"type": "boolean",
"description": "Is this attribute main identifier when attribute type is `pim_catalog_identifier`"
}
},
"example": {
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/attributes/{attribute_code}/options": {
"get": {
"summary": "Get list of attribute options",
"operationId": "get_attributes__attribute_code__options",
"description": "This endpoint allows you to get a list of attribute options. Attribute options are paginated and sorted by code.",
"tags": [
"Attribute option"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "attribute_code",
"in": "path",
"description": "Code of the attribute",
"required": true,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return attribute options paginated",
"schema": {
"title": "Attribute Options",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Code of option"
},
"attribute": {
"type": "string",
"description": "Code of attribute related to the attribute option",
"x-validation-rules": "It is the same attribute code as the one given as path parameter"
},
"sort_order": {
"type": "integer",
"description": "Order of attribute option",
"x-validation-rules": "It is a positive integer"
},
"labels": {
"type": "object",
"description": "Attribute option labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute option label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=3&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=1&limit=3"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=2&limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=4&limit=3"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/red"
}
},
"code": "red",
"attribute": "a_simple_select",
"sort_order": 1,
"labels": {
"en_US": "Red",
"fr_FR": "Rouge"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/black"
}
},
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/purple"
}
},
"code": "purple",
"attribute": "a_simple_select",
"sort_order": 3,
"labels": {
"en_US": "Purple",
"fr_FR": "Violet"
}
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new attribute option",
"operationId": "post_attributes__attribute_code__options",
"description": "This endpoint allows you to create a new attribute option.",
"tags": [
"Attribute option"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "attribute_code",
"in": "path",
"description": "Code of the attribute",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Code of option"
},
"attribute": {
"type": "string",
"description": "Code of attribute related to the attribute option",
"x-validation-rules": "It is the same attribute code as the one given as path parameter"
},
"sort_order": {
"type": "integer",
"description": "Order of attribute option",
"x-validation-rules": "It is a positive integer"
},
"labels": {
"type": "object",
"description": "Attribute option labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute option label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several attribute options",
"operationId": "patch_attributes__attribute_code__options",
"tags": [
"Attribute option"
],
"x-versions": [
"2.1",
"2.2",
"2.3",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update several attribute options at once.",
"x-body-by-line": "Contains several lines, each line is an attribute option in JSON standard format",
"parameters": [
{
"name": "attribute_code",
"in": "path",
"description": "Code of the attribute",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\":\"black\", \"attribute\":\"a_simple_select\", \"labels\":{\"en_US\": \"Black\",\"fr_FR\": \"Noir\"}}",
"x-example-2": "{\"code\":\"red\", \"label\":{\"en_US\": \"Red\",\"fr_FR\": \"Rouge\"}}",
"x-example-3": "{\"code\":\"yellow\", \"labels\":{\"en_US\": \"Yellow\",\"fr_FR\": \"Jaune\"}}"
},
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Code of option"
},
"attribute": {
"type": "string",
"description": "Code of attribute related to the attribute option",
"x-validation-rules": "It is the same attribute code as the one given as path parameter"
},
"sort_order": {
"type": "integer",
"description": "Order of attribute option",
"x-validation-rules": "It is a positive integer"
},
"labels": {
"type": "object",
"description": "Attribute option labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute option label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"x-no-entity": true,
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"black\",\"status_code\":201}",
"x-example-2": "{\"line\":2,\"code\":\"red\",\"status_code\":422,\"message\":\"Property \"label\" does not exist. Check the API format documentation.\"}",
"x-example-3": "{\"line\":3,\"code\":\"yellow\",\"status_code\":204}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/attributes/{attribute_code}/options/{code}": {
"get": {
"summary": "Get an attribute option",
"operationId": "get_attributes__attribute_code__options__code_",
"description": "This endpoint allows you to get the information about a given attribute option.",
"tags": [
"Attribute option"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "attribute_code",
"in": "path",
"description": "Code of the attribute",
"required": true,
"type": "string"
},
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the attribute option in JSON standard format",
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Code of option"
},
"attribute": {
"type": "string",
"description": "Code of attribute related to the attribute option",
"x-validation-rules": "It is the same attribute code as the one given as path parameter"
},
"sort_order": {
"type": "integer",
"description": "Order of attribute option",
"x-validation-rules": "It is a positive integer"
},
"labels": {
"type": "object",
"description": "Attribute option labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute option label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create an attribute option",
"operationId": "patch_attributes__attribute_code__options__code_",
"tags": [
"Attribute option"
],
"x-versions": [
"1.7",
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given attribute option. Know more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no attribute option exists for the given code, it creates it.",
"parameters": [
{
"name": "attribute_code",
"in": "path",
"description": "Code of the attribute",
"required": true,
"type": "string"
},
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Code of option"
},
"attribute": {
"type": "string",
"description": "Code of attribute related to the attribute option",
"x-validation-rules": "It is the same attribute code as the one given as path parameter"
},
"sort_order": {
"type": "integer",
"description": "Order of attribute option",
"x-validation-rules": "It is a positive integer"
},
"labels": {
"type": "object",
"description": "Attribute option labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute option label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/attribute-groups": {
"get": {
"summary": "Get list of attribute groups",
"operationId": "attribute_groups_get_list",
"description": "This endpoint allows you to get a list of attribute groups. Attribute groups are paginated and sorted by code.",
"tags": [
"Attribute group"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "search",
"in": "query",
"description": "Filter attribute groups, for more details see the <a href=\"/documentation/filter.html#filter-attribute-groups\">Filters</a> section.",
"required": false,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return attribute groups paginated",
"schema": {
"title": "Attribute groups",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute group code",
"x-immutable": true
},
"sort_order": {
"type": "integer",
"description": "Attribute group order among other attribute groups",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"attributes": {
"type": "array",
"description": "Attribute codes that compose the attribute group",
"x-validation-rules": "Each string of the array is an existing attribute code, an attribute can only be in one attribute group",
"items": {
"type": "string"
},
"default": []
},
"labels": {
"type": "object",
"description": "Attribute group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute group label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=3&limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=1&limit=2"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=2&limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=4&limit=2"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/marketing"
}
},
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/technical"
}
},
"code": "technical",
"sort_order": 5,
"attributes": [
"weight",
"maximum_scan_size",
"color_scanning",
"power_requirements",
"maximum_print_size",
"sensor_type",
"total_megapixels",
"optical_zoom",
"camera_type"
],
"labels": {
"en_US": "Technical",
"fr_FR": "Technique"
}
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new attribute group",
"operationId": "attribute_groups_post",
"description": "This endpoint allows you to create a new attribute group.",
"tags": [
"Attribute group"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute group code",
"x-immutable": true
},
"sort_order": {
"type": "integer",
"description": "Attribute group order among other attribute groups",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"attributes": {
"type": "array",
"description": "Attribute codes that compose the attribute group",
"x-validation-rules": "Each string of the array is an existing attribute code, an attribute can only be in one attribute group",
"items": {
"type": "string"
},
"default": []
},
"labels": {
"type": "object",
"description": "Attribute group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute group label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update/create several attribute groups",
"operationId": "several_attribute_groups_patch",
"tags": [
"Attribute group"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update and/or create several attribute groups at once.",
"x-body-by-line": "Contains several lines, each line is an attribute group in JSON standard format",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"x-examples": {
"x-example-1": "{\"code\":\"technical\",\"labels\":{\"en_US\": \"Technical\", \"fr_FR\": \"Technique\"}}",
"x-example-2": "{\"code\":\"marketing\",\"type\":\"bar\"}",
"x-example-3": "{\"code\":\"design\",\"sort_order\":7}"
},
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute group code",
"x-immutable": true
},
"sort_order": {
"type": "integer",
"description": "Attribute group order among other attribute groups",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"attributes": {
"type": "array",
"description": "Attribute codes that compose the attribute group",
"x-validation-rules": "Each string of the array is an existing attribute code, an attribute can only be in one attribute group",
"items": {
"type": "string"
},
"default": []
},
"labels": {
"type": "object",
"description": "Attribute group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute group label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns a plain text response whose lines are JSON containing the status of each update or creation",
"schema": {
"type": "object",
"properties": {
"line": {
"type": "integer",
"description": "Line number"
},
"identifier": {
"type": "string",
"description": "Resource identifier, only filled when the resource is a product"
},
"code": {
"type": "string",
"description": "Resource code, only filled when the resource is not a product"
},
"status_code": {
"type": "integer",
"description": "HTTP status code, see <a href=\"/documentation/responses.html#client-errors\">Client errors</a> to understand the meaning of each code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"x-example-1": "{\"line\":1,\"code\":\"technical\",\"status_code\":201}",
"x-example-2": "{\"line\":2,\"code\":\"marketing\",\"status_code\":422,\"message\":\"Property \\\"type\\\" does not exist. Check the standard format documentation.\",\"_links\":{\"documentation\":{\"href\":\"http:\\/\\/api.akeneo.com\\/api-reference.html#patch_attribute_groups__code_\"}",
"x-example-3": "{\"line\":3,\"code\":\"design\",\"status_code\":204}"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"413": {
"description": "Request Entity Too Large",
"x-details": "There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/vnd.akeneo.collection+json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/vnd.akeneo.collection+json’ is allowed."
}
}
}
}
},
"/api/rest/v1/attribute-groups/{code}": {
"get": {
"summary": "Get an attribute group",
"operationId": "attribute_groups_get",
"description": "This endpoint allows you to get the information about a given attribute group.",
"tags": [
"Attribute group"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"x-details": "Returns the content of the attribute group in JSON standard format",
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute group code",
"x-immutable": true
},
"sort_order": {
"type": "integer",
"description": "Attribute group order among other attribute groups",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"attributes": {
"type": "array",
"description": "Attribute codes that compose the attribute group",
"x-validation-rules": "Each string of the array is an existing attribute code, an attribute can only be in one attribute group",
"items": {
"type": "string"
},
"default": []
},
"labels": {
"type": "object",
"description": "Attribute group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute group label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"404": {
"description": "Resource not found",
"x-details": "The resource code given in the URI does not correspond to any existing PIM resource",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"patch": {
"summary": "Update/create an attribute group",
"operationId": "attribute_groups_patch",
"tags": [
"Attribute group"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"description": "This endpoint allows you to update a given attribute group. Know more about <a href=\"/documentation/update.html#update-behavior\">Update behavior</a>. Note that if no attribute group exists for the given code, it creates it.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "Code of the resource",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Attribute group code",
"x-immutable": true
},
"sort_order": {
"type": "integer",
"description": "Attribute group order among other attribute groups",
"x-validation-rules": "It is a positive integer",
"default": 0
},
"attributes": {
"type": "array",
"description": "Attribute codes that compose the attribute group",
"x-validation-rules": "Each string of the array is an existing attribute code, an attribute can only be in one attribute group",
"items": {
"type": "string"
},
"default": []
},
"labels": {
"type": "object",
"description": "Attribute group labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Attribute group label for the locale `localeCode`"
}
}
}
},
"example": {
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"204": {
"description": "No content to return",
"x-details": "Means that the update was successful",
"headers": {
"Location": {
"description": "URI of the updated resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘application/json’ is allowed."
}
},
"422": {
"description": "Unprocessable entity",
"x-details": "The validation of the entity given in the body of the request failed",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"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"
}
}
}
}
}
}
},
"/api/rest/v1/association-types": {
"get": {
"summary": "Get a list of association types",
"operationId": "association_types_get_list",
"description": "This endpoint allows you to get a list of association types. Association types are paginated and sorted by code.",
"tags": [
"Association type"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "Number of the page to retrieve when using the `page` pagination method type. <strong>Should never be set manually</strong>, see <a href=\"/documentation/pagination.html#pagination\">Pagination</a> section",
"required": false,
"type": "integer",
"default": 1
},
{
"name": "limit",
"in": "query",
"description": "Number of results by page, see <a href=\"/documentation/pagination.html\">Pagination</a> section",
"required": false,
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
{
"name": "with_count",
"in": "query",
"description": "Return the count of items in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way",
"default": false,
"type": "boolean",
"required": false
}
],
"responses": {
"200": {
"description": "Return association types paginated",
"schema": {
"title": "Association types",
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the current page of resources"
}
}
},
"first": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the first page of resources"
}
}
},
"previous": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the previous page of resources"
}
}
},
"next": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the next page of resources"
}
}
}
}
},
"current_page": {
"type": "integer",
"description": "Current page number"
}
}
},
{
"properties": {
"_embedded": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of the resource"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Association type code",
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Association type labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Association type label for the locale `localeCode`"
}
}
},
"is_quantified": {
"type": "boolean",
"description": "When true, the association is a quantified association (Only available in the PIM Serenity version.)",
"default": false,
"x-immutable": true
},
"is_two_way": {
"type": "boolean",
"description": "When true, the association is a two-way association (Only available in the PIM Serenity version.)",
"default": false,
"x-immutable": true
}
},
"example": {
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}
}
]
}
}
}
}
}
}
]
},
"examples": {
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/X_SELL"
}
},
"code": "X_SELL",
"labels": {
"en_US": "Cross sell",
"fr_FR": "Vente croisée"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/UPSELL"
}
},
"code": "UPSELL",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/SUBSTITUTION"
}
},
"code": "SUBSTITUTION",
"labels": {
"en_US": "Substitution",
"fr_FR": "Remplacement"
},
"is_quantified": false,
"is_two_way": false
}
]
}
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"406": {
"description": "Not Acceptable",
"x-details": "The `Accept` header is not `application/json` but it should",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 406,
"message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
}
}
}
},
"post": {
"summary": "Create a new association type",
"operationId": "association_types_post",
"description": "This endpoint allows you to create a new association type.",
"tags": [
"Association type"
],
"x-versions": [
"2.x",
"3.x",
"4.0",
"5.0",
"6.0",
"7.0",
"SaaS"
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Association type code",
"x-immutable": true
},
"labels": {
"type": "object",
"description": "Association type labels for each locale",
"x-validation-rules": "The `localeCode` is the code of an existing and activated locale",
"default": {},
"properties": {
"localeCode": {
"type": "string",
"description": "Association type label for the locale `localeCode`"
}
}
},
"is_quantified": {
"type": "boolean",
"description": "When true, the association is a quantified association (Only available in the PIM Serenity version.)",
"default": false,
"x-immutable": true
},
"is_two_way": {
"type": "boolean",
"description": "When true, the association is a two-way association (Only available in the PIM Serenity version.)",
"default": false,
"x-immutable": true
}
},
"example": {
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}
}
}
],
"responses": {
"201": {
"description": "Created",
"x-details": "Means that the creation was successful",
"headers": {
"Location": {
"description": "URI of the created resource",
"type": "string"
}
}
},
"400": {
"description": "Bad request",
"x-details": "Can be caused by a malformed JSON request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 400,
"message": "Invalid JSON message received"
}
},
"401": {
"description": "Authentication required",
"x-details": "Can be caused by a missing or expired token",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 401,
"message": "Authentication is required"
}
},
"403": {
"description": "Access forbidden",
"x-details": "The user does not have the permission to execute this request",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 403,
"message": "Access forbidden. You are not allowed to list categories."
}
},
"415": {
"description": "Unsupported Media type",
"x-details": "The `Content-type` header has to be `application/json`",
"schema": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "HTTP status code"
},
"message": {
"type": "string",
"description": "Message explaining the error"
}
}
},
"examples": {
"code": 415,
"message": "‘xxx’ in ‘Content-type’ header is not valid. Only ‘applicatio
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment