The Connect Channel Platform API used by channel partners integrating a sales channel with Mirakl Connect — store business information, channel catalog configuration, taxonomy upserts, product feedback and order upserts (12 paths), paired with the push webhook catalog.
{
"components": {
"parameters": {
"channel_id_path": {
"description": "Connect Channel identifier",
"explode": false,
"in": "path",
"name": "channel_id",
"required": true,
"schema": {
"type": "string",
"examples": [
"1234"
],
"minLength": 1
},
"style": "simple"
},
"store_id_path": {
"deprecated": true,
"description": "Store identifier in the channel",
"explode": false,
"in": "path",
"name": "store_id",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"style": "simple"
}
},
"schemas": {
"ActionError": {
"type": "object",
"description": "Detailed information about an error encountered during action processing",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code identifying the type of failure.\n\n\nEnum: `\"INVALID_INPUT\"`, `\"DATA_NOT_FOUND\"`, `\"UNEXPECTED\"`, `\"UNAVAILABLE\"`, `\"TOO_MANY_REQUEST\"`, `\"ACTION_NOT_SUPPORTED\"`, `\"ORDER_IN_WRONG_STATE\"`, `\"RETURN_IN_WRONG_STATE\"`, `\"CARRIER_NOT_SUPPORTED\"`, `\"MISSING_CARRIER\"`, `\"WAREHOUSE_ID_NOT_FOUND\"`, `\"WAREHOUSE_ID_REQUIRED\"`, `\"OTHER\"`\n"
},
"message": {
"type": "string",
"description": "Human-readable description of the error.\n",
"examples": [
"Cannot process cancellation: order is already shipped"
]
}
},
"required": [
"code",
"message"
]
},
"AddressRequest": {
"type": "object",
"properties": {
"additional_info": {
"type": "string",
"description": "Additional delivery instructions or notes."
},
"city": {
"type": "string",
"description": "City."
},
"company": {
"type": "string",
"description": "Company name, if applicable."
},
"country": {
"type": "string",
"description": "Country name."
},
"country_iso_code": {
"type": "string",
"description": "ISO 3166-1 alpha-3 country code (e.g. FRA, USA, DEU)."
},
"first_name": {
"type": "string",
"description": "Recipient's first name."
},
"last_name": {
"type": "string",
"description": "Recipient's last name."
},
"phone": {
"type": "string",
"description": "Phone number of the recipient."
},
"state": {
"type": "string",
"description": "State or region."
},
"street": {
"type": "string",
"description": "Street name and number."
},
"street_additional_info": {
"type": "string",
"description": "Additional street information (apartment, floor, building, etc.)."
},
"zip_code": {
"type": "string",
"description": "Postal or ZIP code."
}
},
"required": [
"city",
"last_name",
"street"
]
},
"AdjustmentRequest": {
"type": "object",
"properties": {
"channel_adjustment_id": {
"type": "string",
"description": "Unique identifier of the adjustment on the channel."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Date and time when the adjustment was created on the channel."
},
"price": {
"$ref": "#/components/schemas/Money",
"description": "Refunded or cancelled amount, **tax excluded**. Taxes on the adjusted product amount are listed separately in `taxes`."
},
"quantity": {
"type": "integer",
"description": "Number of units affected by this adjustment. For a `CANCELATION`, this is the number of units cancelled. For a `REFUND`, this is the number of units for which the refund applies."
},
"reason": {
"type": "string",
"description": "Business reason for the adjustment.\n\nEnum: `\"CUSTOMER_CANCELATION\"`, `\"OUT_OF_STOCK\"`, `\"RETURN\"`, `\"ITEM_NOT_RECEIVED\"`, `\"AGREEMENT\"`, `\"DEFECT\"`, `\"UNABLE_TO_DELIVER\"`, `\"CHANNEL_SPECIFIC\"`\n"
},
"shipping_price": {
"$ref": "#/components/schemas/Money",
"description": "Refunded or cancelled shipping amount, **tax excluded**. Shipping taxes are listed separately in `shipping_taxes`."
},
"shipping_taxes": {
"type": "array",
"description": "Taxes on the adjusted shipping amount. These amounts are **not** included in `shipping_price`.",
"items": {
"$ref": "#/components/schemas/TaxRequest"
}
},
"taxes": {
"type": "array",
"description": "Refunded or cancelled taxes. These amounts should **not** be included in `price`.",
"items": {
"$ref": "#/components/schemas/TaxRequest"
}
},
"type": {
"type": "string",
"description": "Nature of the adjustment.\n\n`CANCELATION` means units were removed from the line (quantity reduction); connect will release the corresponding stock reservation.\n\n`REFUND` means a monetary compensation was issued without changing the ordered quantity.\n\n\nEnum: `\"REFUND\"`, `\"CANCELATION\"`\n"
}
},
"required": [
"channel_adjustment_id",
"created_at",
"price",
"quantity",
"reason",
"shipping_price",
"type"
]
},
"Attribute": {
"type": "object",
"discriminator": {
"mapping": {
"Boolean": "#/components/schemas/BooleanAttribute",
"List": "#/components/schemas/ListAttribute",
"Numeric": "#/components/schemas/NumericAttribute",
"Text": "#/components/schemas/TextAttribute"
},
"propertyName": "type"
},
"properties": {
"configuration_modes": {
"type": "array",
"description": "List of accepted configuration modes for providing the value",
"items": {
"$ref": "#/components/schemas/ConfigurationMode"
},
"minItems": 1
},
"descriptions": {
"type": "array",
"description": "Additional attribute descriptions",
"items": {
"$ref": "#/components/schemas/Localized"
}
},
"id": {
"type": "string",
"description": "Id of the attribute",
"minLength": 1
},
"labels": {
"type": "array",
"description": "Labels of the attribute",
"items": {
"$ref": "#/components/schemas/Localized"
},
"minItems": 1
},
"requirement_level": {
"type": "string",
"description": "Requirement level of the attribute\n\nEnum: `\"OPTIONAL\"`, `\"RECOMMENDED\"`, `\"REQUIRED\"`\n"
},
"type": {
"$ref": "#/components/schemas/AttributeType"
}
},
"required": [
"configuration_modes",
"id",
"labels",
"requirement_level",
"type"
]
},
"AttributeContext": {
"type": "object",
"description": "Additional context information about where this attribute label is located within \nthe marketplace's data structure. This helps with catalog transformation.\n",
"properties": {
"labels": {
"type": "array",
"description": "List of labels context for the attribute",
"items": {
"$ref": "#/components/schemas/Localized"
}
},
"path": {
"type": "string",
"description": "The path indicating where this attribute label is located in the marketplace's data structure.\nUsed for data mapping and transformation purposes.\n"
}
}
},
"AttributeType": {
"type": "string",
"description": "Enum: `\"Boolean\"`, `\"Numeric\"`, `\"Text\"`, `\"List\"`\n"
},
"BillingInfoRequest": {
"type": "object",
"description": "Billing information for invoice and payment purposes. Optional.",
"properties": {
"address": {
"$ref": "#/components/schemas/AddressRequest",
"description": "Billing address used for invoice and payment purposes."
}
}
},
"BooleanAttribute": {
"allOf": [
{
"$ref": "#/components/schemas/Attribute"
},
{
"type": "object",
"properties": {
"default_value": {
"type": "boolean",
"description": "Default boolean value of the attribute, used for required attributes only"
}
}
}
]
},
"BusinessInformationInput": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Currency tag, expected in ISO 4217 format. Cannot be changed later.",
"example": "USD",
"maxLength": 3,
"minLength": 1,
"pattern": "^[A-Z]{3}$"
},
"kyc_status": {
"type": "string",
"description": "KYC (Know Your Customer) status of the configuration.\nIf KYC is not required, the status will be set to NOT_REQUIRED.\n\n\nEnum: `\"PENDING_SUBMISSION\"`, `\"PENDING_APPROVAL\"`, `\"REFUSED\"`, `\"APPROVED\"`, `\"NOT_REQUIRED\"`\n"
},
"kyc_status_reason": {
"type": "string",
"description": "Reason of a problem with the KYC configuration.\nThis information can be displayed to the seller if needed in Mirakl Connect\n"
},
"missing_configuration": {
"type": "boolean",
"description": "Indicates if the store is missing configuration to be properly functioning.\nThis can be either required information not filled or documents not sent.\nFalse indicates that there is no missing configuration for the store.\nTrue will raise a warning to the seller stating that they need to configure their store.\n"
},
"payment_information_configured": {
"type": "boolean",
"description": "Indicates if a payment method is configured for the store.\n"
},
"payment_information_warning": {
"type": "string",
"description": "Reason of a problem with the payment configuration.\nA null value indicates no problems encountered, payment configuration is valid.\nAny content will raise a warning in Mirakl Connect for the seller stating that there might be a problem \nwith how their payment method is configured in the Marketplace where their store is located.\n"
},
"quality_suspension_reasons": {
"type": "array",
"description": "List of reasons for the suspension of the store related to quality standard defined by the Marketplace.\nA null or empty value indicates no problems encountered, store is not suspended.\nAny content will raise a warning in Mirakl Connect for the seller stating that there might be \nquality issues with their store.\n",
"items": {
"$ref": "#/components/schemas/QualitySuspensionReason"
}
},
"shipping_warning": {
"type": "string",
"description": "Reason of a problem with the shipping configuration.\nA null value indicates no problems encountered, shipping configuration is valid.\n"
},
"sub_channels": {
"type": "array",
"description": "List of sales channels inside the Marketplace where the store is located.\nThis is useful for marketplaces where sellers have a global product catalog with multiple sales channels.\nOne store can be provided per seller with as many sub channels as the sales channels the store operates in.\nBy doing so, the store will receive offers, prices and stock updates per sub channel. Product events will come once for the store.\n\nSub channels are a critical part, it can impact the business of a seller. \nBy deleting one the seller participates in, all offers synchronization will stop for the marketplace sales channel it relates to. Orders should also not be sent anymore to Connect.\n\nBehavior for the sub channel field:\n- Can be null if it was never filled before.\n- Can be an empty array if it was never filled before.\n- Cannot be emptied if there was at least one item before.\nHow to:\n- Add a new sub channel: add it to the list.\n- Update an existing sub channel: update the item in the list with the same id.\n- Delete an existing sub channel: remove it from the list.\n",
"items": {
"$ref": "#/components/schemas/SubChannel"
}
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Date of the last update of the store information.\nOlder event for a store will not be saved.\n"
}
},
"required": [
"currency",
"updated_at"
]
},
"CarrierRequest": {
"type": "object",
"properties": {
"channel_carrier_id": {
"type": "string",
"description": "Unique identifier of the carrier on the channel"
},
"name": {
"type": "string",
"description": "Display name of the carrier"
}
},
"required": [
"channel_carrier_id",
"name"
]
},
"ChannelCatalogCapabilities": {
"type": "object",
"properties": {
"offer_configuration": {
"$ref": "#/components/schemas/OfferConfiguration"
},
"use_case_configurations": {
"$ref": "#/components/schemas/UseCaseConfigurations"
}
}
},
"ConfigurationMode": {
"type": "string",
"description": "The user can configure an attribute via:\n- `CONSTANT`: a constant value for all the catalog\n- `VARIABLE`: a value that can be different for each item, based on an attribute\n\n\nEnum: `\"CONSTANT\"`, `\"VARIABLE\"`\n"
},
"ConnectStandardAttribute": {
"type": "string",
"description": "Equivalent of the attribute in Connect standard taxonomy\n\nEnum: `\"PRODUCT_ID\"`, `\"CATEGORY\"`, `\"BRAND\"`, `\"TITLE\"`, `\"DESCRIPTION\"`, `\"IMAGE\"`, `\"GTIN\"`, `\"VARIANT_GROUP_CODE\"`\n"
},
"CustomAttributeBooleanRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CustomAttributeRequest"
},
{
"type": "object",
"properties": {
"value": {
"type": "boolean",
"description": "Attribute's boolean value",
"examples": [
"true"
]
}
}
}
],
"required": [
"id",
"type",
"value"
]
},
"CustomAttributeDateRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CustomAttributeRequest"
},
{
"type": "object",
"properties": {
"value": {
"type": "string",
"format": "date-time",
"description": "Attribute's date value",
"examples": [
"2024-01-27T09:24:36.326Z"
]
}
}
}
],
"required": [
"id",
"type",
"value"
]
},
"CustomAttributeListRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CustomAttributeRequest"
},
{
"type": "object",
"properties": {
"value": {
"type": "array",
"description": "Additional attribute values",
"items": {
"type": "string",
"maxLength": 10000
},
"maxItems": 1000,
"minItems": 1
}
}
}
],
"required": [
"id",
"type",
"value"
]
},
"CustomAttributeNumericRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CustomAttributeRequest"
},
{
"type": "object",
"properties": {
"value": {
"type": "number",
"format": "with decimals",
"description": "Attribute's numeric value",
"examples": [
"1234.56"
],
"maximum": 1000000000,
"minimum": -1000000000
}
}
}
],
"required": [
"id",
"type",
"value"
]
},
"CustomAttributeRequest": {
"type": "object",
"description": "A custom attribute.",
"discriminator": {
"mapping": {
"BOOLEAN": "#/components/schemas/CustomAttributeBooleanRequest",
"DATE": "#/components/schemas/CustomAttributeDateRequest",
"LIST": "#/components/schemas/CustomAttributeListRequest",
"NUMERIC": "#/components/schemas/CustomAttributeNumericRequest",
"STRING": "#/components/schemas/CustomAttributeStringRequest"
},
"propertyName": "type"
},
"properties": {
"id": {
"type": "string",
"description": "Attribute's id",
"maxLength": 255,
"minLength": 1
},
"type": {
"type": "string",
"description": "The attribute's type\n\nEnum: `\"STRING\"`, `\"NUMERIC\"`, `\"BOOLEAN\"`, `\"DATE\"`, `\"LIST\"`\n"
}
},
"required": [
"id",
"type"
]
},
"CustomAttributeStringRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CustomAttributeRequest"
},
{
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "Attribute's string value",
"examples": [
"red"
],
"maxLength": 100000
}
}
}
],
"required": [
"id",
"type",
"value"
]
},
"CustomAttributesRequest": {
"type": "array",
"description": "Custom attributes",
"items": {
"$ref": "#/components/schemas/CustomAttributeRequest"
},
"maxItems": 1000,
"minItems": 0
},
"Diagnostic": {
"type": "object",
"description": "Represents a diagnostic message related to a catalog item.",
"properties": {
"channel_attribute_id": {
"type": [
"string",
"null"
],
"description": "The identifier of the channel attribute related to the diagnostic."
},
"channel_diagnostic_id": {
"type": [
"string",
"null"
],
"description": "The diagnostic identifier in the channel."
},
"connector_override_action": {
"type": [
"string",
"null"
],
"deprecated": true,
"description": "Enum: `\"REMOVED\"`, `null`\n"
},
"message": {
"type": "string",
"description": "The diagnostic message."
}
},
"required": [
"message"
]
},
"DiscountPricePeriod": {
"type": "object",
"description": "Configuration for discount price period.",
"properties": {
"end_date": {
"$ref": "#/components/schemas/PricingConfigurationField"
},
"start_date": {
"$ref": "#/components/schemas/PricingConfigurationField"
},
"support": {
"type": "string",
"description": "Support for the discount price period\n\nEnum: `\"SUPPORTED\"`, `\"UNSUPPORTED\"`\n"
}
},
"required": [
"end_date",
"start_date",
"support"
]
},
"DocumentOriginRequest": {
"type": "object",
"properties": {
"channel_id": {
"type": "string",
"description": "Unique identifier of the sales channel"
},
"channel_store_id": {
"type": "string",
"description": "Store identifier on the sales channel."
},
"sub_channel_code": {
"type": "string",
"description": "Code of the sub-channel on which the document was uploaded."
}
},
"required": [
"channel_id",
"channel_store_id"
]
},
"EmbeddedAttribute": {
"type": "object",
"discriminator": {
"mapping": {
"Decimal": "#/components/schemas/EmbeddedDecimalAttribute",
"Integer": "#/components/schemas/EmbeddedIntegerAttribute",
"List": "#/components/schemas/EmbeddedListAttribute",
"Media": "#/components/schemas/EmbeddedMediaAttribute",
"Text": "#/components/schemas/EmbeddedTextAttribute"
},
"propertyName": "type"
},
"properties": {
"connect_standard_attributes": {
"type": "array",
"description": "Map one attribute per standard type (e.g., your main image attribute to IMAGE). \nFor multi-lingual catalogs, multiple locale-specific attributes may map to TITLE and DESCRIPTION.\n",
"items": {
"$ref": "#/components/schemas/ConnectStandardAttribute"
}
},
"context": {
"$ref": "#/components/schemas/AttributeContext"
},
"descriptions": {
"type": "array",
"description": "Additional attribute descriptions with their associated locale",
"items": {
"$ref": "#/components/schemas/Localized"
}
},
"id": {
"$ref": "#/components/schemas/ProductAttributeId"
},
"labels": {
"type": "array",
"description": "Labels for the attribute with their associated locale",
"items": {
"$ref": "#/components/schemas/Localized"
},
"minItems": 1
},
"requirement_level": {
"$ref": "#/components/schemas/RequirementLevel"
},
"type": {
"$ref": "#/components/schemas/ProductAttributeType"
}
},
"required": [
"descriptions",
"id",
"labels",
"requirement_level",
"type"
]
},
"EmbeddedDecimalAttribute": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EmbeddedAttribute"
}
],
"examples": [
"42.3"
],
"properties": {
"maximum": {
"type": "number",
"format": "double",
"description": "The maximum allowed value (inclusive)",
"example": 1000000
},
"minimum": {
"type": "number",
"format": "double",
"description": "The minimum number allowed (inclusive)",
"example": 0
},
"scale": {
"type": "integer",
"description": "Number of decimal places",
"minimum": 0
}
},
"required": [
"scale"
]
},
"EmbeddedIntegerAttribute": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EmbeddedAttribute"
}
],
"examples": [
"42"
],
"properties": {
"maximum": {
"type": "integer",
"format": "int64",
"description": "The maximum Number allowed",
"example": 9999
},
"minimum": {
"type": "integer",
"format": "int64",
"description": "The minimum number allowed",
"example": -9999
}
}
},
"EmbeddedListAttribute": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EmbeddedAttribute"
}
],
"properties": {
"available_values": {
"type": "array",
"description": "List of available values for the attribute",
"items": {
"$ref": "#/components/schemas/ProductListAttributeValue"
},
"maxItems": 1000,
"minItems": 1
},
"max_values": {
"type": "integer",
"description": "Maximum number of values a given product can have for this attribute",
"minimum": 1
}
},
"required": [
"available_values"
]
},
"EmbeddedMediaAttribute": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EmbeddedAttribute"
}
],
"properties": {
"media_type": {
"type": "string",
"description": "Specifies the type of media associated with the attribute.\nWhen `media_type` is set to `IMAGE`, this attribute serves the role of an Image (e.g., for display or illustration purposes).\n\n\nEnum: `\"IMAGE\"`, `\"OTHER\"`\n"
}
}
},
"EmbeddedTextAttribute": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/EmbeddedAttribute"
}
],
"properties": {
"max_length": {
"type": "integer",
"description": "Maximum length for Text attributes",
"example": 255,
"minimum": 1
},
"min_length": {
"type": "integer",
"description": "Minimum length for Text attributes",
"example": 3,
"minimum": 0
}
}
},
"EqualsRuleConditionPayload": {
"type": "object",
"properties": {
"attribute": {
"$ref": "#/components/schemas/ProductAttributeId"
},
"value": {
"$ref": "#/components/schemas/EqualsRuleConditionPayloadValue"
}
},
"required": [
"attribute",
"value"
]
},
"EqualsRuleConditionPayloadValue": {
"description": "The value to compare against",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code (immutable)",
"examples": [
"DATA_NOT_FOUND"
]
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ErrorItem"
}
},
"extensions": {
"type": "object",
"description": "Free map where you find additional context data to better describe the error",
"examples": [
{
"maxLength": 255,
"minLength": 1
}
]
},
"message": {
"type": "string",
"description": "Literal string error description (Please do not base your error handling on this field since it is subject to change)",
"examples": [
"An error occurred while processing your request"
]
}
},
"required": [
"code",
"message"
]
},
"ErrorItem": {
"type": "object",
"properties": {
"extensions": {
"type": "object",
"description": "Free map where you find additional context data to better describe the error",
"examples": [
{
"maxLength": 255,
"minLength": 1
}
]
},
"field": {
"type": "string",
"description": "JsonPath to the field where the error occurred",
"examples": [
"input.account.id"
]
},
"message": {
"type": "string",
"description": "Literal string error item description (Please do not base your error handling on this field since it is subject to change)",
"examples": [
"An error occurred while processing your request: id is null"
]
}
},
"required": [
"message"
]
},
"FulfillmentRequest": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Identifier of the fulfillment partner. Only meaningful when `type` is `FULFILLED_BY_PARTNER`. Ignored for `FULFILLED_BY_SELLER`."
},
"type": {
"type": "string",
"description": "Indicates who is responsible for physically fulfilling the order.\n\n\nEnum: `\"FULFILLED_BY_SELLER\"`, `\"FULFILLED_BY_PARTNER\"`\n"
}
},
"required": [
"type"
]
},
"InRuleConditionPayload": {
"type": "object",
"properties": {
"attribute": {
"$ref": "#/components/schemas/ProductAttributeId"
},
"values": {
"type": "array",
"description": "List of values to check against",
"items": {
"$ref": "#/components/schemas/InRuleConditionPayloadValue"
}
}
},
"required": [
"attribute",
"values"
]
},
"InRuleConditionPayloadValue": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
},
"IsSetRuleConditionPayload": {
"type": "object",
"properties": {
"attribute": {
"$ref": "#/components/schemas/ProductAttributeId"
}
},
"required": [
"attribute"
]
},
"ListAttribute": {
"allOf": [
{
"$ref": "#/components/schemas/Attribute"
},
{
"type": "object",
"properties": {
"default_values": {
"type": "array",
"description": "Default values of the attribute (use the id in your attribute values), used for required attributes only",
"items": {
"type": "string"
}
},
"max_size": {
"type": "integer",
"description": "Max number of values to select. `1` means selection of a single value.",
"minimum": 1
},
"values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListAttributeItem",
"description": "Lis
# --- truncated at 32 KB (175 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mirakl/refs/heads/main/openapi/_original/mirakl-connect-channel-openapi.json