openapi: 3.2.0 info: title: Akeneo API REFERENCE Mapping schema for products API version: 1.0.0 description: '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.' license: name: Open Software License 3.0 url: http://opensource.org/licenses/OSL-3.0 contact: name: Akeneo Support url: https://www.akeneo.com/support-help-center/ email: contact@akeneo.com servers: - url: '{your-pim-url}' variables: your-pim-url: default: '' description: 'Set the PIM url you want to target ex: https://my-pim.cloud.akeneo.com or https://localhost:8443' tags: - name: Mapping schema for products description: '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.' paths: /api/rest/v1/catalogs/{id}/mapping-schemas/product: get: operationId: get_catalog_mapping_schema_product x-visibility: public summary: Get the product mapping schema related to a catalog description: This endpoint allows you to retrieve the product mapping schema related to a catalog. tags: - Mapping schema for products security: - appToken: [] parameters: - in: path name: id description: '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. ' required: true schema: type: string format: uuid example: 12351d98-200e-4bbc-aa19-7fdda1bd14f2 x-app-token: true responses: '200': description: Return product mapping schema related to a catalog content: application/json: schema: type: object required: - $schema - properties properties: $id: type: string description: id of your schema example: https://example.com/product $schema: type: string description: $schema indicates which product mapping schema version your app uses example: https://api.akeneo.com/mapping/product/1.0.0/schema $comment: type: string description: allows you to add a comment example: This is a comment about the mapping schema title: type: string description: allows you to add a title to your mapping schema example: Product Mapping Schema description: type: string description: allows you to add a description of your mapping schema example: This schema describes the product mapping for our application type: type: string description: should always be "object" enum: - object example: object properties: type: object description: list and describe the targets your app expects example: properties: code: title: Model ID type: string brand: title: Brand name type: string description: title: Product description type: string fabrics: title: Fabrics type: array items: type: string localized_names: title: Name with multiple locales type: array items: type: object properties: locale: type: string value: type: string required: - locale - value example: $id: https://example.com/product $schema: https://api.akeneo.com/mapping/product/1.0.3/schema type: object properties: code: title: Model ID type: string brand: title: Brand name type: string description: title: Product description type: string fabrics: title: Fabrics type: array items: type: string localized_names: title: Name with multiple locales type: array items: type: object properties: locale: type: string value: type: string required: - locale - value localized_number: type: array items: type: object properties: locale: type: string value: type: number required: - locale - value localized_link: type: array items: type: object properties: locale: type: string value: type: string format: uri required: - locale - value localized_datetime: type: array items: type: object properties: locale: type: string value: type: string format: date-time required: - locale - value localized_boolean: type: array items: type: object properties: locale: type: string value: type: boolean required: - locale - value variation_axes: type: array items: type: object properties: code: type: string label: type: array items: type: object properties: locale: type: string value: type: string variants: oneOf: - type: string format: uri - type: array items: type: object properties: variation_axes_values: type: array items: type: object properties: code: type: string value: oneOf: - type: - string - boolean - type: object properties: amount: type: number unit: type: string label: type: array items: type: object properties: locale: type: string value: type: string uuid: title: uuid type: string sku: title: SKU type: string position: title: Position type: number price: title: Price type: string response_time: title: Response time type: string localized_product_photos_media_file: title: Photos with value per locale(links) type: array items: type: object properties: locale: type: string value: type: array items: type: string format: uri required: - locale - value localized_prices: title: Price in multiple currencies with value per locale type: array items: type: object properties: locale: type: string value: type: array items: type: object properties: amount: type: number currency: type: string required: - amount - currency required: - locale - value required: - uuid '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. put: operationId: put_catalog_mapping_schema_product x-visibility: public summary: Create or update the product mapping schema related to a catalog description: 'This endpoint allows you to create or update the product mapping schema related to a catalog. See documentation to define your JSON schema.' tags: - Mapping schema for products security: - appToken: [] parameters: - in: path name: id description: '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. ' required: true schema: type: string format: uuid example: 12351d98-200e-4bbc-aa19-7fdda1bd14f2 x-app-token: true requestBody: description: Body containing the product mapping schema to create or update content: application/json: schema: type: object required: - $schema - properties properties: $id: type: string description: id of your schema example: https://example.com/product $schema: type: string description: $schema indicates which product mapping schema version your app uses example: https://api.akeneo.com/mapping/product/1.0.0/schema $comment: type: string description: allows you to add a comment example: This is a comment about the mapping schema title: type: string description: allows you to add a title to your mapping schema example: Product Mapping Schema description: type: string description: allows you to add a description of your mapping schema example: This schema describes the product mapping for our application type: type: string description: should always be "object" enum: - object example: object properties: type: object description: list and describe the targets your app expects example: properties: code: title: Model ID type: string brand: title: Brand name type: string description: title: Product description type: string fabrics: title: Fabrics type: array items: type: string localized_names: title: Name with multiple locales type: array items: type: object properties: locale: type: string value: type: string required: - locale - value example: $id: https://example.com/product $schema: https://api.akeneo.com/mapping/product/1.0.3/schema type: object properties: code: title: Model ID type: string brand: title: Brand name type: string description: title: Product description type: string fabrics: title: Fabrics type: array items: type: string localized_names: title: Name with multiple locales type: array items: type: object properties: locale: type: string value: type: string required: - locale - value localized_number: type: array items: type: object properties: locale: type: string value: type: number required: - locale - value localized_link: type: array items: type: object properties: locale: type: string value: type: string format: uri required: - locale - value localized_datetime: type: array items: type: object properties: locale: type: string value: type: string format: date-time required: - locale - value localized_boolean: type: array items: type: object properties: locale: type: string value: type: boolean required: - locale - value variation_axes: type: array items: type: object properties: code: type: string label: type: array items: type: object properties: locale: type: string value: type: string variants: oneOf: - type: string format: uri - type: array items: type: object properties: variation_axes_values: type: array items: type: object properties: code: type: string value: oneOf: - type: - string - boolean - type: object properties: amount: type: number unit: type: string label: type: array items: type: object properties: locale: type: string value: type: string uuid: title: uuid type: string sku: title: SKU type: string position: title: Position type: number price: title: Price type: string response_time: title: Response time type: string localized_product_photos_media_file: title: Photos with value per locale(links) type: array items: type: object properties: locale: type: string value: type: array items: type: string format: uri required: - locale - value localized_prices: title: Price in multiple currencies with value per locale type: array items: type: object properties: locale: type: string value: type: array items: type: object properties: amount: type: number currency: type: string required: - amount - currency required: - locale - value required: - uuid responses: '204': description: Successfully created or updated product mapping schema, empty response body '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '415': description: 'This response indicates that the `Content-type` header of the request is not supported by the server. The server expects the `Content-type` header to be `application/json`, and any other value will result in this error. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 415 message: xxx in `Content-type` header is not valid. Only `application/json` is allowed." '422': description: 'This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 422 message: type: string description: Message explaining the error example: Validation failed. example: code: 422 message: Validation failed. delete: operationId: delete_catalog_mapping_schema_product x-visibility: public summary: Delete the product mapping schema related to a catalog description: This endpoint allows you to delete the product mapping schema related to a catalog tags: - Mapping schema for products security: - appToken: [] parameters: - in: path name: id description: '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. ' required: true schema: type: string format: uuid example: 12351d98-200e-4bbc-aa19-7fdda1bd14f2 x-app-token: true responses: '204': description: 'No content to return. Means that the deletion was successful. ' '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. components: securitySchemes: basicToken: scheme: basic type: http description: 'HTTP Basic authentication using user credentials. [More information here](https://api.akeneo.com/documentation/authentication.html) ' bearerToken: scheme: bearer type: http description: 'Bearer token obtained via the "Password Grant" flow. This token authenticates a user, is valid for one hour, and can be refreshed using a refresh token. [More information here](https://api.akeneo.com/documentation/authentication.html) ' appToken: scheme: bearer type: http description: 'Bearer token for Apps, obtained via the OAuth 2.0 flow. This permanent token allows an application to make requests on behalf of a user. [More information here](https://api.akeneo.com/apps/authentication-and-authorization.html) ' x-provenance: method: harvested publisher: Akeneo source: https://storage.googleapis.com/akecld-prd-pim-saas-shared-openapi-spec/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)