REST API reference
Complete reference on how to handle Akeneo PIM resources
Products
Product [uuid]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
search
(string)
• Filter products, for more details see the Filters section
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• Cursor when using the search_after pagination method type.
It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets.
Should never be set manually, see Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert measurement attribute values to the appropriate unit for the channel provided by the scope parameter.
When set to true, the scope parameter is required.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_root_parent
(boolean)
• Return the root parent product model code of a variant in the response.
When set to true, the response will include the root parent product model code for each variant product.
This is useful for understanding the hierarchical relationship between product variants and their parent models, which is essential for product catalog navigation.
If set to false, the response will not include parent model information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
root_parent (string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness (object)
: {
aggregated_scores_by_scope (array [object])
• Aggregated readiness score per channel: the average of the per-locale scores within each
readiness, then averaged across the readiness configurations that apply to that channel
(equal weight) and rounded.
: [
{
scope
(string) • Channel code for which the aggregated readiness score is calculated
score
(integer) • Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale (object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"family": "caps",
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "cap",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"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
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"family": null,
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"winter_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "sweat",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
]
},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": [],
"completenesses": [],
"workflow_execution_statuses": []
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product
This endpoint allows you to create a new product. 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.
REQUEST
post /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Body contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
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": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. 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.
REQUEST
patch /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product in JSON standard format. Modifications to existing products can be specified using additional keys such as `add_categories` and `remove_categories`.
{
uuid
(string)
• Product UUID
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.d
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
{"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","values":{"sku":[{"data":"updated_sku","locale":null,"scope":null}]}, "group":["promotion"]}
{"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","values":{"sku":[{"data":"new_product","locale":null,"scope":null}]},"family":"clothes"}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
uuid
(string)
• Product uuid
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","status_code":204}
{"line":2,"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","status_code":201}
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Search list of products
This endpoint allows you to search for products that match the filters provided in the request body. Products are paginated and can be filtered by scope, locales, attributes, and other criteria. User-group-based permissions are applied to the products you request.
Important limitations
- The maximum number of attributes in the request body is 800.
- The maximum number of search criteria is 20.
- The maximum number of items in an array (e.g., values for filters like
INorNOT IN) is 800.
REQUEST
post /api/rest/v1/products-uuid/search
Path parameters
Ø
Query parameters
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• Cursor when using the search_after pagination method type.
It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets.
Should never be set manually, see Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
search
(string)
• Stringified JSON to filter products,
for more details see the Filters section.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes,
for more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes,
for more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes,
for more details see the Filter product values via attributes section.
convert_measurements
(boolean,
false by default)
• Convert measurement attribute values to the appropriate unit for the channel provided by the "scope" parameter.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Whether to return asset collection share link URLs in the response.
See the linked_data format for more details.
with_quality_scores__products
(boolean)
• Return product quality scores in the response
with_readiness
(string)
• Return product readiness in the response.
scores_only returns percentage scores only; detailed also returns unmet requirements.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_completenesses
(boolean)
• Return product completenesses in the response
with_workflow_execution_statuses
(boolean)
• Return an array of workflow_execution_statuses in the response
}
Example
{
"scope": "ecommerce",
"locales": "en_US",
"search": "{\"completeness\":[{\"operator\": \"=\",\"value\": 100,\"scope\":\"ecommerce\"}]}",
"attributes": "description, name",
"with_attribute_options": false,
"with_asset_share_links": true,
"with_quality_scores__products": true,
"with_completenesses": true
}RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
root_parent (string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness (object)
: {
aggregated_scores_by_scope (array [object])
• Aggregated readiness score per channel: the average of the per-locale scores within each
readiness, then averaged across the readiness configurations that apply to that channel
(equal weight) and rounded.
: [
{
scope
(string) • Channel code for which the aggregated readiness score is calculated
score
(integer) • Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale (object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"family": "caps",
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "cap",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"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
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"family": null,
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"winter_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "sweat",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
]
},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": [],
"completenesses": [],
"workflow_execution_statuses": []
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a product
This endpoint allows you to get the information about a given product. Permissions based on your user groups are applied to the product you request.
REQUEST
get /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_root_parent
(boolean)
• Return the root parent product model code of a variant in the response.
When set to true, the response will include the root parent product model code for each variant product.
This is useful for understanding the hierarchical relationship between product variants and their parent models, which is essential for product catalog navigation.
If set to false, the response will not include parent model information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
root_parent
(string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Enterprise 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.
REQUEST
patch /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
update_parent_values
(boolean)
• When set to true, allows updating attribute values on the parent product models when patching a variant product.
By default, only values owned by the variant product level can be updated.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.d
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the request was successful and that there is no content to return. It is typically used in response to a successful update operation where the server does not need to return any data to the client.
Headers
Location • URI of the updated resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product
This endpoint allows you to delete a given product. Permissions based on your user groups are applied to the product you try to delete.
REQUEST
delete /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a draft for approval
REQUEST
post /api/rest/v1/products-uuid/{uuid}/proposal
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft
This endpoint allows you to get the information about a given draft
REQUEST
get /api/rest/v1/products-uuid/{uuid}/draft
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
root_parent
(string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product [identifier]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/products
Path parameters
Ø
Query parameters
search
(string)
• Filter products,
for more details see the Filters section.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• Cursor when using the search_after pagination method type.
It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets.
Should never be set manually, see Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert measurement attribute values to the appropriate unit for the channel provided by the scope parameter.
When set to true, the scope parameter is required.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified.
• Codes of the categories in which the product is classified.
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness (object)
: {
aggregated_scores_by_scope (array [object])
• Aggregated readiness score per channel: the average of the per-locale scores within each
readiness, then averaged across the readiness configurations that apply to that channel
(equal weight) and rounded.
: [
{
scope
(string) • Channel code for which the aggregated readiness score is calculated
score
(integer) • Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale (object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"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
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/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,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"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
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/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": [],
"workflow_execution_statuses": []
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product
This endpoint allows you to create a new product. Permissions based on your user groups are applied to the product you try to create.
REQUEST
post /api/rest/v1/products
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Body contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product. by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
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": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"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
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. 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.
REQUEST
patch /api/rest/v1/products
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product model in JSON standard format. Modifications to existing product models can be specified using additional keys such as `add_categories` and `remove_categories`.
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"line":1,"identifier":"cap","status_code":204}
{"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"identifier":"tshirt","status_code":201}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
identifier
(string)
• Product identifier
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"identifier":"cap","status_code":204}
{"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"identifier":"tshirt","status_code":201}
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a product
This endpoint allows you to get the information about a given product. Permissions based on your user groups are applied to the product you request.
REQUEST
get /api/rest/v1/products/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified.
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"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
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. In the Enterprise 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.
REQUEST
patch /api/rest/v1/products/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
update_parent_values
(boolean)
• When set to true, allows updating attribute values on the parent product models when patching a variant product.
By default, only values owned by the variant product level can be updated.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"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
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the request was successful and that there is no content to return. It is typically used in response to a successful update operation where the server does not need to return any data to the client.
Headers
Location • URI of the updated resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product
This endpoint allows you to delete a given product. Permissions based on your user groups are applied to the product you try to delete.
REQUEST
delete /api/rest/v1/products/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a draft for approval.
REQUEST
post /api/rest/v1/products/{code}/proposal
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft
This endpoint allows you to get the information about a given draft.
REQUEST
get /api/rest/v1/products/{code}/draft
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified.
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"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
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product model
Get list of product models
This endpoint allows you to get a list of product models. Product models are paginated. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/product-models
Path parameters
Ø
Query parameters
search
(string)
• Filter product models,
for more details see the Filters.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• Cursor when using the search_after pagination method type.
It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets.
Should never be set manually, see Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert measurement attribute values to the appropriate unit for the channel provided by the scope parameter.
When set to true, the scope parameter is required.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product model quality scores in the response.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return product models paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Product model code
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant (string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent (string,null)
• Code of the parent product model when the product is a variant
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
readiness (object)
: {
aggregated_scores_by_scope (array [object])
• Aggregated readiness score per channel: the average of the per-locale scores within each
readiness, then averaged across the readiness configurations that apply to that channel
(equal weight) and rounded.
: [
{
scope
(string) • Channel code for which the aggregated readiness score is calculated
score
(integer) • Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale (object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=2&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=1&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=1&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=3&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
}
},
"current_page": 1,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/amarisshoe"
}
},
"code": "amarisshoe",
"family": "shoes",
"family_variant": "shoes_VariantA1",
"categories": [
"clothing",
"shoes"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like shoes!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"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"
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/Abiloitshirt"
}
},
"code": "Abiloitshirt",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"categories": [
"clothing",
"tshirt"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like tshirt!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"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"
}
],
"workflow_execution_statuses": [],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/Astertrousers"
}
},
"code": "Astertrousers",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"categories": [
"clothing",
"trousers"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like trousers!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"workflow_execution_statuses": [],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a new product model
This endpoint allows you to create a new product model. Permissions based on your user groups are applied to the product model you try to create.
REQUEST
post /api/rest/v1/product-models
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Body contains complex objects not visible here. Consult the static documentation for more details
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null
}
],
"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": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several product models
This endpoint allows you to update and/or create several product models at once. Learn more about Update behavior. Note that if no product models exists for the given code, it creates it. 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.
REQUEST
patch /api/rest/v1/product-models
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product model in JSON standard format. Modifications to existing product models can be specified using additional keys such as `add_categories` and `remove_categories`.
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product model.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product model.
Other categories will be preserved.
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product model regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"code": "sub_sweat_option_a", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code": "sub_sweat_option_b", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code":"tshirt", "parent": "root_tshirt", "family_variant":"clothesvariant","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing tshirt"}]}}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"sub_sweat_option_a","status_code":204}
{"line":2,"code":"sub_sweat_option_b","status_code":422,"message":"Validation failed.","errors":[{"property":"attribute","message":"Cannot set value \"Option A\" for the attribute axis \"a_simple_select\", as another sibling entity already has this value"}]}
{"line":3,"code":"tshirt","status_code":201}
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a product model
This endpoint allows you to get the information about a given product model. Permissions based on your user groups are applied to the product model you request.
REQUEST
get /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_enabled_assets_only
(boolean)
• When set to true, disabled assets are excluded from asset collection values in the response.
Only assets with status: "enabled" are returned.
When set to false (default), all assets are returned regardless of their status.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_readiness
(string)
• Return readiness information in the response.
scores_only: include readiness percentage scores only.detailed: include readiness percentage scores together with the list of unmet requirements. When omitted, no readiness information is returned.
Readiness is currently in beta and is available by request only. If you would like to participate, please reach out to your Customer Success Manager.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
convert_measurements
(boolean)
• Convert measurement attribute values to the appropriate unit for the channel provided by the scope parameter.
When set to true, the scope parameter is required.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product model in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
code
(string)
• Product model code
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string,null)
• Code of the parent product model when the product is a variant
categories
(array [string])
• Codes of the categories in which the product is classified
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"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"
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create a product model
This endpoint allows you to update a given product model. Learn more about Update behavior. Note that if no product model exists for the given code, it creates it. 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.
REQUEST
patch /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product model.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product model.
Other categories will be preserved.
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product model regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"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"
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the request was successful and that there is no content to return. It is typically used in response to a successful update operation where the server does not need to return any data to the client.
Headers
Location • URI of the updated resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a product model
This endpoint allows you to delete a given product model. All its children, product models and variant products, will be also deleted. Permissions based on your connection user group are applied to the product model you try to delete.
REQUEST
delete /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a product model draft for approval
REQUEST
post /api/rest/v1/product-models/{code}/proposal
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a draft
This endpoint allows you to get the information about a given product model draft
REQUEST
get /api/rest/v1/product-models/{code}/draft
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product model in JSON standard format
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
code
(string)
• Product model code
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string,null)
• Code of the parent product model when the product is a variant
categories
(array [string])
• Codes of the categories in which the product is classified
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
readiness
(object)
: {
aggregated_scores_by_scope
(array[object])
: [
{
scope (string
)
• Channel code for which the aggregated readiness score is calculated
score (integer
)
• Aggregated readiness percentage score (0-100) for the given channel
}
]
scores_by_scope_and_locale
(object)
• Readiness scores grouped by readiness code, for each channel/locale combination
}
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"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"
}
],
"readiness": {
"aggregated_scores_by_scope": [
{
"scope": "ecommerce",
"score": 88
}
],
"scores_by_scope_and_locale": {
"camcorders_ecommerce": [
{
"scope": "ecommerce",
"locale": "en_US",
"score": 75,
"unmet_requirements": [
{
"field": "name",
"operator": "NOT EMPTY",
"value": null
}
]
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"score": 100,
"unmet_requirements": []
}
]
}
},
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product media file
Get a list of product media files
This endpoint allows you to get a list of media files that are used as attribute values in products or product models
REQUEST
get /api/rest/v1/media-files
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return media files paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the media file
}
}
_links (object)
: {
download (object)
: {
href
(string) • URI to download the binaries of the media file
}
}
code (string)
• Media file code
original_filename (string)
• Original filename of the media file
mime_type (string)
• Mime type of the media file
size (integer)
• Size of the media file
extension (string)
• Extension of the media file
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"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"
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new product media file
This endpoint allows you to create a new media file and associate it to an attribute value of a given product or product model
REQUEST
post /api/rest/v1/media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-Type
• Equal to 'multipart/form-data' (with boundary value), no other value allowed.
Body
Given as form-data
product
(string,null)
• 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.
RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Get a product media file
This endpoint allows you to get the information about a given media file that is used as an attribute value of a product or a product model.
REQUEST
get /api/rest/v1/media-files/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the media file in JSON standard format
Body Format application/json
{
_links
(object)
: {
download
(object)
: {
href
(string)
• URI to download the binaries of the media file
}
}
code
(string)
• Media file code
original_filename
(string)
• Original filename of the media file
mime_type
(string)
• Mime type of the media file
size
(integer)
• Size of the media file
extension
(string)
• Extension of the media file
}
Example
{
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Download a product media file
This endpoint allows you to download a given media file that is used as an attribute value of a product or a product model
REQUEST
get /api/rest/v1/media-files/{code}/download
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
Returns the binary of the media file
Body Format Mime-type of the media file
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format Mime-type of the media file
This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format Mime-type of the media file
This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format Mime-type of the media file
Jobs
Jobs
Launch export job by code
This endpoint allows you to launch an export job by code
REQUEST
post /api/rest/v1/jobs/export/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the execution ID for the launched job
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
job_execution_id
(integer)
• The ID of the job execution that was launched (integer format)
}
Example
{
"job_execution_id": 12345
}This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Launch import job by code
This endpoint allows you to launch an import job by code
REQUEST
post /api/rest/v1/jobs/import/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
import_mode
(string)
• Change the import mode for this job by overriding the profile value.
Available values are: create_only, update_only and create_or_update.
}
Example
RESPONSES
Returns the execution ID for the launched job
Body Format application/json
Response contains complex objects not visible here. Consult the static documentation for more details
{
job_execution_id
(integer)
• The ID of the job execution that was launched (integer format)
}
Example
{
"job_execution_id": 12345
}This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Catalog structure
Family
Get list of families
This endpoint allows you to get a list of families. Families are paginated and sorted by code.
REQUEST
get /api/rest/v1/families
Path parameters
Ø
Query parameters
search
(string)
• The search query parameter allows you to filter families based on specific criteria.
For more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return family variants paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Family code
attribute_as_label (string)
• Attribute code used as label
attribute_as_image (string,null)
• Attribute code used as the main picture in the user interface
attributes (array [string])
• Attribute codes that compose the family
• Attribute codes that compose the family
attribute_requirements (object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Family label for the specified locale
}
parent (string,null)
• The parent family code. If the family has no parent, this field is null
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=2&limit=2&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=3&limit=2&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_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"
},
"parent": null
},
{
"_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"
},
"parent": "accessories"
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new family
This endpoint allows you to create a new family
REQUEST
post /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-Type
• This header indicates the media type of the resource being sent to the server.
It is used to specify the format of the request body, allowing the server to correctly interpret the data being sent.
Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed.
Body
Follow the standard format of the entity
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"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"
},
"parent": null
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several families
This endpoint allows you to update and/or create several families at once
REQUEST
patch /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{ "code": "tshirt","attribute_as_label": "description","attributes": [ "description","size" ] }
{ "code": "cap","attribute_as_label": "descripion" }
{ "code": "mug","attributes": [ "description","short_description" ] }
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"camcorders","status_code":201}
{"line":2,"code":"cap","status_code":422,"message":"Attribute \"descripion\" does not exist."}
{"line":3,"code":"clothes","status_code":204}
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a family
This endpoint allows you to get the information about a given family
REQUEST
get /api/rest/v1/families/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the family in JSON standard format
Body Format application/json
{
code
(string)
• Family code
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array [string])
• Attribute codes that compose the family
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale
}
parent
(string,null)
• The parent family code. If the family has no parent, this field is null
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"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"
},
"parent": null
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a family
This endpoint allows you to update a given family. Know more about Update behavior. Note that if no family exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/families/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-Type
• This header indicates the media type of the resource being sent to the server.
It is used to specify the format of the request body, allowing the server to correctly interpret the data being sent.
Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed.
Body
Follow the standard format of the entity
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"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"
},
"parent": null
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Delete a family
This endpoint allows you to delete a given family. A family can only be deleted if it has no products, no family variants, and is not a parent of other families.
REQUEST
delete /api/rest/v1/families/{code}
Path parameters
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}The family cannot be deleted because it is still in use.
This error is returned when at least one of the following conditions is true:
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining why the family cannot be deleted
}
Example
{
"code": 422,
"message": "Family \"my_family\" could not be removed as it still has products"
}Family variant
Get list of family variants
This endpoint allows you to get a list of family variants. Family variants are paginated and sorted by code.
REQUEST
get /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return family variants paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Family variant code
common_attributes (array [string])
• Codes of attributes that are common to all variants (not specific to any enrichment level)
• Codes of attributes that are common to all variants (not specific to any enrichment level)
variant_attribute_sets (array [object])
: [
{
level (integer) • Enrichment level
axes (array [string]) • Codes of attributes used as variant axes
attributes (array [string]) • Codes of attributes bind to this enrichment level
}
]
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Family variant label for the specified locale
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=2&limit=10&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=1&limit=10&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=1&limit=10&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=3&limit=10&with_count=true"
}
},
"current_page": 1,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants/shoesVariant"
}
},
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"common_attributes": [
"name",
"description",
"image"
],
"variant_attribute_sets": [
{
"level": 1,
"axes": [
"color"
],
"attributes": [
"color",
"material"
]
},
{
"level": 2,
"axes": [
"size"
],
"attributes": [
"sku",
"size"
]
}
]
}
]
}
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new family variant
This endpoint allows you to create a family variant
REQUEST
post /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several family variants
This endpoint allows you to update and/or create several family variants at once
REQUEST
patch /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{"code": "shoes_by_size", "variant_attribute_sets": [{"level": 1, "axes": ["size"], "attributes": ["color"]}]}
{"code": "shoes_by_color","labels": {"en_US": "Shoes by color"}}
{"code": "shoes_without_axes", "variant_attribute_sets": [{"level": 1, "axes": [], "attributes": ["color"]}]}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"shoes_by_size","status_code":201}
{"line":2,"code":"shoes_by_color","status_code":204}
{"line":3,"code":"mug","status_code":422, "message":"There should be at least one attribute defined as axis for the attribute set for level \"1\""}
This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a family variant
This endpoint allows you to get the information about a given family variant
REQUEST
get /api/rest/v1/families/{family_code}/variants/{code}
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the family variant in JSON standard format
Body Format application/json
{
code
(string)
• Family variant code
common_attributes
(array [string])
• Codes of attributes that are common to all variants (not specific to any enrichment level)
variant_attribute_sets
(array [object])
: [
{
level (integer) • Enrichment level
axes (array) • Codes of attributes used as variant axes
attributes (array) • Codes of attributes bind to this enrichment level
}
]
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"common_attributes": [
"name",
"description"
],
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request's Accept header.
It is typically used when the requested resource is not available in the requested format.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a family variant
This endpoint allows you to update a given family variant. Know more about Update behavior. Note that if no family variant exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/families/{family_code}/variants/{code}
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
code
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a Location header that contains the URI of the newly created resource.
Headers
Location • URI of the created resource
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}This response indicates that the Content-type header of the request is not supported by the server.
The server expects the Content-type header to be application/json, and any other value will result in this error.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Validation failed.",
"errors": [
{
"property": "family",
"message": "The tshirts family does not exist in your PIM."
},
{
"property": "categories",
"message": "The \"tvs_projectors\" category does not exist."
},
{
"property": "associations.SUBSTITUTION.groups",
"message": "You should associate existing groups. The \"promotion\" group does not exist."
},
{
"property": "values",
"message": "The \"description\" attribute requires a channel.",
"attribute": "description",
"locale": "en_US",
"scope": null
},
{
"property": "values",
"message": "The \"name\" attribute requires a locale.",
"attribute": "name",
"locale": null,
"scope": null
}
],
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Attribute
Get list of attributes
This endpoint allows you to get a list of attributes. Attributes are paginated and sorted by code.
REQUEST
get /api/rest/v1/attributes
Path parameters
Ø
Query parameters
search
(string)
• Filter attributes,
for more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.