API docs by Redocly

Akeneo API REFERENCE (1.0.0)

Download OpenAPI specification:

Akeneo Support: contact@akeneo.com URL: https://www.akeneo.com/support-help-center/ License: Open Software License 3.0

This is the reference documentation for the Akeneo PIM REST API. It provides detailed information about the available endpoints, request and response formats, and authentication methods.

For more information, visit the Akeneo PIM documentation.

Product [uuid]

A product is a single item that can be managed in the PIM. It can have various attributes and values, and can be associated with product models, categories, and other entities. Products are the core entities in the PIM and are used to manage the product information. 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.

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.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"uuid":[{"operator":"IN","value":["8945388d-cf5b-49af-8799-05d1ed6e296f", "941fe892-99dd-440f-b2a9-8eccb94248f0"]}]} - Filter the products by their uuid
  • search={"categories":[{"operator":"IN","value":["winter_collection"]}]} - Filter the products by their category
  • search={"categories":[{"operator":"IN","value":["winter_collection"]},{"operator":"NOT IN","value":["accessories"]}]} - Filter the products categorized on the Winter Collection category and that are not categorized on the Accessories category
  • search={"enabled":[{"operator":"=","value":false}]} - Filter the products by their status
  • search={"completeness":[{"operator":"=","value":50,"scope":"ecommerce"}]} - Filter the products by their completeness
  • search={"completeness":[{"operator":"GREATER OR EQUALS THAN ON ALL LOCALES","value":100,"locales":["en_US","fr_FR"],"scope":"ecommerce"}]} - Filter the products that are 100% complete on both the en_US and fr_FR locales for the ecommerce channel
  • search={"groups":[{"operator":"IN","value":["promotion"]}]} - Filter the products by their group
  • search={"family":[{"operator":"NOT IN","value":["camcorders","digital_cameras"]}]} - Filter the products by their family
  • search={"created":[{"operator":"=","value":"2016-07-04 10:00:00"}]} - Filter the products by their creation date
  • search={"updated":[{"operator":"SINCE LAST N DAYS","value":4}]} - Filter the products updated since X days
  • search={"parent":[{"operator":"IN","value":["tops"]}]} - Filter the variant products by their parent
  • search={"parent":[{"operator":"IN","value":["tshirt_armor_blue","tshirt_armor_red"]}]} - Filter the variant products by their sub product model
  • search={"parent":[{"operator":"NOT EMPTY"}]} - Get all variant products
  • search={"parent":[{"operator":"EMPTY"}]} - Get all simple products
  • search={"quality_score":[{"operator":"IN","value":["D"],"scope":"ecommerce","locale":"en_US"}]} - Filter the products with a "D" for the ecommerce channel and en_US locale
  • search={"quality_score":[{"operator":"IN","value":["A","B"],"scope":"mobile","locale":"en_GB"}]} - Filter the products with an "A" or "B" for the mobile channel and en_GB locale
  • search={"enabled":[{"operator":"=","value":true}]} - Get only enabled products
  • search={"enabled":[{"operator":"=","value":true}],"completeness":[{"operator":">","value":70,"scope":"ecommerce"}]} - Get only enabled products that are at least 70% complete on the ecommerce channel
  • search={"main_color":[{"operator":"IN","value":["purple"]}]} - Filter the products by an attribute value
  • search={"description":[{"operator":"STARTS WITH","value":"Amazing","locale":"en_US"}]} - Filter the products having a description begining with Amazing on the en_US locale
  • search={"release_date":[{"operator":">","value":"2016-07-04","scope":"ecommerce"}]} - Filter the products that have a release date due after the 4th of July 2016 for the ecommerce channel
  • search={"name":[{"operator":"CONTAINS","value":"shirt","locale":"en_US","scope":"mobile"}]} - Filter the products containing a text in the name attribute
  • search={"description":[{"operator":"STARTS WITH","value":"Amazing","locale":"en_US","scope":"ecommerce"}],"main_color":[{"operator":"IN","value":["purple"]}]} - Filter the products by multiple attribute values
  • search={"description":[{"operator":"NOT EMPTY","locale":"en_US","scope":"ecommerce"},{"operator":"EMPTY","locale":"fr_FR","scope":"ecommerce"}]} - Filter the products by multiple attribute conditions

Filter products, for more details see the Filters section

scope
string
Example: scope=ecommerce

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
Example: locales=en_US,fr_FR

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
Example: attributes=name,description

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
Default: "page"
Enum: "page" "search_after"
Example: pagination_type=page

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
Default: 1
Example: page=1

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
Default: "cursor to the first page"
Example: search_after=qaXbcde

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Example: search_scope=ecommerce

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
Example: search_locale=en_US

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
Default: false
Example: convert_measurements=true

Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter. When set to true, the response will include measurement values converted to the appropriate unit according to the following priority:

  1. First, the system uses the conversion unit configured at the channel level for that attribute.
  2. If no channel-level configuration exists, the system falls back to the attribute's default measurement unit.
  3. If neither is configured, the measurement value remains in its original unit. This is useful for displaying measurement values in the appropriate units for different channels or regions. If set to false, the response will return measurement values in their original units, which can improve performance. Therefore, this parameter requires the scope parameter to be provided.
with_count
boolean
Default: false
Example: with_count=true

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
Default: false
Example: with_attribute_options=true

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
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Default: false
Example: with_quality_scores=true

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
Default: false
Example: with_completenesses=true

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_root_parent
boolean
Default: false
Example: with_root_parent=true

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
Default: false
Example: with_workflow_execution_statuses=true

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.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "current_page": 3,
  • "items_count": 3,
  • "_embedded": {
    }
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/json

Body of a product creation request

uuid
string

Product UUID

enabled
boolean
Default: true

Whether the product is enabled

family
string or null
Default: "null only in the case of a non variant product"

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 of strings
Default: []

Codes of the categories in which the product is classified

groups
Array of strings
Default: []

Codes of the groups to which the product belong

parent
string or null
Default: null

Code of the parent product model when the product is a variant

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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

Responses

Request samples

