Mirakl Products API
The Products API from Mirakl — 11 operation(s) for products.
OpenAPI Specification
openapi: 3.1.0
info:
description: '{% partial file="/partial-content/product/connect-channel-platform/rest/connect/openapi-description.md" /%}'
title: Mirakl Connect Channel Platform APIs Carriers Products API
version: ''
servers:
- description: Connect Channel Platform API
url: https://miraklconnect.com/api/channel-platform
tags:
- name: Products
paths:
/api/mcm/products/sources/status/export:
get:
description: '<div class="extension-title">Description</div>
Delta export of the source product data sheet status in JSON format.
Define a cron job in your system that periodically calls this API and sets the previous
request date as the `updated_since` query parameter.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: <br/>- Differential: every 15 minutes</div>
<div class="max-call-frequency">Maximum usage: <br/>- Differential: every 5 minutes <br/>- Full: every 4 hours</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/mcm/page/topics/Mirakl/mcm/integration_mcm/cm11.htm">More context</a></li><li><a href="https://help.mirakl.com/bundle/mcm/page/topics/Mirakl/mcm/troubleshooting_mcm.htm">Error troubleshooting</a></li></ul></div>'
operationId: CM11
parameters:
- description: Export start date. Given date must respect ISO-8601 format and must be URL encoded
explode: true
in: query
name: updated_since
required: false
schema:
type: string
format: date-time
style: form
- description: Export end date. Given date must respect ISO-8601 format and must be URL encoded
explode: true
in: query
name: updated_to
required: false
schema:
type: string
format: date-time
style: form
- description: 'The status of the product : LIVE / NOT_LIVE'
explode: true
in: query
name: status
required: false
schema:
type: string
enum:
- LIVE
- NOT_LIVE
style: form
- description: The provider unique identifier of the product
explode: true
in: query
name: provider_unique_identifier
required: false
schema:
type: array
items:
type: string
maxItems: 100
minItems: 0
uniqueItems: true
style: form
- description: 'The unique identifier of the product with type (structure: \"unique_identifier=&UniqueIdentifierType1|UniqueIdentifierID1,UniqueIdentifierType2|UniqueIdentifierID2, ...\").'
explode: true
in: query
name: unique_identifier
required: false
schema:
type: array
items:
type: string
maxItems: 100
minItems: 0
uniqueItems: true
style: form
- description: The provider id
explode: true
in: query
name: provider_id
required: true
schema:
type: string
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
- errors:
- channels:
- BE
- FR
code: MCM-04012
message: The product has been rejected by the operator temporarily.
rejection_details:
message: This product is obsolete
reason_code: '2'
reason_label: The product does not fit the targeted audience
- channels:
- US
- CA
code: MCM-04012
message: The operator has requested changes to your product data.
rejection_details:
message: The description in English is not detailed enough.
reason_code: '5'
reason_label: A better description is required
- code: MCM-0L000
message: The product has not been synchronized yet.
- code: MCM-04000
integration_details:
- attribute_code: color
code: WARNING
message: is not mapped
message: The product integration contains errors.
provider_unique_identifier: shopSku1
status: NOT_LIVE
unique_identifiers:
- code: EAN
value: EAN1
- code: EAN
value: EAN2
- code: ISBN
value: ISBN1
warnings:
- attribute_code: mainImageLarge
code: MCM-05000
message: The 'mainImageLarge' attribute is required.
- provider_unique_identifier: shopSku2
status: LIVE
warnings:
- attribute_code: productTitle_fr
code: MCM-05000
message: The 'productTitle_fr' attribute is required.
application/json-auto:
summary: Complete example with value types (application/json)
value: string
schema:
type: array
format: binary
items:
$ref: '#/components/schemas/CM11_Response_200_Ext_FileStructure'
description: Export success
'204':
description: No source product data sheet status to export
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: CM11 - Export Source Product Data Sheet status
tags:
- Products
/api/hierarchies:
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Every hour</div>
<div class="max-call-frequency">Maximum usage: Every hour</div>
</div>'
operationId: H11
parameters:
- description: Catalog category code
explode: true
in: query
name: hierarchy
required: false
schema:
type: string
style: form
- description: Number of children catalog category levels to retrieve. If not specified, all child catalog categories are retrieved
explode: true
in: query
name: max_level
required: false
schema:
type: integer
format: int32
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
hierarchies:
- code: '5911111'
label: Suncare
label_translations:
- locale: en
value: Suncare
- locale: fr
value: Protection solaire
level: 2
parent_code: '59'
- code: '5911112'
label: Toiletries
label_translations:
- locale: en
value: Toiletries
- locale: fr
value: Articles de toilette
level: 2
parent_code: '59'
- code: '5911113'
label: Womens Hair Removal
label_translations:
- locale: en
value: Womens Hair Removal
- locale: fr
value: Épilation Femmes
level: 2
parent_code: '59'
application/json-auto:
summary: Complete example with value types (application/json)
value:
hierarchies:
- code: string
label: string
label_translations:
- locale: string
value: string
level: 0
parent_code: string
schema:
type: object
$ref: '#/components/schemas/H11_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: H11 - List Catalog categories (parents and children) related to a Catalog category
tags:
- Products
/api/products/imports:
post:
description: '<div class="extension-title">Description</div>
Returns the import identifier to track the status of the import
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Every hour, for each seller</div>
<div class="max-call-frequency">Maximum usage: Every 15 minutes, for each seller</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/mci/Operator/sync_pim.html">More context</a></li></ul></div>'
operationId: P41
parameters: []
requestBody:
content:
multipart/form-data:
examples:
multipart/form-data-auto:
summary: Complete example with value types (multipart/form-data)
value:
conversion_options:
ai_enrichment:
status: ENABLED
ai_rewrite:
status: ENABLED
ai_translation:
status: ENABLED
conversion_type: AI_CONVERTER
file: string
operator_format: true
shop: 0
schema:
type: object
properties:
conversion_options:
$ref: '#/components/schemas/P41_Request_MultipartFormData_ConversionOptions'
description: Options used for product file conversion when conversion_type is <code>AI_CONVERTER</code>
conversion_type:
type: string
description: 'Product file conversion type. If Catalog Transformer is enabled but the conversionType is not specified, then the default configuration from the shop settings will be used
Enum: `"AI_CONVERTER"`, `"STANDARD"`
'
file:
type: string
format: binary
description: Import file (CSV or XML or XLSX) to upload. Use <code>multipart/form-data</code> with name <code>file</code>
operator_format:
type: boolean
default: false
description: Force the use of the operator product format
shop:
type: integer
format: int64
description: Shop identifier
required:
- file
- shop
responses:
'201':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
import_id: 2035
application/json-auto:
summary: Complete example with value types (application/json)
value:
import_id: 0
schema:
type: object
$ref: '#/components/schemas/P41_Response_201'
description: Created
headers:
Location:
description: Pre-calculated URL to call to get the import status
explode: false
schema: {}
style: simple
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P41 - Import products to the operator information system
tags:
- Products
x-codeSamples:
- lang: cURL
source: "curl -i -X POST \\\n https://your-instance.mirakl.net/api/products/imports \\\n -H 'Content-Type: multipart/form-data' \\\n -F 'conversion_options=\"{\\\"ai_enrichment\\\":{\\\"status\\\":\\\"ENABLED\\\"},\\\"ai_rewrite\\\":{\\\"status\\\":\\\"ENABLED\\\"},\\\"ai_translation\\\":{\\\"status\\\":\\\"ENABLED\\\"}}\";type=application/json' \\\n -F 'conversion_type=\"\\\"AI_CONVERTER\\\"\";type=application/json' \\\n -F 'file=@path/to/file' \\\n -F 'operator_format=\"true\";type=application/json' \\\n -F 'shop=\"0\";type=application/json'\n"
get:
description: '<div class="extension-title">Description</div>
If the last_request_date param is not set the api returns all product imports.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Every 5 minutes</div>
<div class="max-call-frequency">Maximum usage: Once per minute</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/mci/Operator/sync_pim.html">More context</a></li></ul><div class="extension-title">Pagination</div>
<p>This resource supports offset pagination (<a href="#section/Offset-pagination-and-sort">see documentation</a>)</p>
<div class="extension-title">Sort fields</div>
<code>sort</code> field can have the following values:<ul><li><b>dateCreated</b> (Default) - Sort by creation date (asc by default)</li></ul>
</div>'
operationId: P51
parameters:
- description: Return only product imports that have changed since this date
explode: true
in: query
name: last_request_date
required: false
schema:
type: string
format: date-time
style: form
- description: Product import status. One of <code>CANCELLED</code>, <code>WAITING</code>, <code>RUNNING</code>, <code>SENT</code>, <code>COMPLETE</code>, <code>FAILED</code>
explode: true
in: query
name: status
required: false
schema:
type: string
style: form
- description: If <code>true</code> returns only product import trackings with transformed file
explode: true
in: query
name: has_transformed_file
required: false
schema:
type: boolean
style: form
- description: Shop identifier
explode: true
in: query
name: shop_id
required: false
schema:
type: integer
format: int64
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
product_import_trackings:
- date_created: '2019-04-05T13:13:06Z'
has_error_report: true
has_new_product_report: true
has_transformation_error_report: true
has_transformed_file: false
import_id: 2008
import_status: COMPLETE
shop_id: 2000
transform_lines_in_error: 5
transform_lines_in_success: 0
transform_lines_read: 5
transform_lines_with_warning: 0
- date_created: '2019-04-05T13:13:25Z'
has_error_report: false
has_new_product_report: false
has_transformation_error_report: false
has_transformed_file: true
import_id: 2009
import_status: SENT
shop_id: 2000
transform_lines_in_error: 0
transform_lines_in_success: 1
transform_lines_read: 1
transform_lines_with_warning: 0
total_count: 2
application/json-auto:
summary: Complete example with value types (application/json)
value:
product_import_trackings:
- conversion_options:
ai_enrichment:
status: ENABLED
ai_rewrite:
status: ENABLED
ai_translation:
status: ENABLED
conversion_type: AI_CONVERTER
date_created: '2023-03-28T09:34:42Z'
has_error_report: true
has_new_product_report: true
has_transformation_error_report: true
has_transformed_file: true
import_id: 0
import_status: TRANSFORMATION_WAITING
integration_details:
invalid_products: 0
products_not_accepted_in_time: 0
products_not_synchronized_in_time: 0
products_reimported: 0
products_successfully_synchronized: 0
products_with_synchronization_issues: 0
products_with_wrong_identifiers: 0
rejected_products: 0
reason_status: string
shop_id: 0
transform_lines_in_error: 0
transform_lines_in_success: 0
transform_lines_read: 0
transform_lines_with_warning: 0
total_count: 0
schema:
type: object
$ref: '#/components/schemas/P51_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P51 - Get information about product import statuses
tags:
- Products
/api/products/imports/{import}:
get:
description: '<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Once per minute until getting the import final status</div>
<div class="max-call-frequency">Maximum usage: Once per minute</div>
</div>'
operationId: P42
parameters:
- description: Import identifier
explode: false
in: path
name: import
required: true
schema:
type: integer
format: int64
style: simple
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
date_created: '2019-04-05T12:56:21Z'
has_error_report: false
has_new_product_report: false
has_transformation_error_report: false
has_transformed_file: true
import_id: 2005
import_status: SENT
shop_id: 2000
transform_lines_in_error: 0
transform_lines_in_success: 1
transform_lines_read: 1
transform_lines_with_warning: 0
application/json-auto:
summary: Complete example with value types (application/json)
value:
conversion_options:
ai_enrichment:
status: ENABLED
ai_rewrite:
status: ENABLED
ai_translation:
status: ENABLED
conversion_type: AI_CONVERTER
date_created: '2023-03-28T09:34:42Z'
has_error_report: true
has_new_product_report: true
has_transformation_error_report: true
has_transformed_file: true
import_id: 0
import_status: TRANSFORMATION_WAITING
integration_details:
invalid_products: 0
products_not_accepted_in_time: 0
products_not_synchronized_in_time: 0
products_reimported: 0
products_successfully_synchronized: 0
products_with_synchronization_issues: 0
products_with_wrong_identifiers: 0
rejected_products: 0
reason_status: string
shop_id: 0
transform_lines_in_error: 0
transform_lines_in_success: 0
transform_lines_read: 0
transform_lines_with_warning: 0
schema:
type: object
$ref: '#/components/schemas/P42_Response_200'
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P42 - Get the import status for a product import
tags:
- Products
/api/products/imports/{import}/error_report:
get:
description: '<div class="extension-title">Description</div>
This API returns either a CSV file (MCM enabled) or a file in a format defined by the operator (MCM disabled).
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Each time an error report is needed</div>
<div class="max-call-frequency">Maximum usage: Each time an error report is needed</div>
<div class="extension-title">Read More</div>
<ul><li><a href="https://help.mirakl.com/bundle/customers/page/topics/Mirakl/mci/Operator/catalog_integration_process_using_api.html">More context</a></li></ul></div>'
operationId: P44
parameters:
- description: Import identifier
explode: false
in: path
name: import
required: true
schema:
type: integer
format: int64
style: simple
responses:
'200':
content:
application/octet-stream:
examples:
application/octet-stream-auto:
summary: Complete example with value types (application/octet-stream)
value: string
schema:
type: string
format: binary
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P44 - Get the error report file for a product import ("Non-integrated products report")
tags:
- Products
/api/products/imports/{import}/new_product_report:
get:
description: '<div class="extension-title">Description</div>
This API returns either a CSV file (MCM enabled) or a file in a format defined by the operator (MCM disabled).
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Each time an integration report is needed</div>
<div class="max-call-frequency">Maximum usage: Each time an integration report is needed</div>
</div>'
operationId: P45
parameters:
- description: Import identifier
explode: false
in: path
name: import
required: true
schema:
type: integer
format: int64
style: simple
responses:
'200':
content:
application/octet-stream:
examples:
application/octet-stream-auto:
summary: Complete example with value types (application/octet-stream)
value: string
schema:
type: string
format: binary
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P45 - Get the product integration report file for a product import ("Added products report")
tags:
- Products
/api/products/imports/{import}/transformed_file:
get:
description: '<div class="extension-title">Description</div>
This API returns a CSV file.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Each time a transformed file is available</div>
<div class="max-call-frequency">Maximum usage: Each time a transformed file is available</div>
</div>'
operationId: P46
parameters:
- description: Import identifier
explode: false
in: path
name: import
required: true
schema:
type: integer
format: int64
style: simple
responses:
'200':
content:
text/csv:
examples:
text/csv-auto:
summary: Complete example with value types (text/csv)
value: string
schema:
type: string
format: binary
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P46 - Get the transformed file for a product import ("File in operator format")
tags:
- Products
/api/products/imports/{import}/transformation_error_report:
get:
description: '<div class="extension-title">Description</div>
This API returns a CSV, XLSX or XML file, depending on the file format provided by the seller.
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Each time an error report is needed</div>
<div class="max-call-frequency">Maximum usage: Each time an error report is needed</div>
</div>'
operationId: P47
parameters:
- description: Import identifier
explode: false
in: path
name: import
required: true
schema:
type: integer
format: int64
style: simple
responses:
'200':
content:
application/octet-stream:
examples:
application/octet-stream-auto:
summary: Complete example with value types (application/octet-stream)
value: string
schema:
type: string
format: binary
description: OK
security:
- Operator-Bearer-Token: []
- OAuth-2: []
summary: P47 - Get the transformation error report file for a product import ("Source file error report")
tags:
- Products
/api/products/attributes:
get:
description: '<div class="extension-title">Description</div>
Retrieves all attributes for parents and children of the requested hierarchy
<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>
<div class="recommended-call-frequency">Recommended usage: Every hour</div>
<div class="max-call-frequency">Maximum usage: Every hour</div>
</div>'
operationId: PM11
parameters:
- description: Code of the hierarchy (category) for which to retrieve the attributes. If not specified, all attributes are retrieved.
explode: true
in: query
name: hierarchy
required: false
schema:
type: string
style: form
- description: Number of children hierarchy (category) levels to retrieve. If not specified, attributes from all children hierarchies are retrieved.
explode: true
in: query
name: max_level
required: false
schema:
type: integer
format: int32
style: form
- description: List of channel codes
explode: true
in: query
name: channels
required: false
schema:
type: array
items:
type: string
uniqueItems: true
style: form
- description: Set to "<code>true</code>" to get only the attributes that have roles.
explode: true
in: query
name: with_roles
required: false
schema:
type: boolean
default: false
style: form
responses:
'200':
content:
application/json:
examples:
application/json-0:
summary: Example with business values (application/json)
value:
attributes:
- channels:
- code: WEBSITE_EN
code: washingInstructions3
default_value: null
description: How do you wash the product
description_translations:
- locale: en
value: How do you wash the product
example: null
hierarchy_code: '3012'
label: Washing Instructions
label_translations:
- locale: en
value: Washing Instructions
locale: en_US
requirement_level: OPTIONAL
roles: []
transformations: CAMEL_CASE
type: TEXT
type_parameter: null
validations: MIN_LENGTH|10
variant: false
- channels:
- code: WEBSITE_FR
- code: WEBSITE_EN
code: toolsIncluded3
default_value: null
description: Are tools included for the assembly of this product
description_translations:
- locale: en
value: Are tools included for the assembly of this product
example: null
hierarchy_code: '5610102'
label: Tools Included
label_translations:
- locale: en
value: Tools Included
requirement_level: OPTIONAL
roles: []
type: LIST
type_parameter: Boolean
variant: false
application/json-auto:
summary: Complete example with value types (application/json)
value:
attributes:
- channels:
- code: string
code: string
default_value: string
description: string
description_translations:
- locale: string
value: string
example: string
hierarchy_code: string
label: string
label_translations:
- locale: string
value: string
locale: string
required: true
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/mirakl-products-api-openapi.yml