The Mirakl Connect API — the seller-side network API behind Mirakl Connect, covering stores, channels, catalog, offers, orders and business requests across 24 paths. Bearer (JWT) authenticated against the Connect production endpoint.
components:
schemas:
AcceptOrderLine:
type: object
properties:
accepted:
type: boolean
description: Indicates if an order line is accepted (true) or refused (false).
examples:
- true
id:
type: string
description: >-
Unique order line identifier used by Mirakl Connect. This identifier
can be used as a primary key, but it must not be shared with final
users.
examples:
- 0002_3202630-A-2
required:
- accepted
- id
AcceptOrderLinesRequest:
properties:
order_lines:
type: array
description: Information about ordered products
items:
$ref: '#/components/schemas/AcceptOrderLine'
minItems: 1
required:
- order_lines
AcceptReturnRequest:
type: object
properties:
accepted:
type: boolean
description: Indicates if a return is accepted (true) or refused (false).
examples:
- true
rejection_reason:
type: string
description: >
Reason for rejecting the return
Enum: `"RETURN_WINDOW_CLOSED"`, `"NOT_ELIGIBLE_FOR_RETURN"`,
`"FINAL_SALES"`
required:
- accepted
ActionCreatedResponse:
type: object
properties:
action_id:
type: string
description: The unique identifier for the action.
examples:
- 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
required:
- action_id
ActionError:
type: object
properties:
code:
type: string
description: >
Enum: `"INVALID_INPUT"`, `"DATA_NOT_FOUND"`, `"UNEXPECTED"`,
`"UNAVAILABLE"`, `"TOO_MANY_REQUEST"`, `"ACTION_NOT_SUPPORTED"`,
`"ORDER_IN_WRONG_STATE"`, `"INVALID_PRODUCT_ID"`, `"OUT_OF_STOCK"`,
`"RETURN_IN_WRONG_STATE"`, `"OTHER"`
message:
type: string
description: Human-readable error message
maxLength: 2000
minLength: 1
required:
- code
- message
ActionErrorResponse:
type: object
properties:
code:
type: string
description: |-
Error code. One of this values :
- <code>INVALID_INPUT</code>
- <code>DATA_NOT_FOUND</code>
- <code>UNEXPECTED</code>
- <code>UNAVAILABLE</code>
- <code>TOO_MANY_REQUEST</code>
- <code>ACTION_NOT_SUPPORTED</code>
- <code>ORDER_IN_WRONG_STATE</code>
- <code>INVALID_PRODUCT_ID</code>
- <code>OUT_OF_STOCK</code>
- <code>RETURN_IN_WRONG_STATE</code>
- <code>ORDER_FULFILLED_BY_PARTNER</code>
- <code>PAYMENT_REQUIRED</code>
- <code>SYNCHRONIZATION_DEACTIVATED</code>
- <code>CARRIER_NOT_SUPPORTED</code>
- <code>MISSING_CARRIER</code>
- <code>WAREHOUSE_ID_NOT_FOUND</code>
- <code>WAREHOUSE_ID_REQUIRED</code>
- <code>OTHER</code>
examples:
- ORDER_IN_WRONG_STATE
message:
type: string
description: Original order error message from the Marketplace
examples:
- The order was not in the expected status.
required:
- code
- message
ActionItemRequest:
type: object
properties:
entity_id:
type: string
description: Unique entity identifier used by Mirakl Connect.
entity_type:
type: string
description: |
Enum: `"ORDER"`
errors:
type: array
description: >-
List of errors encountered during action execution. Should not be
null if the status is `FAILED`.
items:
$ref: '#/components/schemas/ActionError'
executed_at:
type: string
format: date-time
description: Date and time of the action in ISO 8601 format (UTC/Zulu time).
examples:
- '2025-06-30T16:46:00Z'
status:
type: string
description: |
Enum: `"FAILED"`, `"SUCCESS"`
type:
type: string
description: |
Enum: `"SYNCHRONIZE_ORDER"`, `"SYNCHRONIZE_ORDER_UPDATE"`
required:
- entity_id
- entity_type
- executed_at
- status
- type
ActionRequest:
type: object
properties:
actions:
type: array
description: List of actions to report
items:
$ref: '#/components/schemas/ActionItemRequest'
maxItems: 100
minItems: 1
required:
- actions
ActionResponse:
type: object
properties:
created_at:
type: string
format: date-time
description: Action creation date
examples:
- '2021-07-06T09:24:36.32Z'
errors:
type: array
description: List of errors that occurred during the action processing
items:
$ref: '#/components/schemas/ActionErrorResponse'
id:
type: string
description: >-
The unique identifier for the asynchronous action. This ID is
generated when the action is initially requested.
examples:
- 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
status:
type: string
description: |
Current action status
Enum: `"PENDING"`, `"SUCCESS"`, `"FAILED"`
examples:
- PENDING
updated_at:
type: string
format: date-time
description: Date of last modification of the action status
examples:
- '2021-07-06T09:24:36.32Z'
required:
- created_at
- id
- status
- updated_at
ActionsCreatedResponse:
type: object
properties:
actions:
type: array
description: List of created actions ids
items:
$ref: '#/components/schemas/ActionCreatedResponse'
required:
- actions
Address:
type: object
properties:
additional_info:
type: string
description: Additional information related to the address
city:
type: string
description: City
company:
type: string
description: Company of the person associated with the address
country:
type: string
description: Country
country_iso_code:
type: string
format: iso-3166-1 alpha-3
description: Country ISO code
first_name:
type: string
description: First name of the person associated with the address
last_name:
type: string
description: Last name of the person associated with the address
phone:
type: string
description: Phone number of the person associated with the address
state:
type: string
description: State
street:
type: string
description: Street information
street_additional_info:
type: string
description: Additional street information
zip_code:
type: string
description: Postal code
required:
- city
- last_name
- street
Adjustment:
type: object
properties:
adjustment_id:
type: string
description: Unique adjustment identifier used by Mirakl Connect.
examples:
- 0002_3202630_R
created_at:
type: string
format: date-time
description: Adjustment date
id:
type: string
deprecated: true
description: >-
Unique identifier by adjustment type. Deprecated, use adjustment_id
instead.
examples:
- 0002_3202630
price:
$ref: '#/components/schemas/Money'
description: >-
Product unit price multiplied by the quantity adjusted, excluding
taxes and shipping price.
quantity:
type: integer
description: Product quantity adjusted.
examples:
- '10'
reason:
type: string
description: >
The reason why the order line is adjusted.
Enum: `"CUSTOMER_CANCELATION"`, `"OUT_OF_STOCK"`, `"RETURN"`,
`"ITEM_NOT_RECEIVED"`, `"AGREEMENT"`, `"DEFECT"`,
`"UNABLE_TO_DELIVER"`, `"CHANNEL_SPECIFIC"`
shipping_price:
$ref: '#/components/schemas/Money'
description: Shipping price of the adjusted order line, excluding shipping taxes.
shipping_taxes:
type: array
description: Shipping taxes adjusted
items:
$ref: '#/components/schemas/TaxAdjustment'
taxes:
type: array
description: Taxes adjusted
items:
$ref: '#/components/schemas/TaxAdjustment'
type:
type: string
description: |
The type of adjustment.
Enum: `"REFUND"`, `"CANCELATION"`
required:
- adjustment_id
- created_at
- id
- price
- quantity
- reason
- shipping_price
- type
AsynchronousActionResponse:
type: object
properties:
action_id:
type: string
description: >
The unique identifier for the asynchronous action. It should be used
with the [v2-getActionStatus API](#operation/v2-getActionStatus) to
retrieve current action status and potential errors.
examples:
- 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
tracking_id:
type: string
deprecated: true
description: >
**Deprecated:** This field was previously used to obtain the action
ID. It has been replaced by `action_id` and contains the same value.
It is retained for backward compatibility.
examples:
- 1ba5fc4b-c4fd-4251-880b-3052e301bbd4
required:
- action_id
Attribute:
type: object
description: An attribute of this product.
discriminator:
mapping:
BOOLEAN: '#/components/schemas/AttributeBoolean'
NUMERIC: '#/components/schemas/AttributeNumeric'
STRING: '#/components/schemas/AttributeString'
propertyName: type
properties:
id:
type: string
description: Attribute's id
maxLength: 255
minLength: 1
name:
type: string
description: Attribute's name
maxLength: 255
minLength: 1
type:
type: string
description: |
The attribute's type
Enum: `"STRING"`, `"NUMERIC"`, `"BOOLEAN"`
examples:
- STRING
value:
type: object
description: The attribute's value
required:
- id
- name
- type
- value
AttributeBoolean:
allOf:
- $ref: '#/components/schemas/Attribute'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- limitedEdition
maxLength: 255
minLength: 1
name:
type: string
description: Attribute's name
examples:
- Limited edition
maxLength: 255
minLength: 1
value:
type: boolean
description: Attribute's boolean value
examples:
- true
AttributeNumeric:
allOf:
- $ref: '#/components/schemas/Attribute'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- weight
maxLength: 255
minLength: 1
name:
type: string
description: Attribute's name
examples:
- Weight in Kg
maxLength: 255
minLength: 1
value:
type: number
format: with decimals
description: Attribute's numeric value
examples:
- 1234.56
maximum: 1000000000
minimum: -1000000000
AttributeString:
allOf:
- $ref: '#/components/schemas/Attribute'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- color
maxLength: 255
minLength: 1
name:
type: string
description: Attribute's name
examples:
- color
maxLength: 255
minLength: 1
value:
type: string
description: Attribute's string value
examples:
- Red
maxLength: 2000
Attributes:
type:
- array
- 'null'
description: Additional product attributes
items:
$ref: '#/components/schemas/Attribute'
maxItems: 1000
minItems: 0
AvailableQuantity:
type: integer
format: int32
description: Available quantity of a product
maximum: 1000000000
minimum: 0
BillingInfo:
type: object
properties:
address:
$ref: '#/components/schemas/Address'
description: Customer billing address
Brand:
type:
- string
- 'null'
description: Brand
examples:
- My awesome brand
maxLength: 255
CancelOrderLinesRequest:
type: object
properties:
cancelations:
type: array
description: Cancelations details related to an order
items:
$ref: '#/components/schemas/CancelRequest'
minItems: 1
required:
- cancelations
CancelRequest:
type: object
properties:
order_line_id:
type: string
description: >-
Unique order line identifier used by Mirakl Connect. ID of the order
line to cancel.
examples:
- 0002_3202630-A-2
minLength: 1
price:
allOf:
- $ref: '#/components/schemas/Money'
description: Product price to cancel, excluding taxes and shipping price
product_id:
type: string
description: Seller product identifier on the channel
examples:
- SELLER_ID_1
minLength: 1
quantity:
type: integer
description: Product quantity to cancel
examples:
- 10
minimum: 0
reason:
type: string
description: >
The reason why the order line is canceled
Enum: `"CUSTOMER_CANCELATION"`, `"OUT_OF_STOCK"`, `"RETURN"`,
`"ITEM_NOT_RECEIVED"`, `"AGREEMENT"`, `"DEFECT"`,
`"UNABLE_TO_DELIVER"`
shipping_price:
allOf:
- $ref: '#/components/schemas/Money'
description: Shipping price to cancel, excluding shipping taxes
shipping_taxes:
type: array
description: Shipping taxes to cancel
items:
$ref: '#/components/schemas/CanceledTaxRequest'
taxes:
type: array
description: Taxes to cancel
items:
$ref: '#/components/schemas/CanceledTaxRequest'
required:
- price
- quantity
- reason
- shipping_price
CanceledTaxRequest:
type: object
properties:
amount:
allOf:
- $ref: '#/components/schemas/Money'
description: Canceled tax amount
code:
type: string
description: Tax code on the sales channel
minLength: 1
required:
- amount
- code
Category:
type: object
description: Category
properties:
id:
type:
- string
- 'null'
description: The id of the category
examples:
- '123654789'
maxLength: 255
minLength: 1
labels:
type: array
description: Labels for the category with their associated locale
items:
$ref: '#/components/schemas/CategoryLabel'
required:
- labels
CategoryLabel:
type: object
description: A label for the category with its associated locale
properties:
locale:
$ref: '#/components/schemas/Locale'
value:
type: string
description: A label for the category
examples:
- Fridge
maxLength: 255
required:
- locale
- value
ConversationActionErrorItem:
type: object
properties:
code:
type: string
description: |
One of the following :
- INVALID_INPUT
- DATA_NOT_FOUND
- UNEXPECTED
- UNAVAILABLE
- TOO_MANY_REQUEST
example: DATA_NOT_FOUND
message:
type: string
description: Human-readable error message
example: Conversation not found for the given ID.
required:
- code
- message
ConversationActionIdResponse:
type: object
properties:
action_id:
type: string
description: >-
Unique identifier of the action. Use `getConversationActionStatus`
to retrieve the result of your request.
example: abcd
required:
- action_id
ConversationActionStatus:
type: string
description: |
Status of an asynchronous conversation action
Enum: `"PENDING"`, `"SUCCESS"`, `"ERROR"`
ConversationActionStatusResponse:
type: object
properties:
conversation_id:
type: string
description: Identifier of the related conversation.
created_at:
type: string
format: date-time
description: Date and time when the action was created
errors:
type: array
description: List of errors if the action failed
items:
$ref: '#/components/schemas/ConversationActionErrorItem'
id:
type: string
description: Unique identifier of the action
example: abcd
status:
$ref: '#/components/schemas/ConversationActionStatus'
description: Current status of the action
updated_at:
type: string
format: date-time
description: Date and time when the action was last updated
required:
- created_at
- id
- status
- updated_at
ConversationMessagesResponse:
type: object
properties:
messages:
type: array
description: List of messages in the conversation
items:
$ref: '#/components/schemas/MessageResponse'
required:
- messages
ConversationOrigin:
type: object
properties:
channel_id:
type: string
description: Unique identifier of the sales channel
channel_name:
type: string
description: Name of the sales channel
channel_store_id:
type: string
description: >-
Store identifier on the sales channel. This identifier is not
guaranteed to be unique as multiple channels can use the same
identifier.
channel_store_name:
type: string
description: Store public name on the sales channel
required:
- channel_id
- channel_name
- channel_store_id
- channel_store_name
ConversationParticipant:
type: object
properties:
id:
type: string
description: Unique identifier of the participant. Null for type `CUSTOMER`.
example: '123456'
name:
type: string
description: Display name of the participant
example: Marketplace 1
type:
type: string
description: |
Type of the participant
Enum: `"CHANNEL"`, `"CUSTOMER"`
example: CHANNEL
required:
- name
- type
ConversationResponse:
type: object
properties:
anonymized_at:
type: string
format: date-time
description: >-
Date and time when the conversation was anonymized. Absent if the
conversation has not been anonymized.
example: '2024-01-02T13:00:00.000Z'
channel_conversation_id:
type: string
description: Unique identifier of the conversation on the channel
created_at:
type: string
format: date-time
description: Date and time when the conversation was created
example: '2024-01-02T12:13:14.567Z'
entity:
type: object
description: Entity linked to the conversation
properties:
channel_entity_id:
type: string
description: Unique identifier of the entity on the channel
example: MIR-F745HNL8-A
id:
type: string
description: >-
Connect identifier of the entity. Null if the entity is not yet
known to Connect.
example: 0054_MIR-F745HNL8-A
type:
type: string
description: |
Type of the entity
Enum: `"ORDER"`
required:
- channel_entity_id
- type
id:
type: string
description: Unique identifier of the conversation
origin:
$ref: '#/components/schemas/ConversationOrigin'
description: Sales channel information
participants:
type: array
description: List of participants in the conversation
items:
$ref: '#/components/schemas/ConversationParticipant'
topic:
type: object
description: Topic of the conversation
properties:
type:
type: string
description: |
Type of the topic
Enum: `"FREE_TEXT"`
value:
type: string
description: Value of the topic
example: Hello, I have a question about my order
maxLength: 500
required:
- type
- value
updated_at:
type: string
format: date-time
description: >-
Date and time when the conversation was last updated. This is
updated when a new message is received in the conversation.
example: '2024-01-02T12:42:00.667Z'
required:
- channel_conversation_id
- created_at
- entity
- id
- origin
- participants
- topic
- updated_at
ConversationsPageResponse:
allOf:
- $ref: '#/components/schemas/ResourcesPage'
- type: object
properties:
data:
type: array
description: Page of conversations corresponding to the filter parameters
items:
$ref: '#/components/schemas/ConversationResponse'
required:
- data
CreateConversationInput:
type: object
properties:
entity:
type: object
description: Entity to link to the conversation
properties:
id:
type: string
description: Unique identifier of the entity (e.g. order ID)
example: 0123_Order1-A
type:
type: string
description: |
Type of the entity linked to the conversation
Enum: `"ORDER"`
required:
- id
- type
first_message:
type: object
description: First message of the conversation
properties:
body:
type: string
description: Body of the first message
example: Hello! How can I assist you today?
maxLength: 2000
minLength: 1
required:
- body
topic:
$ref: '#/components/schemas/CreateConversationInputTopic'
description: Topic of the conversation
required:
- entity
- first_message
- topic
CreateConversationInputTopic:
type: object
properties:
type:
type: string
description: |
Type of the topic
Enum: `"FREE_TEXT"`
value:
type: string
description: Value of the topic
example: Customer has a general question about services.
maxLength: 500
required:
- type
- value
CreateShipmentItemRequest:
type: object
properties:
id:
type: string
description: Seller product identifier
examples:
- SELLER_ID_1
minLength: 1
order_line_id:
type: string
description: Order line identifier
examples:
- 0024_COMMERCIAL_ID-A-1
minLength: 1
quantity:
type: integer
description: Product quantity to ship
examples:
- '10'
minimum: 1
required:
- quantity
CreateShipmentRequest:
type: object
description: Shipment object and its items' details
properties:
carrier:
type: string
description: |-
Carrier company name. For example:
- <code>UPS</code>
- <code>DHL Express</code>
- <code>Amazon Logistics UK</code>
- <code>FedEx</code>
- <code>China Post</code>
- ...
examples:
- DHL Express
minLength: 1
items:
type: array
description: Shipment items
items:
$ref: '#/components/schemas/CreateShipmentItemRequest'
return_tracking_number:
type: string
description: >-
Return shipment tracking number is required only for marketplaces
that expect return tracking information when the shipment is
created. If the marketplace doesn’t require it to create the
shipment, the value won’t be synchronized.
examples:
- '78910'
minLength: 1
tracking_number:
type: string
description: Carrier tracking number
examples:
- '123456'
minLength: 1
tracking_url:
type: string
description: Carrier tracking URL
examples:
- https://wwwapps.ups.com/WebTracking/track
required:
- items
CustomAttributeBooleanResponse:
allOf:
- $ref: '#/components/schemas/CustomAttributeResponse'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- is-premium
maxLength: 255
minLength: 1
value:
type: boolean
description: Attribute's boolean value
examples:
- true
CustomAttributeDateResponse:
allOf:
- $ref: '#/components/schemas/CustomAttributeResponse'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- delivery-date
maxLength: 255
minLength: 1
value:
type: string
format: date-time
description: Attribute's date value
examples:
- '2024-01-27T09:24:36.326Z'
CustomAttributeListResponse:
allOf:
- $ref: '#/components/schemas/CustomAttributeResponse'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- available-sizes
maxLength: 255
minLength: 1
value:
type: array
description: Additional attribute values
items:
type: string
maxLength: 10000
maxItems: 1000
minItems: 1
CustomAttributeNumericResponse:
allOf:
- $ref: '#/components/schemas/CustomAttributeResponse'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- weight
maxLength: 255
minLength: 1
value:
type: number
format: with decimals
description: Attribute's numeric value
examples:
- '1234.56'
maximum: 1000000000
minimum: -1000000000
CustomAttributeResponse:
type: object
description: A custom attribute.
discriminator:
mapping:
BOOLEAN: '#/components/schemas/CustomAttributeBooleanResponse'
DATE: '#/components/schemas/CustomAttributeDateResponse'
LIST: '#/components/schemas/CustomAttributeListResponse'
NUMERIC: '#/components/schemas/CustomAttributeNumericResponse'
STRING: '#/components/schemas/CustomAttributeStringResponse'
propertyName: type
properties:
id:
type: string
description: Attribute's id
maxLength: 255
minLength: 1
type:
type: string
description: |
The attribute's type
Enum: `"STRING"`, `"NUMERIC"`, `"BOOLEAN"`, `"DATE"`, `"LIST"`
examples:
- STRING
value:
type: object
required:
- id
- type
- value
CustomAttributeStringResponse:
allOf:
- $ref: '#/components/schemas/CustomAttributeResponse'
- type: object
properties:
id:
type: string
description: Attribute's id
examples:
- color
maxLength: 255
minLength: 1
value:
type: string
description: Attribute's string value
examples:
- red
maxLength: 10000
CustomAttributesResponse:
type: array
description: Custom attributes
items:
$ref: '#/components/schemas/CustomAttributeResponse'
DeleteProductsRequest:
type: object
description: |
Delete any of corresponding products.
Unknown or no longer present products won't generate error.
properties:
products:
type: array
description: Identifier of products to delete
items:
$ref: '#/components/schemas/ProductIdentifier'
maxItems: 1000
minItems: 1
required:
- products
Description:
type: object
description: Description with its associated locale
properties:
locale:
$ref: '#/components/schemas/Locale'
value:
type: string
description: Description
examples:
- My awesome product's description
maxLength: 6000
required:
- locale
- value
Descriptions:
type:
- array
- 'null'
description: Descriptions with their associated locale
items:
$ref: '#/components/schemas/Description'
maxItems
# --- truncated at 32 KB (239 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/_original/mirakl-connect-openapi.yaml