Content type
application/json
{
  • "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "parent": null,
  • "values": {
    },
  • "associations": {
    },
  • "quantified_associations": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/vnd.akeneo.collection+json

Body containing the products to update or create using UUIDs. Each line is a JSON object representing a product. Each object contains the following properties:

  • uuid: Product UUID (string) (mandatory)
  • enabled: Whether the product is enabled (boolean) (optional)
  • family: Family code from which the product inherits its attributes and attributes requirements (string) (optional)
  • categories: Codes of the categories in which the product is classified (array) (optional)
  • add_categories: Codes of the categories to add to the product (array) (optional)
  • remove_categories: Codes of the categories to remove from the product (array) (optional)
  • groups: Codes of the groups to which the product belong (array) (optional)
  • parent: Code of the parent product model when the product is a variant (string) (optional)
  • values: Product attributes values. Each key is an attribute code, and the value is an array of value objects for that attribute (object) (optional)
  • associations: Several associations related to groups, product models and/or other products, grouped by association types (object) (optional)
  • quantified_associations: Several quantified associations related to products and/or product models, grouped by quantified association types (object) (optional)
  • created: Date of creation (string) (read-only)
  • updated: Date of the last update (string) (read-only)
  • metadata: More information around the product (object) (read-only)
  • quality_scores: Product quality scores for each channel/locale combination (only available when the with_quality_scores query parameter is set to true) (object) (read-only)
  • completenesses: Product completenesses for each channel/locale combination (only available when the with_completenesses query parameter is set to true) (object) (read-only)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"uuid\":\"fc24e6c3-933c-4a93-8a81-e5c703d134d5\",\"values\":{\"description\":[{\"scope\":\"ecommerce\",\"locale\":\"en_US\",\"data\":\"My amazing cap\"}]}}\n{\"uuid\":\"573dd613-0c7f-4143-83d5-63cc5e535966\",\"values\":{\"sku\":[{\"data\":\"updated_sku\",\"locale\":null,\"scope\":null}]}, \"group\":[\"promotion\"]}\n{\"uuid\":\"25566245-55c3-42ce-86d9-8610ac459fa8\",\"values\":{\"sku\":[{\"data\":\"new_product\",\"locale\":null,\"scope\":null}]},\"family\":\"clothes\"}\n"

Response samples

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

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.

Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

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
Default: false
Example: with_attribute_options=true

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
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Default: false
Example: with_quality_scores=true

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
Default: false
Example: with_completenesses=true

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_root_parent
boolean
Default: false
Example: with_root_parent=true

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
Default: false
Example: with_workflow_execution_statuses=true

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.

Responses

Response samples

Content type
application/json
{
  • "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "parent": null,
  • "root_parent": "null",
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

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.

Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

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

Request Body schema: application/json

Body of the request to update a product

uuid
string

Product UUID

enabled
boolean
Default: true

Whether the product is enabled

family
string or null
Default: "null only in the case of a non variant product"

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 of strings
Default: []

Codes of the categories in which the product is classified

add_categories
Array of strings
Default: []

Codes of the categories to add to the product. Existing categories will be preserved.

remove_categories
Array of strings
Default: []

Codes of the categories to remove from the product. Other categories will be preserved.d

groups
Array of strings
Default: []

Codes of the groups to which the product belong

parent
string or null
Default: 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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

Responses

Request samples

Content type
application/json
{
  • "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "parent": null,
  • "root_parent": "null",
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

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.

Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

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.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Submit a draft for approval

This endpoint allows you to submit a draft for approval

Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

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.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Get a draft

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

Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

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.

Responses

Response samples

Content type
application/json
{
  • "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "parent": null,
  • "root_parent": "null",
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

Product [identifier]

A product is a single item that can be managed in the PIM. It can have various attributes and values, and can be associated with product models, categories, and other entities. Products are the core entities in the PIM and are used to manage the product information. 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.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"categories":[{"operator":"IN","value":["winter_collection"]}]} - Filter the products by their category
  • search={"categories":[{"operator":"IN","value":["winter_collection"]},{"operator":"NOT IN","value":["accessories"]}]} - Filter the products categorized on the Winter Collection category and that are not categorized on the Accessories category
  • search={"enabled":[{"operator":"=","value":false}]} - Filter the products by their status
  • search={"completeness":[{"operator":"=","value":50,"scope":"ecommerce"}]} - Filter the products by their completeness
  • search={"completeness":[{"operator":"GREATER OR EQUALS THAN ON ALL LOCALES","value":100,"locales":["en_US","fr_FR"],"scope":"ecommerce"}]} - Filter the products that are 100% complete on both the en_US and fr_FR locales for the ecommerce channel
  • search={"groups":[{"operator":"IN","value":["promotion"]}]} - Filter the products by their group
  • search={"family":[{"operator":"NOT IN","value":["camcorders","digital_cameras"]}]} - Filter the products by their family
  • search={"created":[{"operator":"=","value":"2016-07-04 10:00:00"}]} - Filter the products by their creation date
  • search={"updated":[{"operator":"SINCE LAST N DAYS","value":4}]} - Filter the products updated since X days
  • search={"parent":[{"operator":"IN","value":["tops"]}]} - Filter the variant products by their parent
  • search={"parent":[{"operator":"IN","value":["tshirt_armor_blue","tshirt_armor_red"]}]} - Filter the variant products by their sub product model
  • search={"parent":[{"operator":"NOT EMPTY"}]} - Get all variant products
  • search={"parent":[{"operator":"EMPTY"}]} - Get all simple products
  • search={"quality_score":[{"operator":"IN","value":["D"],"scope":"ecommerce","locale":"en_US"}]} - Filter the products with a "D" for the ecommerce channel and en_US locale
  • search={"quality_score":[{"operator":"IN","value":["A","B"],"scope":"mobile","locale":"en_GB"}]} - Filter the products with an "A" or "B" for the mobile channel and en_GB locale
  • search={"enabled":[{"operator":"=","value":true}]} - Get only enabled products
  • search={"enabled":[{"operator":"=","value":true}],"completeness":[{"operator":">","value":70,"scope":"ecommerce"}]} - Get only enabled products that are at least 70% complete on the ecommerce channel
  • search={"main_color":[{"operator":"IN","value":["purple"]}]} - Filter the products by an attribute value
  • search={"description":[{"operator":"STARTS WITH","value":"Amazing","locale":"en_US"}]} - Filter the products having a description begining with Amazing on the en_US locale
  • search={"release_date":[{"operator":">","value":"2016-07-04","scope":"ecommerce"}]} - Filter the products that have a release date due after the 4th of July 2016 for the ecommerce channel
  • search={"name":[{"operator":"CONTAINS","value":"shirt","locale":"en_US","scope":"mobile"}]} - Filter the products containing a text in the name attribute
  • search={"description":[{"operator":"STARTS WITH","value":"Amazing","locale":"en_US","scope":"ecommerce"}],"main_color":[{"operator":"IN","value":["purple"]}]} - Filter the products by multiple attribute values
  • search={"description":[{"operator":"NOT EMPTY","locale":"en_US","scope":"ecommerce"},{"operator":"EMPTY","locale":"fr_FR","scope":"ecommerce"}]} - Filter the products by multiple attribute conditions

Filter products, for more details see the Filters section.

scope
string
Example: scope=ecommerce

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
Example: locales=en_US,fr_FR

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
Example: attributes=name,description

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
Default: "page"
Enum: "page" "search_after"
Example: pagination_type=page

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
Default: 1
Example: page=1

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
Default: "cursor to the first page"
Example: search_after=qaXbcde

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Example: search_scope=ecommerce

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
Example: search_locale=en_US

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
Default: false
Example: convert_measurements=true

Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter. When set to true, the response will include measurement values converted to the appropriate unit according to the following priority:

  1. First, the system uses the conversion unit configured at the channel level for that attribute.
  2. If no channel-level configuration exists, the system falls back to the attribute's default measurement unit.
  3. If neither is configured, the measurement value remains in its original unit. This is useful for displaying measurement values in the appropriate units for different channels or regions. If set to false, the response will return measurement values in their original units, which can improve performance. Therefore, this parameter requires the scope parameter to be provided.
with_count
boolean
Default: false
Example: with_count=true

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
Default: false
Example: with_attribute_options=true

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
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Default: false
Example: with_quality_scores=true

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
Default: false
Example: with_completenesses=true

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_workflow_execution_statuses
boolean
Default: false
Example: with_workflow_execution_statuses=true

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.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "current_page": 3,
  • "items_count": 3,
  • "_embedded": {
    }
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/json

Body of the request should contain a JSON object representing the product to create

uuid
string

Product UUID

identifier
required
string

Product identifier, i.e. the value of the only pim_catalog_identifier attribute

enabled
boolean
Default: true

Whether the product is enabled

groups
Array of strings
Default: []

Codes of the groups to which the product belong

family
string or null
Default: "null only in the case of a non variant product."

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 of strings
Default: []

Codes of the categories in which the product is classified

parent
string or null
Default: null

Code of the parent product model when the product is a variant

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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "identifier": "top",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/vnd.akeneo.collection+json

Body containing the products to update or create. Each line is a JSON object representing a product. Each object contains the following properties:

  • `uuid: Product UUID (string) (optional)
  • identifier: Product identifier, i.e. the value of the only pim_catalog_identifier attribute (string) (mandatory)
  • enabled: Whether the product is enabled (boolean) (optional)
  • family: Family code from which the product inherits its attributes and attributes requirements (string) (optional)
  • categories: Codes of the categories in which the product is classified (array) (optional)
  • add_categories: Codes of the categories to add to the product (array) (optional)
  • remove_categories: Codes of the categories to remove from the product (array) (optional)
  • groups: Codes of the groups to which the product belong (array) (optional)
  • parent: Code of the parent product model when the product is a variant (string) (optional)
  • values: Product attributes values. Each key is an attribute code, and the value is an array of value objects for that attribute (object) (optional)
  • associations: Several associations related to groups, product models and/or other products, grouped by association types (object) (optional)
  • quantified_associations: Several quantified associations related to products and/or product models, grouped by quantified association types (object) (optional)
  • created: Date of creation (string) (read-only)
  • updated: Date of the last update (string) (read-only)
  • metadata: More information around the product (object) (read-only)
  • quality_scores: Product quality scores for each channel/locale combination (only available when the with_quality_scores query parameter is set to true) (object) (read-only)
  • completenesses: Product completenesses for each channel/locale combination (only available when the with_completenesses query parameter is set to true) (object) (read-only)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"identifier\":\"cap\",\"status_code\":204}\n{\"line\":2,\"identifier\":\"mug\",\"status_code\":422,\"message\":\"Property \\\"group\\\" does not exist.\"}\n{\"line\":3,\"identifier\":\"tshirt\",\"status_code\":201}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"identifier\":\"cap\",\"status_code\":204}\n{\"line\":2,\"identifier\":\"mug\",\"status_code\":422,\"message\":\"Property \\\"group\\\" does not exist.\"}\n{\"line\":3,\"identifier\":\"tshirt\",\"status_code\":201}\n"

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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
Default: false
Example: with_attribute_options=true

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
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Default: false
Example: with_quality_scores=true

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
Default: false
Example: with_completenesses=true

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_workflow_execution_statuses
boolean
Default: false
Example: with_workflow_execution_statuses=true

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.

Responses

Response samples

Content type
application/json
{
  • "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "identifier": "top",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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

Request Body schema: application/json

Body of the request to update a product by its identifier

uuid
string

Product UUID

identifier
string

Product identifier, i.e. the value of the only pim_catalog_identifier attribute

enabled
boolean
Default: true

Whether the product is enabled

groups
Array of strings
Default: []

Codes of the groups to which the product belong

family
string or null
Default: "null only in the case of a non variant product"

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 of strings
Default: []

Codes of the categories in which the product is classified

add_categories
Array of strings
Default: []

Codes of the categories to add to the product. Existing categories will be preserved

remove_categories
Array of strings
Default: []

Codes of the categories to remove from the product. Other categories will be preserved.

parent
string or null
Default: 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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

Responses

Request samples

Content type
application/json
{
  • "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "identifier": "top",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Submit a draft for approval

This endpoint allows you to submit a draft for approval.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json

Empty body to submit the draft for approval

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Get a draft

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "identifier": "top",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}

Product model

A product model is a template for products that share the same attributes and values. It allows you to create a hierarchy of products, where a product model can have several variants. A product model can also have its own attributes and values, which are inherited by its variants.

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.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"categories":[{"operator":"IN","value":["winter_collection"]}]} - Filter the product models by their category
  • search={"completeness":[{"operator":"ALL COMPLETE","locale":"fr_FR","scope":"ecommerce"}]} - Filter the product models by their completeness
  • search={"completeness":[{"operator":"AT LEAST COMPLETE","locales":["en_US","fr_FR"],"scope":"ecommerce"}]} - Filter the product models that have at least one variant product 100% complete
  • search={"family":[{"operator":"IN","value":["camcorders"]}]} - Filter the product models that are in the camcorders family,
  • search={"family":[{"operator":"NOT IN","value":["camcorders","digital_cameras"]}]} - Filter the product models that are not in the camcorders and digital_cameras family
  • search={"created":[{"operator":"=","value":"2016-07-04 10:00:00"}]} - Filter the product models by their creation date
  • search={"updated":[{"operator":"SINCE LAST N DAYS","value":4}]} - Filter the product models updated since X days
  • search={"parent":[{"operator":"IN","value":["tshirt_armor"]}]} - Filter the sub-product models of the root product model with the code tshirt_armor
  • search={"parent":[{"operator":"IS NULL"}]} - Filter the root product models (product models without parent)
  • search={"parent":[{"operator":"IS NOT NULL"}]} - Filter the sub-product models (product models with parent)

Filter product models, for more details see the Filters.

scope
string
Example: scope=ecommerce

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
Example: locales=en_US,fr_FR

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
Example: attributes=name,description

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
Default: "page"
Enum: "page" "search_after"
Example: pagination_type=page

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
Default: 1
Example: page=1

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
Default: "cursor to the first page"
Example: search_after=qaXbcde

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Example: search_scope=ecommerce

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
Example: search_locale=en_US

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
Default: false
Example: convert_measurements=true

Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter. When set to true, the response will include measurement values converted to the appropriate unit according to the following priority:

  1. First, the system uses the conversion unit configured at the channel level for that attribute.
  2. If no channel-level configuration exists, the system falls back to the attribute's default measurement unit.
  3. If neither is configured, the measurement value remains in its original unit. This is useful for displaying measurement values in the appropriate units for different channels or regions. If set to false, the response will return measurement values in their original units, which can improve performance. Therefore, this parameter requires the scope parameter to be provided.
with_count
boolean
Default: false
Example: with_count=true

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
Default: false
Example: with_workflow_execution_statuses=true

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
Default: false
Example: with_attribute_options=true

Return labels of attribute options in the response. See the linked_data format section for more details.

with_asset_share_links
boolean
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Example: with_quality_scores=true

Return product model quality scores in the response.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "current_page": 1,
  • "items_count": 3,
  • "_embedded": {
    }
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/json

Body of the request should contain the product model to create

code
required
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 or null
Default: null

Code of the parent product model

categories
Array of strings
Default: []

Codes of the categories in which the product model is categorized

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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

Responses

Request samples

Content type
application/json
{
  • "code": "model-biker-jacket-leather",
  • "family": "clothing",
  • "family_variant": "clothing_material_size",
  • "parent": "model-biker-jacket",
  • "categories": [
    ],
  • "values": {
    },
  • "associations": {
    },
  • "quantified_associations": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

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.

Authorizations:
bearerToken
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).

Request Body schema: application/vnd.akeneo.collection+json

Body containing the product models to update or create. Each line is a JSON object representing a product model. Each object contains the following properties:

  • code: Product model code (string) (mandatory)
  • family: Family code from which the product model inherits its attributes and attributes requirements (string) (optional)
  • family_variant: Family variant code from which the product model inherits its attributes and variant attributes (string) (mandatory for root product models, optional for sub-product models)
  • parent: Code of the parent product model (string) (optional)
  • categories: Codes of the categories in which the product model is categorized (array) (optional)
  • add_categories: Codes of the categories to add to the product model (array) (optional)
  • remove_categories: Codes of the categories to remove from the product model (array) (optional)
  • values: Product model attributes values. Each key is an attribute code, and the value is an array of value objects for that attribute (object) (optional)
  • associations: Several associations related to groups, product and/or other product models, grouped by association types (object) (optional)
  • quantified_associations: Several quantified associations related to products and/or product models, grouped by quantified association types (object) (optional)
  • created: Date of creation (string) (read-only)
  • updated: Date of the last update (string) (read-only)
  • metadata: More information around the product model (object) (read-only)
  • quality_scores: Product model quality scores for each channel/locale combination (only available when the with_quality_scores query parameter is set to true) (object) (read-only)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\": \"sub_sweat_option_a\", \"parent\": \"sweat\", \"values\": {\"a_simple_select\": [{\"locale\": null, \"scope\": null, \"data\": \"optionA\"}]}}\n{\"code\": \"sub_sweat_option_b\", \"parent\": \"sweat\", \"values\": {\"a_simple_select\": [{\"locale\": null, \"scope\": null, \"data\": \"optionA\"}]}}\n{\"code\":\"tshirt\", \"parent\": \"root_tshirt\", \"family_variant\":\"clothesvariant\",\"values\":{\"description\":[{\"scope\":\"ecommerce\",\"locale\":\"en_US\",\"data\":\"My amazing tshirt\"}]}}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"sub_sweat_option_a\",\"status_code\":204}\n{\"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\"}]}\n{\"line\":3,\"code\":\"tshirt\",\"status_code\":201}\n"

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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
Default: false
Example: with_asset_share_links=true

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_quality_scores
boolean
Default: false
Example: with_quality_scores=true

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_workflow_execution_statuses
boolean
Default: false
Example: with_workflow_execution_statuses=true

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.

Responses

Response samples

Content type
application/json
{
  • "code": "model-biker-jacket-leather",
  • "family": "clothing",
  • "family_variant": "clothing_material_size",
  • "parent": "model-biker-jacket",
  • "categories": [
    ],
  • "values": {
    },
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "workflow_execution_statuses": [
    ],
  • "created": "2017-10-02T15:03:55+02:00",
  • "updated": "2017-10-02T15:03:55+02:00"
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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

Request Body schema: application/json

The product model to update

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 or null
Default: null

Code of the parent product model

categories
Array of strings
Default: []

Codes of the categories in which the product model is categorized

add_categories
Array of strings
Default: []

Codes of the categories to add to the product model. Existing categories will be preserved.

remove_categories
Array of strings
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.

object

Several associations related to groups, product models and/or other products, grouped by association types

object

Several quantified associations related to products and/or product models, grouped by quantified association types

Responses

Request samples

Content type
application/json
{
  • "code": "model-biker-jacket-leather",
  • "family": "clothing",
  • "family_variant": "clothing_material_size",
  • "parent": "model-biker-jacket",
  • "categories": [
    ],
  • "values": {
    },
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "workflow_execution_statuses": [
    ],
  • "created": "2017-10-02T15:03:55+02:00",
  • "updated": "2017-10-02T15:03:55+02:00"
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Submit a draft for approval

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

The content of the request body is not used

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Get a draft

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "model-biker-jacket-leather",
  • "family": "clothing",
  • "family_variant": "clothing_material_size",
  • "parent": "model-biker-jacket",
  • "categories": [
    ],
  • "values": {
    },
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "quality_scores": [
    ],
  • "workflow_execution_statuses": [
    ],
  • "created": "2017-10-02T15:03:55+02:00",
  • "updated": "2017-10-02T15:03:55+02:00"
}

Product media file

A media file is a file that can be attached to a product, product model, category, or asset. It can be an image, a video, a PDF, or any other type of file. Media files are used to enrich the product information and provide additional context to the products.

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

Authorizations:
bearerToken
query Parameters
page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

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

Authorizations:
bearerToken
Request Body schema: multipart/form-data

Body of the request to create a new media file

One of
product
required
string or 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.

file
required
string <binary>

The binaries of the file

Responses

Request samples

Content type
multipart/form-data
Example
{
  "product": "{\"identifier\":\"product_identifier\", \"attribute\":\"attribute_code\", \"scope\":null,\"locale\":null}",
  "file": ""
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{}

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Jobs

A job is a process that can be executed in the PIM to perform various tasks, such as importing or exporting data. Jobs can be used to synchronize data between the PIM and external systems, or to perform bulk operations on products, product models, or other entities.

Launch export job by code

This endpoint allows you to launch an export job by code

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
optional

Export jobs accept an optional request body

is_dry_run
boolean

Whether to run the export in dry-run mode

Responses

Request samples

Content type
application/json
{
  • "is_dry_run": false
}

Response samples

Content type
application/json
{
  • "job_execution_id": 12345
}

Launch import job by code

This endpoint allows you to launch an import job by code

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
optional

Body to change the import mode for this job.

import_mode
string
Enum: "create_only" "update_only" "create_or_update"

Change the import mode for this job by overriding the profile value. Available values are: create_only, update_only and create_or_update.

is_dry_run
boolean

Whether to run the import in dry-run mode

Responses

Request samples

Content type
application/json
{
  • "import_mode": "create_or_update",
  • "is_dry_run": false
}

Response samples

Content type
application/json
{
  • "job_execution_id": 12345
}

Family

A family is a set of attributes that are shared by products belonging to this family. In other words, a family can be considered as a template for products. A product family can use all of the attributes available in the PIM. Several families of products can use the same attributes.

Get list of families

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

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"code":[{"operator":"IN","value":["family_code1","family_code2"]}]} - Filter the families by their code
  • search={"updated":[{"operator":">","value":"2020-07-04T10:00:00Z"}]} - Filter the families by their update date
  • search={"has_products":[{"operator":"=","value":true}]} - Filter the families that have at least one attached product

The search query parameter allows you to filter families based on specific criteria. For more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new family

This endpoint allows you to create a new family

Authorizations:
bearerToken
header Parameters
Content-Type
required
string
Default: application/json
Example: application/json

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.

Request Body schema: application/json
required

The family to be created

code
required
string

Family code

attribute_as_label
string

Attribute code used as label

attribute_as_image
string or null

Attribute code used as the main picture in the user interface

attributes
Array of strings

Attribute codes that compose the family. Each string in the array must be an existing attribute code

object

Attribute codes of the family that are required for the completeness calculation for each channel

object
Default: {}

Family labels for each locale. The localeCode must be the code of an existing and activated locale

parent
string or null

The code of the parent family. If not provided, the family is a root family

Responses

Request samples

Content type
application/json
{
  • "code": "caps",
  • "attributes": [
    ],
  • "attribute_as_label": "name",
  • "attribute_as_image": "picture,",
  • "attribute_requirements": {
    },
  • "labels": {
    },
  • "parent": null
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several families

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

Authorizations:
bearerToken
header Parameters
Content-Type
required
string
Value: "application/vnd.akeneo.collection+json"

The content type of the request

Request Body schema: application/vnd.akeneo.collection+json
required

Body containing the families to update or create. Each line is a JSON object representing a family. Each object contains the following properties:

  • code: Family code (string) (mandatory)
  • attribute_as_label: Attribute code used as label (string) (optional)
  • attribute_as_image: Attribute code used as the main picture in the user interface (string) (optional)
  • attributes: Attribute codes that compose the family. Each string in the array must be an existing attribute code (array of strings) (optional)
  • attribute_requirements: Attribute codes of the family that are required for the completeness calculation for each channel (object) (optional)
  • labels: Family labels for each locale. The localeCode must be the code of an existing and activated locale (object) (optional)
  • parent: The code of the parent family. If not provided, the family is a root family (string) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{ \"code\": \"tshirt\",\"attribute_as_label\": \"description\",\"attributes\": [ \"description\",\"size\" ] }\n{ \"code\": \"cap\",\"attribute_as_label\": \"descripion\" }\n{ \"code\": \"mug\",\"attributes\": [ \"description\",\"short_description\" ] }\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"camcorders\",\"status_code\":201}\n{\"line\":2,\"code\":\"cap\",\"status_code\":422,\"message\":\"Attribute \\\"descripion\\\" does not exist.\"}\n{\"line\":3,\"code\":\"clothes\",\"status_code\":204}\n"

Get a family

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "caps",
  • "attributes": [
    ],
  • "attribute_as_label": "name",
  • "attribute_as_image": "picture,",
  • "attribute_requirements": {
    },
  • "labels": {
    },
  • "parent": null
}

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.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

header Parameters
Content-Type
required
string
Default: application/json
Example: application/json

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.

Request Body schema: application/json
required

The family object to update or create

code
string

Family code

attribute_as_label
string

Attribute code used as label

attribute_as_image
string or null

Attribute code used as the main picture in the user interface

attributes
Array of strings

Attribute codes that compose the family. Each string in the array must be an existing attribute code

object

Attribute codes of the family that are required for the completeness calculation for each channel

object
Default: {}

Family labels for each locale. The localeCode must be the code of an existing and activated locale

parent
string or null

The code of the parent family. If not provided, the family is a root family

Responses

Request samples

Content type
application/json
{
  • "code": "caps",
  • "attributes": [
    ],
  • "attribute_as_label": "name",
  • "attribute_as_image": "picture,",
  • "attribute_requirements": {
    },
  • "labels": {
    },
  • "parent": null
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Family variant

A family variant is a specific type of family that allows you to create variants of a product model. It allows you to define the attributes and values that are specific to the variants of a product model. Family variants are used to manage the relationships between product models and their variants.

Get list of family variants

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

Authorizations:
bearerToken
path Parameters
family_code
required
string
Example: caps

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
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new family variant

This endpoint allows you to create a family variant

Authorizations:
bearerToken
path Parameters
family_code
required
string
Example: caps

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.

Request Body schema: application/json

The body should contain a family variant in JSON standard format

code
required
string

Family variant code

required
Array of objects

Attributes distribution according to the enrichment level

object
Default: {}

Family variant labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "shoesVariant",
  • "labels": {
    },
  • "variant_attribute_sets": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several family variants

This endpoint allows you to update and/or create several family variants at once

Authorizations:
bearerToken
path Parameters
family_code
required
string
Example: caps

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.

Request Body schema: application/vnd.akeneo.collection+json

Body containing the family variants to update or create. Each line is a JSON object representing a family variant. Each object contains the following properties:

  • code: Family variant code (string) (mandatory)
  • variant_attribute_sets: Attributes distribution according to the enrichment level (array) (mandatory)
  • labels: Family variant labels for each locale (object) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\": \"shoes_by_size\", \"variant_attribute_sets\": [{\"level\": 1, \"axes\": [\"size\"], \"attributes\": [\"color\"]}]}\n{\"code\": \"shoes_by_color\",\"labels\": {\"en_US\": \"Shoes by color\"}}\n{\"code\": \"shoes_without_axes\", \"variant_attribute_sets\": [{\"level\": 1, \"axes\": [], \"attributes\": [\"color\"]}]}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"shoes_by_size\",\"status_code\":201}\n{\"line\":2,\"code\":\"shoes_by_color\",\"status_code\":204}\n{\"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\\\"\"}\n"

Get a family variant

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

Authorizations:
bearerToken
path Parameters
family_code
required
string
Example: caps

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
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "shoesVariant",
  • "labels": {
    },
  • "common_attributes": [
    ],
  • "variant_attribute_sets": [
    ]
}

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.

Authorizations:
bearerToken
path Parameters
family_code
required
string
Example: caps

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
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Family variants to update or create

code
string

Family variant code

required
Array of objects

Attributes distribution according to the enrichment level

object
Default: {}

Family variant labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "shoesVariant",
  • "labels": {
    },
  • "variant_attribute_sets": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Attribute

An attribute is a piece of information that can be associated with a product or product model. Attributes can be used to store various types of data, such as text, numbers, dates, or media files. They are used to define the characteristics of products and to provide additional information about them.

Get list of attributes

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

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"code":[{"operator":"IN","value":["code1","code2"]}]} - Filter the attributes by their code
  • search={"updated":[{"operator":">","value":"2020-07-04T10:00:00Z"}]} - Filter the attributes by their update date
  • search={"type":[{"operator":"IN","value":["pim_catalog_simpleselect","pim_catalog_multiselect"]}]} - Filter the attributes by their type
  • search={"is_main_identifier":[{"operator":"=","value":true}]} - Filter the attributes that are main identifier or not

Filter attributes, for more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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_table_select_options
boolean
Default: false
Example: with_table_select_options=true

Return the options of 'select' column types (of a table attribute) in the response. When set to true, the response will include all available options for select-type columns in table attributes. This is useful for retrieving all available options for select-type columns in table attributes, which is essential for form rendering and data validation. If set to false, the response will not include select options, which can improve performance.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "current_page": 3,
  • "items_count": 10,
  • "_embedded": {
    }
}

Create a new attribute

This endpoint allows you to create a new attribute.

Authorizations:
bearerToken
Request Body schema: application/json

The body of the request must be a JSON object containing the attribute to create. The code field is mandatory, it is used to identify the attribute. If the attribute already exists, an error will be returned. Note: The code field must be unique across all attributes.

code
required
string

Attribute code

type
required
string
Enum: "pim_catalog_identifier" "pim_catalog_metric" "pim_catalog_number" "pim_reference_data_multiselect" "pim_reference_data_simpleselect" "pim_catalog_simpleselect" "pim_catalog_multiselect" "pim_catalog_date" "pim_catalog_textarea" "pim_catalog_text" "pim_catalog_file" "pim_catalog_image" "pim_catalog_price_collection" "pim_catalog_boolean" "akeneo_reference_entity" "akeneo_reference_entity_collection" "pim_catalog_asset_collection" "pim_catalog_product_link" "pim_catalog_table"

Attribute type. See type section for more details.

object
Default: {}

Attribute labels for each locale

group
required
string

Attribute group

sort_order
integer
Default: 0

Order of the attribute in its group

localizable
boolean
Default: false

Whether the attribute is localizable, i.e. can have one value by locale

scopable
boolean
Default: false

Whether the attribute is scopable, i.e. can have one value by channel

available_locales
Array of strings

To make the attribute locale specfic, specify here for which locales it is specific

unique
boolean

Whether two values for the attribute cannot be the same

useable_as_grid_filter
boolean

Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters
integer or null

Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier

validation_rule
string or null

Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier

validation_regexp
string or null

Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier

wysiwyg_enabled
boolean or null

Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea

number_min
string or null

Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

number_max
string or null

Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

decimals_allowed
boolean or null

Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

negative_allowed
boolean or null

Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number

metric_family
string or null

Metric family when the attribute type is pim_catalog_metric

default_metric_unit
string or null

Default metric unit when the attribute type is pim_catalog_metric

date_min
string or null <date-time>

Minimum date allowed when the attribute type is pim_catalog_date

date_max
string or null <date-time>

Maximum date allowed when the attribute type is pim_catalog_date

allowed_extensions
Array of strings

Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image

max_file_size
string or null

Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image

reference_data_name
string or null

Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection OR Asset family code when the attribute type is pim_catalog_asset_collection

boolean or number or string or Array of strings or null
Array of objects

Configuration of the Table attribute (columns)

is_main_identifier
boolean

Is this attribute main identifier when attribute type is pim_catalog_identifier

is_mandatory
boolean

This attribute must be enriched from the moment a product is created. It will be mandatory across all families.

decimal_places_strategy
string or null

Defines the decimal places strategy. Available options are round, forbid and trim.

decimal_places
number or null

Defines the number of decimal places when decimal places strategy is round or forbid

enable_option_creation_during_import
boolean or null

Whether new attribute options can be created automatically during product or product model import (CSV, XLSX), when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect

max_items_count
number or null

Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection

Responses

Request samples

Content type
application/json
{
  • "code": "release_date",
  • "type": "pim_catalog_date",
  • "group": "marketing",
  • "group_labels": {
    },
  • "unique": false,
  • "useable_as_grid_filter": true,
  • "allowed_extensions": [ ],
  • "metric_family": null,
  • "default_metric_unit": null,
  • "reference_data_name": null,
  • "available_locales": [ ],
  • "max_characters": null,
  • "validation_rule": null,
  • "validation_regexp": null,
  • "wysiwyg_enabled": null,
  • "number_min": null,
  • "number_max": null,
  • "decimals_allowed": null,
  • "negative_allowed": null,
  • "date_min": "2017-06-28T08:00:00",
  • "date_max": "2017-08-08T22:00:00",
  • "max_file_size": null,
  • "minimum_input_length": null,
  • "sort_order": 1,
  • "localizable": false,
  • "scopable": false,
  • "default_value": null,
  • "labels": {
    },
  • "is_mandatory": false,
  • "decimal_places_strategy": null,
  • "decimal_places": null,
  • "enable_option_creation_during_import": false,
  • "max_items_count": null
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several attributes

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

Authorizations:
bearerToken
Request Body schema: application/vnd.akeneo.collection+json

Body containing the attributes to update or create. Each line is a JSON object representing an attribute. Each object contains the following properties: code: Attribute code (string) (mandatory) type: Attribute type (string) (mandatory) labels: Attribute labels for each locale (object) (optional) group: Attribute group (string) (mandatory) group_ labels: Group labels for each locale (object) (optional) sort_order: Order of the attribute in its group (integer) (optional) localizable: Whether the attribute is localizable, i.e. can have one value by locale (boolean) (optional) scopable: Whether the attribute is scopable, i.e. can have one value by channel (boolean) (optional) available_locales: To make the attribute locale specfic, specify here for which locales it is specific (array) (optional) unique: Whether two values for the attribute cannot be the same (boolean) (optional) useable_as_grid_filter: Whether the attribute can be used as a filter for the product grid in the PIM user interface (boolean) (optional) max_characters:Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier (integer) (optional) validation_rule: Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier (string) (optional) validation_regexp: Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier (string) (optional) wysiwyg_enabled: Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea (boolean) (optional) number_min: Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number (integer) (optional) number_max: Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number (integer) (optional) decimals_allowed: Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number (boolean) (optional) negative_allowed: Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number (boolean) (optional) metric_family: Metric family when the attribute type is pim_catalog_metric (string) (optional) default_metric_unit: Default metric unit when the attribute type is pim_catalog_metric (string) (optional) date_min: Minimum date allowed when the attribute type is pim_catalog_date (string) (optional) date_max: Maximum date allowed when the attribute type is pim_catalog_date (string) (optional) allowed_extensions: Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image (array) (optional) max_file_size: Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image (string) (optional) reference_data_name: Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection OR Asset family code when the attribute type is pim_catalog_asset_collection (string) (optional) default_value: Default value applied when creating products (mixed) (optional) table_configuration: Configuration of the Table attribute (columns) (array) (optional) is_main_identifier: Is this attribute main identifier when attribute type is pim_catalog_identifier (boolean) (optional) is_mandatory: This attribute must be enriched from the moment a product is created. It will be mandatory across all families (boolean) (optional) decimal_places_strategy: Defines the decimal places strategy (round, forbid, trim) (string) (optional) decimal_places: Defines the number of decimal places when decimal places strategy is round or forbid (number) (optional) enable_option_creation_during_import: Whether new attribute options can be created automatically during product or product model import (CSV, XLSX), when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect (boolean) (optional) max_items_count: Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection (number) (optional)

string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"description\",\"useable_as_grid_filter\":true}\n{\"code\":\"short_description\",\"group\":\"marketig\"}\n{\"code\":\"release_date\",\"date_min\":\"2017-06-28T08:00:00\"}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"description\",\"status_code\":201}\n{\"line\":2,\"code\":\"short_description\",\"status_code\":422,\"message\":\"Group \\\"marketig\\\" does not exist.\"}\n{\"line\":3,\"code\":\"release_date\",\"status_code\":204}\n"

Get an attribute

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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_table_select_options
boolean
Default: false
Example: with_table_select_options=true

Return the options of 'select' column types (of a table attribute) in the response. When set to true, the response will include all available options for select-type columns in table attributes. This is useful for retrieving all available options for select-type columns in table attributes, which is essential for form rendering and data validation. If set to false, the response will not include select options, which can improve performance.

Responses

Response samples

Content type
application/json
{
  • "code": "release_date",
  • "type": "pim_catalog_date",
  • "group": "marketing",
  • "group_labels": {
    },
  • "unique": false,
  • "useable_as_grid_filter": true,
  • "allowed_extensions": [ ],
  • "metric_family": null,
  • "default_metric_unit": null,
  • "reference_data_name": null,
  • "available_locales": [ ],
  • "max_characters": null,
  • "validation_rule": null,
  • "validation_regexp": null,
  • "wysiwyg_enabled": null,
  • "number_min": null,
  • "number_max": null,
  • "decimals_allowed": null,
  • "negative_allowed": null,
  • "date_min": "2017-06-28T08:00:00",
  • "date_max": "2017-08-08T22:00:00",
  • "max_file_size": null,
  • "minimum_input_length": null,
  • "sort_order": 1,
  • "localizable": false,
  • "scopable": false,
  • "default_value": null,
  • "labels": {
    },
  • "is_mandatory": false,
  • "decimal_places_strategy": null,
  • "decimal_places": null,
  • "enable_option_creation_during_import": false,
  • "max_items_count": null
}

Update/create an attribute

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

The attribute to update or create. If the attribute does not exist, it will be created.

code
string

Attribute code

type
string
Enum: "pim_catalog_identifier" "pim_catalog_metric" "pim_catalog_number" "pim_reference_data_multiselect" "pim_reference_data_simpleselect" "pim_catalog_simpleselect" "pim_catalog_multiselect" "pim_catalog_date" "pim_catalog_textarea" "pim_catalog_text" "pim_catalog_file" "pim_catalog_image" "pim_catalog_price_collection" "pim_catalog_boolean" "akeneo_reference_entity" "akeneo_reference_entity_collection" "pim_catalog_asset_collection" "pim_catalog_product_link" "pim_catalog_table"

Attribute type. See type section for more details.

object
Default: {}

Attribute labels for each locale

group
string

Attribute group

sort_order
integer
Default: 0

Order of the attribute in its group

localizable
boolean
Default: false

Whether the attribute is localizable, i.e. can have one value by locale

scopable
boolean
Default: false

Whether the attribute is scopable, i.e. can have one value by channel

available_locales
Array of strings

To make the attribute locale specfic, specify here for which locales it is specific

unique
boolean

Whether two values for the attribute cannot be the same

useable_as_grid_filter
boolean

Whether the attribute can be used as a filter for the product grid in the PIM user interface

max_characters
integer or null

Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier

validation_rule
string or null

Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier

validation_regexp
string or null

Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier

wysiwyg_enabled
boolean or null

Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea

number_min
string or null

Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

number_max
string or null

Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

decimals_allowed
boolean or null

Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number

negative_allowed
boolean or null

Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number

metric_family
string or null

Metric family when the attribute type is pim_catalog_metric

default_metric_unit
string or null

Default metric unit when the attribute type is pim_catalog_metric

date_min
string or null <date-time>

Minimum date allowed when the attribute type is pim_catalog_date

date_max
string or null <date-time>

Maximum date allowed when the attribute type is pim_catalog_date

allowed_extensions
Array of strings

Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image

max_file_size
string or null

Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image

reference_data_name
string or null

Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection OR Asset family code when the attribute type is pim_catalog_asset_collection

boolean or number or string or Array of strings or null
Array of objects

Configuration of the Table attribute (columns)

is_main_identifier
boolean

Is this attribute main identifier when attribute type is pim_catalog_identifier

is_mandatory
boolean

This attribute must be enriched from the moment a product is created. It will be mandatory across all families.

decimal_places_strategy
string or null

Defines the decimal places strategy. Available options are round, forbid and trim.

decimal_places
number or null

Defines the number of decimal places when decimal places strategy is round or forbid

enable_option_creation_during_import
boolean or null

Whether new attribute options can be created automatically during product or product model import (CSV, XLSX), when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect

max_items_count
number or null

Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection

Responses

Request samples

Content type
application/json
{
  • "code": "release_date",
  • "type": "pim_catalog_date",
  • "group": "marketing",
  • "group_labels": {
    },
  • "unique": false,
  • "useable_as_grid_filter": true,
  • "allowed_extensions": [ ],
  • "metric_family": null,
  • "default_metric_unit": null,
  • "reference_data_name": null,
  • "available_locales": [ ],
  • "max_characters": null,
  • "validation_rule": null,
  • "validation_regexp": null,
  • "wysiwyg_enabled": null,
  • "number_min": null,
  • "number_max": null,
  • "decimals_allowed": null,
  • "negative_allowed": null,
  • "date_min": "2017-06-28T08:00:00",
  • "date_max": "2017-08-08T22:00:00",
  • "max_file_size": null,
  • "minimum_input_length": null,
  • "sort_order": 1,
  • "localizable": false,
  • "scopable": false,
  • "default_value": null,
  • "labels": {
    },
  • "is_mandatory": false,
  • "decimal_places_strategy": null,
  • "decimal_places": null,
  • "enable_option_creation_during_import": false,
  • "max_items_count": null
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Attribute option

An attribute option is a value that can be associated with an attribute. For example, if you have an attribute called "Color", the options could be "Red", "Blue", "Green", etc. Options are used to provide predefined values for attributes, making it easier to manage and maintain product data.

Get list of attribute options

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

Authorizations:
bearerToken
path Parameters
attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

query Parameters
page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new attribute option

This endpoint allows you to create a new attribute option

Authorizations:
bearerToken
path Parameters
attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

Request Body schema: application/json

Body containing the attribute option to create

code
required
string

Code of option

attribute
string

Code of attribute related to the attribute option

sort_order
integer

Order of attribute option

object
Default: {}

Attribute option labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "black",
  • "attribute": "a_simple_select",
  • "sort_order": 2,
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several attribute options

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

Authorizations:
bearerToken
path Parameters
attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

Request Body schema: application/vnd.akeneo.collection+json

Body containing the attribute options to update or create. Each line is a JSON representing an attribute option. Each object contains the following properties:

  • code: Code of option (string) (mandatory)
  • attribute: Code of attribute related to the attribute option (string) (not required, taken from the URL)
  • sort_order: Order of attribute option (integer) (optional)
  • labels: Attribute option labels for each locale (object) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"black\",\"attribute\":\"a_simple_select\",\"labels\":{\"en_US\":\"Black\",\"fr_FR\":\"Noir\"}}\n{\"code\":\"red\",\"label\":{\"en_US\": \"Red\",\"fr_FR\": \"Rouge\"}}\n{\"code\":\"yellow\",\"labels\":{\"en_US\": \"Yellow\",\"fr_FR\": \"Jaune\"}}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"black\",\"status_code\":201}\n{\"line\":2,\"code\":\"red\",\"status_code\":422,\"message\":\"Property \\\"label\\\" does not exist. Check the API format documentation.\"}\n{\"line\":3,\"code\":\"yellow\",\"status_code\":204}\n"

Get an attribute option

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

Authorizations:
bearerToken
path Parameters
attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "black",
  • "attribute": "a_simple_select",
  • "sort_order": 2,
  • "labels": {
    }
}

Update/create an attribute option

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

Authorizations:
bearerToken
path Parameters
attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Body containing the attribute option to create or update

code
string

Code of option

attribute
string

Code of attribute related to the attribute option

sort_order
integer

Order of attribute option

object
Default: {}

Attribute option labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "black",
  • "attribute": "a_simple_select",
  • "sort_order": 2,
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Attribute group

An attribute group is a way to organize attributes in the PIM. It allows you to group related attributes together, making it easier to manage and maintain product data. For example, you could have an attribute group called "Specifications" that contains attributes like "Weight", "Dimensions", and "Material".

Get list of attribute groups

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

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"code":[{"operator":"IN","value":["marketing","technical"]}]} - Filter the attribute groups by their code
  • search={"updated":[{"operator":">","value":"2020-07-04T10:00:00Z"}]} - Filter the attribute groups by their update date

Filter attribute groups, for more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new attribute group

This endpoint allows you to create a new attribute group.

Authorizations:
bearerToken
Request Body schema: application/json

Representation of the attribute group to create, in JSON standard format

code
required
string

Attribute group code

sort_order
integer
Default: 0

Attribute group order among other attribute groups

attributes
Array of strings
Default: []

Attribute codes that compose the attribute group

object
Default: {}

Attribute group labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "marketing",
  • "sort_order": 4,
  • "attributes": [
    ],
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several attribute groups

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

Authorizations:
bearerToken
Request Body schema: application/vnd.akeneo.collection+json

Body containing the attribute groups to update or create. Each line is a JSON object representing an attribute group. Each object contains the following properties:

  • code: Attribute group code (string) (mandatory)
  • sort_order: Attribute group order among other attribute groups (integer) (optional)
  • attributes: Attribute codes that compose the attribute group (array of strings) (optional)
  • labels: Attribute group labels for each locale (object) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"technical\",\"labels\":{\"en_US\": \"Technical\", \"fr_FR\": \"Technique\"}}\n{\"code\":\"marketing\",\"type\":\"bar\"}\n{\"code\":\"design\",\"sort_order\":7}\n"

Response samples

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

Get an attribute group

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "marketing",
  • "sort_order": 4,
  • "attributes": [
    ],
  • "labels": {
    }
}

Update/create an attribute group

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json

Representation of the attribute group to create or update

code
string

Attribute group code

sort_order
integer
Default: 0

Attribute group order among other attribute groups

attributes
Array of strings
Default: []

Attribute codes that compose the attribute group

object
Default: {}

Attribute group labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "marketing",
  • "sort_order": 4,
  • "attributes": [
    ],
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Association type

An association type is a way to define the relationship between products or product models. It allows you to create links between products, such as "related products", "up-sell products", or "cross-sell products". Association types are used to manage the relationships between products and to provide additional context to the product information.

Get a list of association types

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

Authorizations:
bearerToken
query Parameters
page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new association type

This endpoint allows you to create a new association type

Authorizations:
bearerToken
Request Body schema: application/json

Body containing the association type to create

code
required
string

Association type code

object
Default: {}

Association type labels for each locale

is_quantified
boolean
Default: false

When true, the association is a quantified association

is_two_way
boolean
Default: false

When true, the association is a bidirectional association

Responses

Request samples

Content type
application/json
{
  • "code": "upsell",
  • "labels": {
    },
  • "is_quantified": false,
  • "is_two_way": false
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several association types

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

Authorizations:
bearerToken
Request Body schema: application/vnd.akeneo.collection+json

Body containing the association types to update or create. Each line is a JSON object representing an association type. Each object contains the following properties:

  • code: Association type code (string) (mandatory)
  • labels: Association type labels for each locale (object) (optional)
  • is_quantified: When true, the association is a quantified association (boolean) (optional)
  • is_two_way: When true, the association is a bidirectional association (boolean) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"new_sell\"}\n{\"code\":\"substitution\", \"type\":\"bar\"}\n{\"code\":\"x_cross_sell\", \"is_two_way\": true, \"is_quantified\": false}\n"

Response samples

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

Get an association type

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "upsell",
  • "labels": {
    },
  • "is_quantified": false,
  • "is_two_way": false
}

Update/create an association type

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Body containing the association type to update or create

code
string

Association type code

object
Default: {}

Association type labels for each locale

is_quantified
boolean
Default: false

When true, the association is a quantified association

is_two_way
boolean
Default: false

When true, the association is a bidirectional association

Responses

Request samples

Content type
application/json
{
  • "code": "upsell",
  • "labels": {
    },
  • "is_quantified": false,
  • "is_two_way": false
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Category

A category is a way of classifying products. Categories constitute category trees and in Akeneo, you can have multiple category trees with an unlimited number of levels (categories, subcategories, subsubcategories..).

Get the list of categories

This endpoint allows you to get a list of categories. Categories are paginated and sorted by root/left. You can filter the categories by using the search query parameter, which supports searching by category code or label. The response includes the category's code, parent code, labels, values, and channel requirements. You can also specify the with_position query parameter to include the position of the category in its level. The with_enriched_attributes query parameter allows you to include enriched attributes.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"is_root":[{"operator":"=","value":true}]} - Filter the categories to get only root categories
  • search={"parent":[{"operator":"=","value":"categoryA"}]} - Filter the categories by parent
  • search={"code":[{"operator":"IN","value":["category_code1","category_code2"]}]} - Filter the categories by their code
  • search={"updated":[{"operator":">","value":"2021-05-17T10:00:00Z"}]} - Filter the categories by their update date

The search query parameter allows you to filter categories based on specific criteria. For more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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_position
boolean
Default: false
Example: with_position=true

Return information about the category's position within its category tree. When set to true, the response will include the position of the category in its level, which can be useful for understanding the hierarchy and order of categories. If set to false, the response will not include this information, which can improve performance.

with_enriched_attributes
boolean
Default: false
Example: with_enriched_attributes=true

Return the attribute values of the category. When set to true, the response will include the values of all attributes associated with the category. This is useful for retrieving detailed information about the category's attributes, such as their values and configurations. If set to false, the response will not include attribute values, which can improve performance

Responses

Response samples

Content type
application/json
{}

Create a new category

This endpoint allows you to create a new category. You can specify the category's code, parent category, labels, values, validations, and channel requirements. The request body should be in JSON format and include the necessary fields for the category.

Authorizations:
bearerToken
Request Body schema: application/json
optional

The category to be created

code
required
string

Category code

parent
string or null

Category code of the parent's category

object
Default: {}
channel_requirements
Array of strings
Default: []

List of Channel codes on which the category is required for products completeness. Only category trees can be required, not child categories.

Array of objects or object
Default: []

Attribute values

object
Default: {}

Category validations

Responses

Request samples

Content type
application/json
Example
{
  • "code": "winter_collection",
  • "parent": null,
  • "labels": {
    },
  • "values": [
    ],
  • "validations": {
    },
  • "channel_requirements": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Create or update several categories

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

Authorizations:
bearerToken
Request Body schema: application/vnd.akeneo.collection+json
optional

Body containing the categories to update or create. Each line is a JSON object representing a category. Each object contains the following properties:

  • code: Category code (string) (mandatory)
  • parent: Category code of the parent's category (string) (optional, null for root categories)
  • updated: Date of the last update (string) (read-only)
  • position: Position of the category in its level, start from 1 (only available when query parameter "with_position" is set to "true") (integer) (read-only)
  • labels: Category label for the specified locale (object) (optional)
  • values: Attribute values (array) (optional)
  • validations: the validations for products in this category (object) (optional)
  • channel_requirements: List of Channel codes on which the category is required for products completeness. Only category trees can be required, not child categories (array of strings) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"spring_collection\",\"parent\":null}\n{\"code\":\"woman\",\"parent\":\"spring_collectionn\"}\n{\"code\":\"man\",\"parent\":\"spring_collection\"}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"spring_collection\",\"status_code\":201}\n{\"line\":2,\"code\":\"woman\",\"status_code\":422,\"message\":\"Category \\\"spring_collectionn\\\" does not exist.\"}\n{\"line\":3,\"code\":\"man\",\"status_code\":204}\n"

Get a category

This endpoint allows you to retrieve a category by its code. The response includes the category's details such as its labels, values, and channel requirements. You can also specify the with_position query parameter to include the position of the category in its level. The with_enriched_attributes query parameter allows you to include enriched attributes.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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_position
boolean
Default: false
Example: with_position=true

Return information about the category's position within its category tree. When set to true, the response will include the position of the category in its level, which can be useful for understanding the hierarchy and order of categories. If set to false, the response will not include this information, which can improve performance.

with_enriched_attributes
boolean
Default: false
Example: with_enriched_attributes=true

Return the attribute values of the category. When set to true, the response will include the values of all attributes associated with the category. This is useful for retrieving detailed information about the category's attributes, such as their values and configurations. If set to false, the response will not include attribute values, which can improve performance

Responses

Response samples

Content type
application/json
{
  • "code": "winter_collection",
  • "parent": null,
  • "updated": "2021-05-22T12:48:00+02:00",
  • "position": 1,
  • "labels": {
    },
  • "values": {
    },
  • "channel_requirements": [
    ]
}

Create or update a category

This endpoint allows you to update a given category. Note that if no category exists for the given code, it creates it. You can specify the category's code, parent category, labels, values, validations, and channel requirements. The request body should be in JSON format and include the necessary fields for the category.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

The category to update or create. If the category does not exist, it will be created.

code
string

Category code

parent
string or null

Category code of the parent's category

object
Default: {}
channel_requirements
Array of strings
Default: []

List of Channel codes on which the category is required for products completeness. Only category trees can be required, not child categories.

Array of objects or object
Default: []

Attribute values

object
Default: {}

Category validations

Responses

Request samples

Content type
application/json
Example
{
  • "code": "winter_collection",
  • "parent": null,
  • "labels": {
    },
  • "values": [
    ],
  • "validations": {
    },
  • "channel_requirements": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Create a category media file

This endpoint allows you to create a new media file and associate it to anattribute value of a given enriched category. It is used to upload media files that are linked to categories, such as images or documents. The request body should include the category information and the binary file data.

Authorizations:
bearerToken
Request Body schema: multipart/form-data

Body of the request to create a new category media file

category
required
string

The category to which the media file will be associated. It is a JSON string that follows this format: '{"code":"category code", "attribute_code":"attribute code", "channel":"channel code or null", "locale":"locale code or null"}'.

file
required
string <binary>

The media file to be uploaded. It should be provided as a binary file. Ensure that the file format is supported by the system.

Responses

Request samples

Content type
multipart/form-data
{
  "category": "{\"code\":\"ecomm\", \"attribute_code\":\"image_1\", \"channel\":\"ecommerce\", \"locale\":\"en_US\"}",
  "file": ""
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Download a category media file

This endpoint allows you to download a given media file that is used as an attribute value of a enriched category. The media file is identified by its path, which is provided in the request.

Authorizations:
bearerToken
path Parameters
file_path
required
string
Example: my_resource_code

This path parameter is used to specify the unique identifier of the media file you want to download. It is essential for identifying the specific media file in the API requests. Ensure that the file path is correctly formatted and corresponds to an existing media file in the system.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Channel

A channel is a way to define how products are presented in different contexts, such as online stores, mobile applications, or print catalogs. Channels can have different configurations, such as currencies, locales, and measurement systems. They allow you to tailor the product information to specific markets or audiences.

Get a list of channels

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

Authorizations:
bearerToken
query Parameters
page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Create a new channel

This endpoint allows you to create a new channel.

Authorizations:
bearerToken
Request Body schema: application/json

Body representing the channel

code
required
string

Channel code

locales
required
Array of strings

Codes of activated locales for the channel

currencies
required
Array of strings

Codes of activated currencies for the channel

category_tree
required
string

Code of the category tree linked to the channel

object

Units to which the given metric attributes should be converted when exporting products

object
Default: {}

Channel labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "ecommerce",
  • "currencies": [
    ],
  • "locales": [
    ],
  • "category_tree": "master",
  • "conversion_units": {
    },
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Update/create several channels

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

Authorizations:
bearerToken
Request Body schema: application/vnd.akeneo.collection+json

Body containing the channels to update or create. Each line is a JSON object representing a channel. Each object contains the following properties:

  • code: Channel code (string) (mandatory)
  • locales: Codes of activated locales for the channel (array of strings) (mandatory)
  • currencies: Codes of activated currencies for the channel (array of strings) (mandatory)
  • category_tree: Code of the category tree linked to the channel (string) (mandatory)
  • conversion_units: Units to which the given metric attributes should be converted when exporting products (object) (optional)
  • labels: Channel labels for each locale (object) (optional)
string

Responses

Request samples

Content type
application/vnd.akeneo.collection+json
"{\"code\":\"ecommerce_fr\", \"category_tree\": \"master\", \"currencies\":[\"EUR\"], \"locales\": [\"fr_FR\"], \"labels\":{\"fr_FR\": \"Ecommerce Fr\"}}\n{\"code\":\"ecommerce_ch\", \"type\":\"bar\"}\n{\"code\":\"tablet\", \"labels\":{\"en_US\": \"Tablet\", \"fr_FR\": \"Tablette\"}}\n"

Response samples

Content type
application/vnd.akeneo.collection+json
"{\"line\":1,\"code\":\"ecommerce_fr\",\"status_code\":201}\n{\"line\":2,\"code\":\"ecommerce_ch\",\"status_code\":422,\"message\":\"Property \\\"type\\\" does not exist. Check the standard format documentation.\",\"_links\":{\"documentation\":{\"href\":\"https:\\/\\/api.akeneo.com\\/api-reference.html#patch_channels__code_\"}}}\n{\"line\":3,\"code\":\"tablet\",\"status_code\":204}\n"

Get a channel

This endpoint allows you to get the information about a given channel

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "ecommerce",
  • "currencies": [
    ],
  • "locales": [
    ],
  • "category_tree": "master",
  • "conversion_units": {
    },
  • "labels": {
    }
}

Update/create a channel

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Body of the request to create or update a channel

code
string

Channel code

locales
Array of strings

Codes of activated locales for the channel

currencies
Array of strings

Codes of activated currencies for the channel

category_tree
string

Code of the category tree linked to the channel

object

Units to which the given metric attributes should be converted when exporting products

object
Default: {}

Channel labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "ecommerce",
  • "currencies": [
    ],
  • "locales": [
    ],
  • "category_tree": "master",
  • "conversion_units": {
    },
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Locale

A locale is a combination of a language (English, German, French...) and a country (United States, United Kingdom, France...). Examples: English UK (en_GB), English US (en_US), English AU (en_AU). You can have one or more locales activated in your PIM.

Get a list of locales

This endpoint allows you to retrieve a list of locales available in the system. Locales are paginated and can be filtered using the search query parameter. The response includes the locale code and whether it is enabled. You can also specify pagination parameters such as page, limit, and with_count.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"enabled":[{"operator":"=","value":true}]} - Filter the locales to get only the enabled ones

The search query parameter allows you to filter locales based on specific criteria. For more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Get a locale

This endpoint allows you to get the information about a given locale. You can retrieve details such as the locale code and whether it is enabled. The response will be in JSON format.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "en_US",
  • "enabled": true
}

Currency

A currency is a unit of exchange that is used to price products. Currencies are used in the PIM to define the prices of products in different markets.

Get a list of currencies

This endpoint allows you to retrieve a list of currencies available in the system. Currencies are paginated and can be filtered using the search query parameter. The response includes the currency code, whether it is enabled, and its label. You can also specify pagination parameters such as page, limit, and with_count.

Authorizations:
bearerToken
query Parameters
search
string
Examples:
  • search={"enabled":[{"operator":"=","value":true}]} - Filter the currencies to get only the enabled ones

The search query parameter allows you to filter currencies based on specific criteria. For more details see the Filters section.

page
integer
Default: 1
Example: page=1

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 [ 1 .. 100 ]
Default: 10
Example: limit=100

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
Default: false
Example: with_count=true

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.

Responses

Response samples

Content type
application/json
{}

Get a currency

This endpoint allows you to get the information about a given currency. You can retrieve details such as the currency code, whether it is enabled, and its label. The response will be in JSON format.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "EUR",
  • "enabled": true,
  • "label": "EUR (Euro)"
}

Measurement family

A measurement family is a set of comparable units used to measure a specific physical quantity, such as Area, Weight, or Power. For example, the "Weight" measurement family can group units like "Kilogram" and "Pound" together. Each family has a standard unit for conversions (e.g., "Kilogram"), and all other units within that family include their conversion formulas. These families are used for metric attributes, allowing product data to be entered in one unit and automatically converted for different channels or locales.

Get list of measurement families

This endpoint allows you to get a list of measurement families

Authorizations:
bearerToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update/create several measurement families

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

Authorizations:
bearerToken
Request Body schema: application/json
required

A list of measurement families to create or update

Array
Any of
object
Default: {}

Measurement family labels for each locale

required
object

Measurement units for this family with their conversion operations. More details here

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Reference entity

A reference entity is a custom entity that can be used to store additional information about products or product models. It allows you to create your own entities with their own attributes and values, which can be linked to products or product models. Reference entities are useful for managing complex data structures or for integrating with external systems.

Get list of reference entities

This endpoint allows you to get a list of reference entities. Reference entities are paginated.

Authorizations:
bearerToken
query Parameters
search_after
string
Default: "cursor to the first page"
Example: search_after=qaXbcde

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.

Responses

Response samples

Content type
application/json
{}

Get a reference entity

This endpoint allows you to get the information about a given reference entity

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{}

Update/create a reference entity

This endpoint allows you to update a given reference entity. Note that if the reference entity does not already exist, it creates it.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Payload to create or update a reference entity

code
required
string

Reference entity code

object
Default: {}

Reference entity labels for each locale

image
string or null
Default: null

Code of the reference entity image

Responses

Request samples

Content type
application/json
{
  • "code": "brands",
  • "labels": {
    },
  • "image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Reference entity attribute

A reference entity attribute is a piece of information that can be associated with a reference entity. Reference entity attributes can be used to store various types of data, such as text, numbers, dates, or media files. They are used to define the characteristics of reference entities and to provide additional information about them.

Get the list of attributes of a given reference entity

This endpoint allows you to get the list of attributes of a given reference entity

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get an attribute of a given reference entity

This endpoint allows you to get the information about a given attribute for a given reference entity

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "description",
  • "labels": {
    },
  • "type": "text",
  • "value_per_locale": true,
  • "value_per_channel": false,
  • "is_required_for_completeness": true,
  • "is_textarea": true,
  • "is_rich_text_editor": true,
  • "validation_rule": "none"
}

Update/create an attribute of a given reference entity

This endpoint allows you to update a given attribute for a given reference entity. Note that if the attribute does not already exist for the given reference entity, it creates it.

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Payload to update or create a reference entity attribute

code
string

Attribute code

object
Default: {}

Attribute labels per locale

type
string
Enum: "text" "image" "number" "single_option" "multiple_options" "reference_entity_single_link" "reference_entity_multiple_links" "asset_collection"

Attribute type. See type section for more details.

value_per_locale
boolean
Default: false

Whether the attribute is localizable, i.e. can have one value by locale

value_per_channel
boolean
Default: false

Whether the attribute is scopable, i.e. can have one value by channel

is_required_for_completeness
boolean
Default: false

Whether the attribute should be part of the record's completeness calculation

max_characters
integer or null

Maximum number of characters allowed for the value of the attribute when the attribute type is text

is_textarea
boolean
Default: false

Whether the UI should display a text area instead of a simple field when the attribute type is text

is_rich_text_editor
boolean
Default: false

Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text

validation_rule
string
Default: "none"
Enum: "email" "url" "regular_expression" "none"

Validation rule type used to validate the attribute value when the attribute type is text

validation_regexp
string or null

Regexp expression used to validate the attribute value when the attribute type is text

allowed_extensions
Array of strings
Default: []

Extensions allowed when the attribute type is image

max_file_size
string or null

Max file size in MB when the attribute type is image

decimals_allowed
boolean
Default: false

Whether decimals are allowed when the attribute type is number

min_value
string or null

Minimum value allowed when the attribute type is number

max_value
string or null

Maximum value allowed when the attribute type is number

Responses

Request samples

Content type
application/json
{
  • "code": "description",
  • "labels": {
    },
  • "type": "text",
  • "value_per_locale": true,
  • "value_per_channel": false,
  • "is_required_for_completeness": true,
  • "is_textarea": true,
  • "is_rich_text_editor": true,
  • "validation_rule": "none"
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Reference entity attribute option

A reference entity attribute option is a value that can be associated with a reference entity attribute. For example, if you have a reference entity attribute called "Category", the options could be "Electronics", "Clothing", "Books", etc. Options are used to provide predefined values for reference entity attributes, making it easier to manage and maintain reference entity data.

Get a list of attribute options of a given attribute for a given reference entity

This endpoint allows you to get a list of attribute options for a given reference entity

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get an attribute option for a given attribute of a given reference entity

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

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "global_nomad",
  • "labels": {
    }
}

Update/create a reference entity attribute option

This endpoint allows you to update a given option for a given attribute and a given reference entity. Learn more about Update behavior. Note that if the option does not already exist for the given attribute of the given reference entity, it creates it.

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

JSON payload to create or update a reference entity attribute option

code
required
string

Attribute's option code

object
Default: {}

Attribute labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "global_nomad",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Reference entity record

A reference entity record is a specific instance of a reference entity. It contains the values for the attributes defined in the reference entity. Reference entity records can be linked to products or product models, allowing you to associate additional information with them.

Get the list of the records of a reference entity

This endpoint allows you to get a list of records of a given reference entity. Records are paginated and can be filtered.

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

query Parameters
search
string
Examples:
  • search={"code":[{"operator":"IN","value":["code1","code2"]}]} - Filter the records by their code
  • search={"complete":{"operator":"=","value":true,"channel":"ecommerce","locales":["en_US"]}} - Filter the records to get only the completed ones on a given channel for given locales
  • search={"updated":[{"operator":">","value":"2018-07-04T10:00:00+00:00"}]} - Filter the records by their update date

Filter records of the reference entity, for more details see the Filters

channel
string
Example: channel=ecommerce

Filter record values to return scopable record attributes for the given channel as well as the non localizable/non scopable record attributes, for more details see the Filter record values by channel section.

locales
string
Example: locales=en_US,fr_FR

Filter record values to return localizable record attributes for the given locales as well as the non localizable/non scopable record attributes, for more details see the Filter record values by locale section.

search_after
string
Default: "cursor to the first page"
Example: search_after=qaXbcde

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.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "_embedded": {
    }
}

Update/create several reference entity records

This endpoint allows you to update and/or create several records of a reference entity. Learn more about Update behavior. If a record with the specified code does not already exist, it will be created.

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

Request Body schema: application/json
required

Payload containing one or more reference entity records to create or update

Array
code
required
string

Code of the record

required
object

Record attribute values

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get a record of a given reference entity

Retrieve a specific record of a reference entity

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "kartell",
  • "values": {
    },
  • "created": "2021-01-01T01:23:34+00:00",
  • "updated": "2021-02-03T23:45:59+00:00"
}

Update or create a record of a given reference entity

This endpoint allows you to update a given record of a given reference entity. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.

Authorizations:
bearerToken
path Parameters
reference_entity_code
required
string
Example: brands

This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate. It is essential for identifying the specific reference entity in the API requests. Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Reference entity record to create or update

code
required
string

Code of the record

object

Record attribute values

Responses

Request samples

Content type
application/json
{
  • "code": "kartell",
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}

Reference entity media file

A reference entity media file is a file that can be attached to a reference entity record. It can be an image, a video, a PDF, or any other type of file. Reference entity media files are used to enrich the reference entity information and provide additional context to the reference entities.

Create a new media file for a reference entity or a record

This endpoint allows you to create a new media file and associate it to the image of a reference entity, or to the main image or to an attribute value of a record

Authorizations:
bearerToken
Request Body schema: multipart/form-data
required

Media file to upload

file
required
string <binary>

The media file to upload

Responses

Request samples

Content type
multipart/form-data
{
  "file": ""
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Download the media file associated to a reference entity or a record

This endpoint allows you to download a given media file that is associated with a reference entity or a record

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Asset family

An asset family is a set of attributes that are shared by assets belonging to this family. In other words, an asset family can be considered as a template for assets.

Get list of asset families

This endpoint allows you to get a list of asset families. Asset families are paginated.

Authorizations:
bearerToken
query Parameters
search_after
string
Default: "cursor to the first page"
Example: search_after=qaXbcde

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.

Responses

Response samples

Content type
application/json
{
  • "_links": {},
  • "_embedded": {
    }
}

Get an asset family

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

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "model_pictures",
  • "labels": {
    },
  • "attribute_as_main_media": "main_image",
  • "naming_convention": {
    },
  • "product_link_rules": [
    ],
  • "transformations": [
    ],
  • "sharing_enabled": true
}

Update/create an asset family

This endpoint allows you to update a given asset family. Note that if the asset family does not already exist, it creates it.

Authorizations:
bearerToken
path Parameters
code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

The asset family to be patched

code
required
string

Asset family code

object
Default: {}

Asset family labels for each locale. The localeCode must be the code of an existing and activated locale.

attribute_as_main_media
string or null
Default: "First media file or media link attribute that was created"

Attribute code that is used as the main media of the asset family

object
Default: {}

The naming convention run over the asset code or the main media filename upon each asset creation, in order to automatically set several values in asset attributes. To learn more and see the format of this property, take a look at here.

Array of objects
Default: []

The rules that will be run after the asset creation, in order to automatically link the assets of this family to a set of products. To understand the format of this property, see here.

Array of objects
Default: []

The transformations to perform on source files in order to generate new files into your asset attributes. To understand the format of this property, see here.

sharing_enabled
boolean

Share links are available/unavailable for media file attributes of all the assets in this family

Responses

Request samples

Content type
application/json
{
  • "code": "model_pictures",
  • "labels": {
    },
  • "attribute_as_main_media": "main_image",
  • "naming_convention": {
    },
  • "product_link_rules": [
    ],
  • "transformations": [
    ],
  • "sharing_enabled": true
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Asset attribute

An asset attribute is a piece of information that can be associated with an asset. Asset attributes can be used to store various types of data, such as text, numbers, dates, or media files. They are used to define the characteristics of assets and to provide additional information about them.

Get the list of attributes of a given asset family

This endpoint allows you to get the list of attributes of a given asset family

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get an attribute of a given asset family

This endpoint allows you to get the information about a given attribute for a given asset family

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "model_is_wearing_size",
  • "labels": {
    },
  • "type": "single_option",
  • "value_per_locale": false,
  • "value_per_channel": false,
  • "is_required_for_completeness": true,
  • "is_read_only": false
}

Update/create an attribute of a given asset family

This endpoint allows you to update a given attribute for a given asset family. Note that if the attribute does not already exist for the given asset family, it creates it.

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Body of the request containing the attribute to create or update

code
required
string

Attribute code

object
Default: {}

Attribute labels for each locale

type
required
string
Enum: "text" "media_link" "number" "media_file" "single_option" "multiple_options" "boolean" "date" "record" "asset_family_single_link" "asset_family_multiple_links" "auto_tagging"

Attribute type. See type section for more details.

value_per_locale
boolean
Default: false

Whether the attribute is localizable, i.e. can have one value by locale

value_per_channel
boolean
Default: false

Whether the attribute is scopable, i.e. can have one value by channel

is_required_for_completeness
boolean
Default: false

Whether the attribute should be part of the record's completeness calculation

is_read_only
boolean
Default: false

Whether the attribute should be in read only mode only in the UI, but you can still update it with the API

max_characters
integer or null

Maximum number of characters allowed for the value of the attribute when the attribute type is text

is_textarea
boolean
Default: false

Whether the UI should display a text area instead of a simple field when the attribute type is text

is_rich_text_editor
boolean

Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text

validation_rule
string or null
Default: "none"
Enum: "email" "url" "regular_expression" "none" null

Validation rule type used to validate the attribute value when the attribute type is text

validation_regexp
string or null
Default: null

Regexp expression used to validate the attribute value when the attribute type is text

allowed_extensions
Array of strings
Default: []

Extensions allowed when the attribute type is media_file

max_file_size
string or null
Default: null

Max file size in MB when the attribute type is media_file

decimals_allowed
boolean
Default: false

Whether decimals are allowed when the attribute type is number

min_value
string or null
Default: null

Minimum value allowed when the attribute type is number

max_value
string or null
Default: null

Maximum value allowed when the attribute type is number

media_type
string
Enum: "image" "pdf" "youtube" "vimeo" "other"

For the media_link attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the media_file attribute type, it is the type of the file.

prefix
string or null
Default: null

Prefix of the media_link attribute type. The common url root that prefixes the link to the media.

suffix
string or null
Default: null

Suffix of the media_link attribute type. The common url suffix for the media.

reference_entity
string or null
Default: null

Reference entity code for the record attribute type (see Reference entity)

asset_family_code
string or null
Default: null

Asset family code for the asset_family_single_link and asset_family_multiple_links attribute types

Responses

Request samples

Content type
application/json
{
  • "code": "model_is_wearing_size",
  • "labels": {
    },
  • "type": "single_option",
  • "value_per_locale": false,
  • "value_per_channel": false,
  • "is_required_for_completeness": true,
  • "is_read_only": false
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Asset attribute option

An asset attribute option is a value that can be associated with an asset attribute. For example, if you have an asset attribute called "Type", the options could be "Image", "Video", "Document", etc. Options are used to provide predefined values for asset attributes, making it easier to manage and maintain asset data.

Get a list of attribute options of a given attribute for a given asset family

This endpoint allows you to get a list of attribute options for a given asset family

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get an attribute option for a given attribute of a given asset family

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

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Responses

Response samples

Content type
application/json
{
  • "code": "small",
  • "labels": {
    }
}

Update/create an asset attribute option for a given asset family

This endpoint allows you to update a given option for a given attribute and a given asset family. Learn more about the Update behavior. Note that if the option does not already exist for the given attribute of the given asset family, it creates it.

Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
Example: packshot

This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.

attribute_code
required
string
Example: color

This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate. It is essential for identifying the specific attribute in the API requests. Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.

code
required
string
Example: my_entity_code

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.

Request Body schema: application/json
required

Body of the request containing the asset family attribute option to create or update

code
required
string

Attribute's option code

object
Default: {}

Attribute option labels for each locale

Responses

Request samples

Content type
application/json
{
  • "code": "small",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}

Asset media file

An asset media file is a file that can be attached to an asset family or an asset. It can be an image, a video, a PDF, or any other type of file. Asset media files are used to enrich the asset information and provide additional context to the assets.

Create a new media file for an asset

This endpoint allows you to create a new media file and associate it to a media file attribute value of an asset

Authorizations:
bearerToken
Request Body schema: multipart/form-data
required

The media file to be uploaded. The file must be a valid media type (e.g., image, video, audio) and should not exceed the maximum allowed size. The file will be associated with an asset's media file attribute value.

file
required
string <binary>

The binary of the media file

Responses

Request samples

Content type
multipart/form-data
 Response samples 
Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}
Download the media file associated to an asset 
This endpoint allows you to download a given media file that is associated with an asset


Authorizations:
bearerToken
path Parameters
code
required
string
 
 Example:  my_entity_code
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.


Responses
 Response samples 
Content type
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
Asset
An asset is a flexible object that makes it possible to enrich products with images, videos, documents…
An asset must be part of an asset family. That way, it will have its own attributes and lifecycle.
Assets can be linked to products and product models, in order to enrich them.


Get the list of the assets of a given asset family 
This endpoint allows you to get a list of assets of a given asset family.
Assets are paginated.
This endpoint is case sensitive on the asset family code.


Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
 
 Example:  packshot
This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate.
It is essential for identifying the specific asset family in the API requests.
Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.


query Parameters
search
string
  Examples: 
  • search={"code":[{"operator":"IN","value":["code1","code2"]}]} - Filter the assets by their code
  • search={"updated":[{"operator":">","value":"2018-07-04T10:00:00Z"}]} - Filter the assets by their update date
  • search={"updated":[{"operator":"NOT BETWEEN","value":["2018-07-04T10:00:00Z","2018-08-04T10:00:00Z"]}]} - Filter the assets that were updated over a period of time
  • search={"updated":[{"operator":"SINCE LAST N DAYS","value":4}]} - Filter the assets that were updated since X days
Filter assets,
for more details see the Asset filters section.


channel
string
 
 Example:  channel=ecommerce
Filter asset values to return scopable asset attributes for the given channel as well as the non localizable/non scopable asset attributes,
for more details see the Filter asset values by channel section.


locales
string
 
 Example:  locales=en_US,fr_FR
Filter asset values to return localizable asset attributes for the given locales as well as the non localizable/non scopable asset attributes,
for more details see the Filter asset values by locale section.


search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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.


with_asset_auto_tags
boolean
 Default:  false
 
 Example:  with_asset_auto_tags=true
Return labels of asset tags generated by auto-tagging in the response.
When set to true, the response will include human-readable labels for asset tags alongside their codes.
If set to false, the response will only include tag codes, which can improve performance.
See the linked_data format section for more details.


Responses
 Response samples 
Content type
application/json
{}
Update/create several assets 
This endpoint allows you to update and/or create several assets of one given asset family at once.
Learn more about the Update behavior.
Note that if the asset does not already exist for the given asset family, it creates it.
This endpoint is case sensitive on the asset family code.


Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
 
 Example:  packshot
This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate.
It is essential for identifying the specific asset family in the API requests.
Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.


Request Body schema: application/json
required
Body of the request containing the assets to create or update


 Array 
code
required
string
 
Code of the asset


asset_family_code
string
 
Code of the asset family


object
 
Asset attributes values.
See the Focus on the asset values section for more details.


Responses
 Request samples 
Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
 Response samples 
Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Get an asset of a given asset family 
This endpoint allows you to get the information about a given asset for a given asset family.
This endpoint is case sensitive on the asset family code.


Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
 
 Example:  packshot
This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate.
It is essential for identifying the specific asset family in the API requests.
Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.


code
required
string
 
 Example:  my_entity_code
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_auto_tags
boolean
 Default:  false
 
 Example:  with_asset_auto_tags=true
Return labels of asset tags generated by auto-tagging in the response.
When set to true, the response will include human-readable labels for asset tags alongside their codes.
If set to false, the response will only include tag codes, which can improve performance.
See the linked_data format section for more details.


Responses
 Response samples 
Content type
application/json
{
  • "code": "sku_54628_picture1",
  • "values": {
    },
  • "created": "2021-05-31T09:23:34+00:00",
  • "updated": "2021-05-31T09:23:34+00:00"
}
Update/create an asset 
This endpoint allows you to update a given asset of a given asset family.
Learn more about the Update behavior.
Note that if the asset does not already exist for the given asset family, it creates it.
This endpoint is case sensitive on the asset family code.


Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
 
 Example:  packshot
This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate.
It is essential for identifying the specific asset family in the API requests.
Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.


code
required
string
 
 Example:  my_entity_code
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.


Request Body schema: application/json
required
Body of the request containing the asset to create or update


code
required
string
 
Code of the asset


asset_family_code
string
 
Code of the asset family


object
 
Asset attributes values.
See the Focus on the asset values section for more details.


Responses
 Request samples 
Content type
application/json
{
  • "code": "sku_54628_picture1",
  • "values": {
    },
  • "created": "2021-05-31T09:23:34+00:00",
  • "updated": "2021-05-31T09:23:34+00:00"
}
 Response samples 
Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}
Delete an asset 
This endpoint allows you to delete a given asset.
This endpoint is case sensitive on the asset family code.


Authorizations:
bearerToken
path Parameters
asset_family_code
required
string
 
 Example:  packshot
This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate.
It is essential for identifying the specific asset family in the API requests.
Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system.


code
required
string
 
 Example:  my_entity_code
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.


Responses
 Response samples 
Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}
Catalogs
A catalog is a collection of products that can be managed in the PIM.
It allows you to create a subset of products that can be used in specific contexts, such as online stores, mobile applications, or print catalogs.
Catalogs can have their own configurations, such as channels, locales, and measurement systems.


Get the list of owned catalogs 
This endpoint allows you to get the list of catalogs you owned


Authorizations:
appToken
query Parameters
page
integer
 Default:  1
 
 Example:  page=1
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


Responses
 Response samples 
Content type
application/json
{}
Create a new catalog 
This endpoint allows you to create a new catalog


Authorizations:
appToken
Request Body schema: application/json
The catalog to create


name
required
string
 
Catalog name


managed_currencies
Array of strings
 
List of currency codes


managed_locales
Array of strings
 
List of locale codes


Responses
 Request samples 
Content type
application/json
{
  • "name": "My app catalog",
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
 Response samples 
Content type
application/json
{
  • "id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
  • "name": "My app catalog",
  • "enabled": false,
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
Get a catalog 
This endpoint allows you to get the information about a catalog


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Responses
 Response samples 
Content type
application/json
{
  • "id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
  • "name": "My app catalog",
  • "enabled": false,
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
Update a catalog 
This endpoint allows you to update a catalog


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Request Body schema: application/json
The catalog to update


name
string
 
Catalog name


managed_currencies
Array of strings
 
List of currency codes


managed_locales
Array of strings
 
List of locale codes


Responses
 Request samples 
Content type
application/json
{
  • "name": "My app catalog",
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
 Response samples 
Content type
application/json
{
  • "id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
  • "name": "My app catalog",
  • "enabled": false,
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
Delete a catalog 
This endpoint allows you to delete a catalog.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Responses
 Response samples 
Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}
Duplicate a catalog 
This endpoint allows you to duplicate an existing catalog.
Note that the duplicated catalog will be deactivated (set to false).


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Request Body schema: application/json
The catalog to duplicate


name
string
 
Catalog name (optional for duplication)


managed_currencies
Array of strings
 
List of currency codes


managed_locales
Array of strings
 
List of locale codes


skip_required_checks
boolean
 Default:  false
 
Option to skip required checks


replace_mapping_locales_with
string
 
When provided, replaces all locale codes in the catalog's product mapping with this locale code


property name*
additional property
any
 
Responses
 Request samples 
Content type
application/json
Example
{ }
 Response samples 
Content type
application/json
{
  • "id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
  • "name": "My app catalog",
  • "enabled": false,
  • "managed_currencies": [
    ],
  • "managed_locales": [
    ]
}
Catalog products
A catalog contains a selection of products from the PIM, intended to be synchronized with a third-party application via the API.
The Catalog products endpoint allows you to retrieve the list of products for a given catalog, with options to filter, paginate, and select the returned fields.
Each returned product includes its attributes, values, status information, and associated references, all in the context of the catalog.
This endpoint is mainly used by Apps to synchronize product data between Akeneo PIM and external platforms, while respecting access rights and catalog configuration.


Get the list of product uuids 
This endpoint allows you to get the list of uuids of products contained in a catalog.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


query Parameters
search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


updated_before
string <date> 
 
 Example:  updated_before=2025-05-17T10:00:00Z
Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


updated_after
string <date> 
 
 Example:  updated_after=2025-06-17T10:00:00Z
Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


with_count
boolean
 Default:  false
 
 Example:  with_count=true
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.


Responses
 Response samples 
Content type
application/json
{}
Get the list of products related to a catalog 
This endpoint allows you to get the list of products related to a catalog.
Products are paginated and they can be filtered. In the Enterprise Edition,
permissions based on your app settings are applied to the set of products you request.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


query Parameters
search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


updated_before
string <date> 
 
 Example:  updated_before=2025-05-17T10:00:00Z
Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


updated_after
string <date> 
 
 Example:  updated_after=2025-06-17T10:00:00Z
Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


Responses
 Response samples 
Content type
application/json
{
  • "_links": {},
  • "_embedded": {
    }
}
Get a product related to a catalog 
This endpoint allows you to get a specific product related to a catalog.
In the Enterprise Edition, permissions based on your app settings are applied on the product you request.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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.


Responses
 Response samples 
Content type
application/json
{
  • "uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
  • "enabled": true,
  • "family": "tshirt",
  • "categories": [
    ],
  • "groups": [ ],
  • "values": {
    },
  • "created": "2016-06-23T18:24:44+02:00",
  • "updated": "2016-06-25T17:56:12+02:00",
  • "associations": {
    },
  • "quantified_associations": {
    },
  • "root_parent": "clothes",
  • "quality_scores": [
    ],
  • "completenesses": [
    ],
  • "workflow_execution_statuses": [
    ]
}
Get the list of mapped flattened products or simple products related to a catalog 
This endpoint is available when the mapping is enabled on a specified catalog.
When the mapping is in a basic mode, this endpoint allows you to get the list of all flattened products related to the catalog.
When it's in models/variants mode, this endpoint allows you to get the list of simple products with all specified targets in the two levels of the mapping schema.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


query Parameters
search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


updated_before
string <date> 
 
 Example:  updated_before=2025-05-17T10:00:00Z
Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


updated_after
string <date> 
 
 Example:  updated_after=2025-06-17T10:00:00Z
Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


Responses
 Response samples 
Content type
application/json
{}
Get the list of mapped models related to a catalog 
This endpoint allows you to get the list of models related to a catalog when the mapping is enabled with a models/variants schema.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


query Parameters
search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


updated_before
string <date> 
 
 Example:  updated_before=2025-05-17T10:00:00Z
Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


updated_after
string <date> 
 
 Example:  updated_after=2025-06-17T10:00:00Z
Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


Responses
 Response samples 
Content type
application/json
{}
Get the list of mapped variants of a model related to a catalog 
This endpoint allows you to get the list of variants of a model related to a catalog when the mapping is enabled.
Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message,
for more details see the App Catalog section.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


model_code
required
string
 
Model code


query Parameters
search_after
string
 Default:  "cursor to the first page"
 
 Example:  search_after=qaXbcde
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  [ 1 .. 100 ] 
 Default:  10
 
 Example:  limit=100
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.


updated_before
string <date> 
 
 Example:  updated_before=2025-05-17T10:00:00Z
Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


updated_after
string <date> 
 
 Example:  updated_after=2025-06-17T10:00:00Z
Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.


Responses
 Response samples 
Content type
application/json
{}
Mapping schema for products
The mapping schema for products defines the expected structure of product data when synchronizing via the API.
It describes the fields, their types, constraints, and transformation rules applied during the export or import of products in a catalog connected to an App.
This schema ensures data consistency between Akeneo PIM and third-party applications by clarifying how PIM attributes correspond to those expected by the App.
For each field, the schema specifies the data type (text, number, boolean, etc.), whether the field is required or optional, and any allowed values or transformations to apply.


Get the product mapping schema related to a catalog 
This endpoint allows you to retrieve the product mapping schema related to a catalog.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Responses
 Response samples 
Content type
application/json
{
  • "$id": "https://example.com/product",
  • "$schema": "https://api.akeneo.com/mapping/product/1.0.3/schema",
  • "type": "object",
  • "properties": {
    }
}
Create or update the product mapping schema related to a catalog 
This endpoint allows you to create or update the product mapping schema related to a catalog.
See documentation to define your JSON schema.


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Request Body schema: application/json
Body containing the product mapping schema to create or update


$id
string
 
id of your schema


$schema
required
string
 
$schema indicates which product mapping schema version your app uses


$comment
string
 
allows you to add a comment


title
string
 
allows you to add a title to your mapping schema


description
string
 
allows you to add a description of your mapping schema


type
string
 Value: "object" 
 
should always be "object"


properties
required
object
 
list and describe the targets your app expects


Responses
 Request samples 
Content type
application/json
{
  • "$id": "https://example.com/product",
  • "$schema": "https://api.akeneo.com/mapping/product/1.0.3/schema",
  • "type": "object",
  • "properties": {
    }
}
 Response samples 
Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}
Delete the product mapping schema related to a catalog 
This endpoint allows you to delete the product mapping schema related to a catalog


Authorizations:
appToken
path Parameters
id
required
string <uuid> 
 
 Example:  12351d98-200e-4bbc-aa19-7fdda1bd14f2
This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.


Responses
 Response samples 
Content type
application/json
{
  • "code": 401,
  • "message": "Authentication is required"
}
Overview
This API reference provides comprehensive documentation for the Akeneo PIM REST API.
It describes all available endpoints, request and response formats, authentication methods, and error codes.
The Akeneo PIM REST API enables you to interact programmatically with your PIM instance, allowing you to manage products, product models, attributes, categories, assets, reference entities, and more.
You can use the API to integrate Akeneo PIM with other systems, automate data flows, and build custom applications.
All API endpoints are organized by resource type and support standard HTTP methods (GET, POST, PUT, PATCH, DELETE).
Authentication is required for all endpoints and is based on OAuth 2.0 or HTTP Basic authentication.
For more details, please refer to the official Akeneo API documentation.


Get list of all endpoints 
This endpoint allows you to get the list of all the available endpoints. 
No need to be authenticated to use this endpoint.


Authorizations:
bearerToken
Responses
 Response samples 
Content type
application/json
{
  • "host": "https://demo.akeneo.com",
  • "authentication": {
    },
  • "routes": {
    }
}
Authentication
The Authentication endpoints provide methods to authenticate and authorize access to the Akeneo PIM API.
You can use these endpoints to obtain an access token, which is required for accessing protected resources in the API.
The authentication process typically involves providing credentials (username and password) or using OAuth 2.0 for secure access.


Get an authentication token 
This endpoint allows you to get an authentication token. 
No need to be authenticated to use this endpoint. 
Want to get your token directly in the API reference? 
Check the Get your API token guide.


Authorizations:
basicToken
header Parameters
Content-Type
required
string
 Default:  application/json
 
 Example:  application/json
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.


Authorization
required
string
 
This header is used to authenticate requests to the API.
Equal to 'Basic xx', where 'xx' is the base 64 encoding of the client id and secret. 
Find out how to generate them in the Client ID/secret generation section.


Request Body schema: application/json
Request body for the token generation endpoint.
This endpoint is used to generate an access token for the Akeneo PIM API.


username
required
string
 
Your PIM username, field username in your PIM connection settings. 
See here for more details.


password
required
string
 
Your PIM password, field password in your PIM connection settings. 
See here for more details.


grant_type
required
string
 Default:  "password"
 
Always equal to password


Responses
 Request samples 
Content type
application/json
{
  • "username": "admin",
  • "password": "admin",
  • "grant_type": "password"
}
 Response samples 
Content type
application/json
{
  • "access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
  • "expires_in": 3600,
  • "token_type": "bearer",
  • "scope": null,
  • "refresh_token": "M3FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
}
System
The System endpoints provide information about the Akeneo PIM instance and its environment.
You can use these endpoints to retrieve details such as the PIM version, edition, enabled features, and system health.
This information is useful for monitoring, troubleshooting, and ensuring compatibility with integrations or applications that interact with the PIM API.


Get system information 
This endpoint allows you to get the version and the edition of the PIM


Authorizations:
bearerToken
Responses
 Response samples 
Content type
application/json
{
  • "version": "v20250717143807",
  • "edition": "Serenity"
}
UI Extensions
UI Extensions allow you to extend the Akeneo PIM user interface with custom components.
They can be used to add new features or to modify the existing ones.
UI Extensions are useful for integrating with external systems or for providing additional functionality to the PIM.


List UI extensions 
List all UI extensions associated with your token


Authorizations:
bearerToken
Responses
 Response samples 
Content type
application/json
[
  • {
    },
  • {
    }
]
Create a new UI extension 
This endpoint allows you to create a new UI extension.
default_label and url configuration fields are mandatory for all UI extensions.
secret is optional and only available for action UI extension.


Authorizations:
bearerToken
Request Body schema: application/json
body of the UI extension to create


name
required
string
 
Name of the extension, shown within the Administration interface


description
string
 
Short description, shown within the Administration interface


version
string
 
Version of the extension, shown within the Administration
interface


position
required
string
 
Position of the UI extension


type
required
string
 
Type of the UI extension


object
 
Configuration options that are specific to the UI extension type


status
string
 
Status of the UI extension (active or inactive)


Array of credential_custom_header (object) or credential_bearer_token (object) or credential_basic_auth (object)
 
Credentials for the UI extension


Responses
 Request samples 
Content type
application/json
{
  • "name": "my_awesome_button_extension",
  • "type": "iframe",
  • "position": "pim.product.tab",
  • "configuration": {
    },
  • "version": "V1.02.3",
  • "description": "A short human readable description."
}
 Response samples 
Content type
application/json
{
  • "uuid": "d414135b-ff4d-44e1-8cb6-fce64cbe29c0",
  • "name": "my_awesome_iframe_extension",
  • "type": "iframe",
  • "position": "pim.product.tab",
  • "configuration": {
    },
  • "status": "active",
  • "credentials": [ ],
  • "version": "V1.02.3",
  • "description": "A short human readable description."
}
Update a UI extension 
This endpoint allows you to update an existing UI extension.
You can send only the fields that you want to update.
If a field is not sent, the previous value is kept.
This endpoint is also available as POST, prefer the POST if you need to upload a file.


Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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.


Request Body schema: application/json
required
body of the UI extension to update


name
string
 
Name of the extension, shown within the Administration interface


description
string
 
Short description, shown within the Administration interface


version
string
 
Version of the extension, shown within the Administration
interface


position
string
 
Position of the UI extension


type
string
 
Type of the UI extension


object
 
Configuration options that are specific to the UI extension type


status
string
 
Status of the UI extension (active or inactive)


Array of credential_custom_header (object) or credential_bearer_token (object) or credential_basic_auth (object)
 
Credentials for the UI extension


Responses
 Request samples 
Content type
application/json
{
  • "type": "link",
  • "position": "pim.product.header",
  • "version": "V1.02.4"
}
 Response samples 
Content type
application/json
{
  • "uuid": "d414135b-ff4d-44e1-8cb6-fce64cbe29c0",
  • "name": "my_awesome_iframe_extension",
  • "type": "iframe",
  • "position": "pim.product.tab",
  • "configuration": {
    },
  • "status": "active",
  • "credentials": [ ],
  • "version": "V1.02.3",
  • "description": "A short human readable description."
}
Delete a UI extension 
This endpoint allows you to delete a given UI extension


Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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.


Responses
 Response samples 
Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}
Workflows
The Workflows endpoints allow you to retrieve the configuration of the Workflows and Steps.


Get list of workflows 
Retrieves a paginated list of workflows


Authorizations:
bearerToken
query Parameters
page
integer
 Default:  1
 
 Example:  page=1
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  [ 1 .. 100 ] 
 Default:  100
 
 Example:  limit=100
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.


Responses
 Response samples 
Content type
application/json
{}
Get a workflow 
This endpoint allows you to get the information about a given workflow as well as its steps


Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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.


Responses
 Response samples 
Content type
application/json
{
  • "uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
  • "code": "enrichment_workflow",
  • "labels": {
    },
  • "enabled": true,
  • "steps": [
    ]
}
Get list of workflow step assignees 
Retrieves a paginated list of assignees for a specified workflow step


Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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
page
integer
 Default:  1
 
 Example:  page=1
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  [ 1 .. 100 ] 
 Default:  100
 
 Example:  limit=100
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.


Responses
 Response samples 
Content type
application/json
{}
Workflow executions
The Workflow executions endpoints allow you to start workflows on products and product models.


Start several workflow executions 
This endpoint allows you to start workflow executions for products and/or product models


Authorizations:
bearerToken
Request Body schema: application/json
required
An array of objects, each containing workflow information and either a product or a product model to be included in a workflow


 Array (<= 100 items)
 One of 
required
object
 
Workflow UUID


required
object
 
Product UUID


Responses
 Request samples 
Content type
application/json
Example
[
  • {
    },
  • {
    }
]
 Response samples 
Content type
application/json
{
  • "code": 207,
  • "message": "Workflow executions started with some errors",
  • "processed": 2,
  • "errors": [
    ]
}
Workflow tasks
The Tasks endpoints allow you to retrieve the tasks for each workflow steps, products and product models.
It also allows you to manage the tasks by approving, rejecting or completing them.


Get list of workflow tasks 
Retrieves a paginated list of tasks for a specified workflow step


Authorizations:
bearerToken
query Parameters
search
required
string
  Examples: 
  • search={"step_uuid":[{"operator":"=","value":"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9"}]} - Search by step UUID
  • search={"step_uuid":[{"operator":"=","value":"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9"}],"product_uuid":[{"operator":"IN","value":["123e4567-e89b-12d3-a456-426614174000"]}]} - Search by product UUID
  • search={"step_uuid":[{"operator":"=","value":"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9"}],"product_model_code":[{"operator":"IN","value":["amor", "apollon]}]} - Search by product model code
Stringified JSON to filter tasks.
For more details see the Filters section.


with_attributes
boolean
 Default:  false
 
Whether to include task attributes in the response


page
integer
 Default:  1
 
 Example:  page=1
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  [ 1 .. 100 ] 
 Default:  100
 
 Example:  limit=100
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.


Responses
 Response samples 
Content type
application/json
Example
{}
Update a Workflow Task's Status (Approve, Reject, Complete) 
Completes or approves/rejects a task.
The request body's structure depends on the action being performed.


    

  • To approve a 'review' task, set status to approved.
    • 

  • To complete an 'enrichment' task, set status to completed.
    • 

  • To reject a 'review' task, set status to rejected, provide send_back_to_step_uuid, and optionally provide rejected_attributes to specify details about rejected attributes.
    • 



Authorizations:
bearerToken
path Parameters
uuid
required
string <uuid> 
 
 Example:  123e4567-e89b-12d3-a456-426614174000
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.


Request Body schema: application/json
The action to perform on the task, determined by the payload


 One of 
status
required
string
 Value: "rejected" 
 
Must be 'rejected' for this action


send_back_to_step_uuid
required
string <uuid> 
 
The UUID of the workflow step to which the task should be returned


object
 
Optionally provides details about which attributes were rejected.
For each attribute name you can specify a comment, the locale, and the scope for the rejection.


Responses
 Request samples 
Content type
application/json
Example
{
  • "status": "rejected",
  • "send_back_to_step_uuid": "123e4567-e89b-12d3-a456-426614174000",
  • "rejected_attributes": {
    }
}
 Response samples 
Content type
application/json
{
  • "code": 400,
  • "message": "Invalid JSON message received"
}