Mirakl connector

Use this connector if you operate a Mirakl-powered marketplace and want Carriyo to manage shipping on behalf of your sellers. Carriyo polls every five minutes for orders in SHIPPING status and books them as shipments. Carriyo writes labels and status updates back to Mirakl so sellers see fulfillment progress in their Mirakl dashboard.

Only shops with the Mirakl additional field carriyofulfillment set to true are picked up. This lets you control which sellers Carriyo fulfills.

If you're a seller selling on a Mirakl marketplace, use the Mirakl Connect connector instead.

Capabilities

• Order ingestion. Polls every five minutes for orders in SHIPPING status.
• Multi-pickup splitting. A Mirakl order with line items from different pickup addresses becomes one Carriyo shipment per address.
• Outbound label. When Carriyo generates a label, the connector registers the shipment with Mirakl, carrier name and tracking number. It then uploads the label PDF as a Mirakl order document.
• Outbound status. When the Carriyo shipment ships, the connector marks the Mirakl shipment SHIPPED. When it's delivered, RECEIVED. The connector also posts a seller-facing thread message alongside.
• Carrier reassignment. If you re-route a shipment after the initial Mirakl push, the connector deletes the old Mirakl shipment and creates a new one.

Setup

Configure in the Carriyo Dashboard under Connectors → Mirakl.

• Base URL: your Mirakl marketplace URL (https://your-marketplace.mirakl.net).
• API Key: your Mirakl front-API key. The connector sends it as a raw Authorization header (Mirakl's pattern, not OAuth).
• Default currency: used when a Mirakl order does not carry one.
• Auto Detect Item Origin Country: optional toggle.
• Connected shops: read-only list refreshed from Mirakl.
• Shop Attribute Mapping: map Carriyo custom-attribute keys to Mirakl shop additional-field codes.

Data mapping

Mirakl	Carriyo
order_id	references.partner_order_reference
{order_id}-{addressHash}	references.partner_shipment_reference (per pickup address)
order_lines	shipment items
offer_sku / product_sku	product_ref / sku
shipping_from.address	pickup (grouped per shipment)
customer shipping address	dropoff
shop_name + shop.contact_informations.phone_secondary	pickup contact
shipping_type_label	Carriyo delivery type (case-insensitive match)

The Mirakl shipment id is stored on the Carriyo shipment as carriyo_metadata.mirakl_shipment_id so subsequent status updates target the correct record.

Limits and cadence

• Cadence. Order ingestion runs every five minutes (EventBridge cron). Outbound status updates fire on the Carriyo webhook triggers default_label_update, shipped, and delivered.
• Per-run cap. 1000 orders and 1000 shops per run, 100 per page.
• Shops cache. Connected-shops list is cached for six hours.
• No COD. All shipments are created as PRE_PAID.
• Refunded orders. Fully-refunded orders are silently ignored.
• Confirm errors. Errors on shipment confirmation are logged as warnings; the connector does not retry.