When using Cloud providers, the payload is sent as an json object.
Mirakl Marketplace APIs
To facilitate seamless integration and enable real-time interaction capabilities, MMP provides robust HTTP Webhooks and Cloud Events features:
- HTTP Webhooks: These allow MMP to trigger calls to a developer-defined HTTP endpoint in response to events occurring within the Mirakl platform.
- Cloud Events: With Cloud Events, MMP can publish messages to a user-defined queue in major cloud services including AWS, GCP, and Azure. This service is ideal for developers looking to leverage cloud infrastructure for enhanced scalability and performance.
Our HTTP Webhooks are designed to provide real-time event notifications to your applications, enabling you to react and adapt to changes and actions immediately. Due to the nature of these notifications, which can occur at a high frequency, it is crucial to manage these HTTP Webhooks efficiently to maintain the performance and reliability of your services. As a large volume of HTTP calls can be generated in a short period, especially during peak times, it is essential to ensure that your application scales and performs reliably under such loads. To do so, HTTP calls should be processed asynchronously. The recommendation is to store the content of the HTTP calls received to the endpoint directly in an event queue, and to respond with an HTTP 2xx code as soon as the event is stored in the queue. Then, another process can consume the queue at its own pace and process events.
A recommended architecture can be represented as follows:
To maintain optimal performance and efficiency in our webhook integrations, we implement specific timeouts. These timeouts are crucial for ensuring that HTTP calls do not congest our system and your endpoints. The following timeout are implemented:
- Connect Timeout – 1 Second: This timeout ensures that the connection to your endpoint is established within 1 second. It is crucial that your endpoint is reachable within this timeframe to start processing the webhook notification.
- Read Timeout – 1 Second: Once the connection is established, your server must process the incoming call and respond within 1 second. This includes the time taken by your server to process the webhook data and send back an HTTP response with a status code in the 2xx range, indicating successful receipt and handling of the notification. Once again, process the HTTP call asynchronously will enable to comply with this timeout, even during peak time.
Cloud Events leverages event queues that are hosted in the cloud. Instead of interacting directly with an HTTP endpoint as with HTTP Webhooks, Mirakl sends messages to your designated event queue stored in the cloud.
The following diagram shows a typical setup:
We currently support the following cloud-based event queues:
- AWS SQS
- GCP Pub/Sub
- Azure ServiceBus
Your queue should be accessible over the Internet and permissions should be configured to allow access for Mirakl user.
For further details on setup and permissions, please refer to our documentation.
Languages
Servers
The URL of your server
https://your-service.mirakl.net/
Bodyapplication/json
Example: {"action":"UPSERT","detail":{"active":true,"all_prices":[{"channel_code":null,"discount_end_date":null,"discount_start_date":null,"price":18,"unit_discount_price":null,"unit_origin_price":18,"volume_prices":[{"price":18,"quantity_threshold":1,"unit_discount_price":null,"unit_origin_price":18}]}],"allow_quote_requests":true,"available_end_date":null,"available_start_date":null,"channels":["US"],"currency_iso_code":"EUR","date_created":"2025-01-01T07:52:10Z","description":"Tennis Racket is made with high grade durable material, this racket is perfect for any tennis star.","eco_contributions":[{"eco_contribution_amount":3.59,"epr_category_code":"FR-DEA","producer_id":"FR123456_89ABCD"},{"eco_contribution_amount":0.99,"epr_category_code":"DE-WEEE","producer_id":"ProducerID1"}],"favorite_rank":null,"fulfillment_center_code":"DEFAULT","last_updated":"2025-01-02T00:11:22Z","leadtime_to_ship":null,"logistic_class_code":"M","max_order_quantity":null,"measurements":[],"min_order_quantity":null,"min_shipping_price":0,"min_shipping_price_additional":0,"min_shipping_type":"CLC","min_shipping_zone":"DOM1","model":"MARKETPLACE","offer_additional_fields":[],"origin_price":18,"package_quantity":null,"premium":false,"price":18,"price_additional_info":null,"product_sku":"MKP100000000037797","product_tax_code":null,"professional":false,"quantity":500,"shop_id":3,"shop_name":"* Super Shop","shop_sku":"sku-2023","state_code":"2","total_price":18},"id":2023}
- The URL of your server
https://your-service.mirakl.net/OfferWebhookCloud
application/json
{ "event_type": "OFFER", "payload": { "action": "UPSERT", "detail": { … }, "id": 2023 } }
Bodyapplication/json
Example: {"details":{"channel":{"code":"US"},"commercial_id":"Order_00001","created_date":"2022-03-07T17:14:07.673Z","currency_iso_code":"EUR","customer":{"accounting_contact":null,"billing_address":{"city":"New York City","civility":"Mr","company":"LIMARK Company","company_2":"Other Inf. Company","country":"USA","country_iso_code":"USA","firstname":"smith","lastname":"Taylor","phone":null,"phone_secondary":null,"state":"New York","street_1":"113 MacDougal Street","street_2":"1st floor","zip_code":"NY 10012"},"civility":"Mr","customer_id":"Customer_id_001","delivery_contact":null,"email":"customer@mail.com","firstname":"Smith","lastname":"Taylor","locale":"en_US","organization":{"address":{"city":"New York","country_iso_code":"USA","state":"Manhattan","street1":"113 MacDougal Street","street2":"1st floor","zip_code":"NY 10012"},"identification_number":"00410609124541","name":"Limark Company Inc.","organization_id":"123","tax_identification_number":"96-25472919"},"shipping_address":{"additional_info":"One article per box","city":"New York","civility":"Mr","company":"LIMARK Company","company_2":"Other Inf. Company","country":"USA","country_iso_code":"USA","firstname":"Smith","internal_additional_info":"No additional information","lastname":"Taylor","phone":null,"phone_secondary":null,"state":"Manhattan","street_1":"113 MacDougal Street","street_2":"1st floor","zip_code":"NY 10012"}},"customer_debited_date":null,"delivery_date":null,"event_date":"2022-03-07T17:14:07.673Z","fulfillment":{"center":{"code":"DEFAULT"}},"imprint_number":"My_Imprint_Number","invoice_details":{"document_details":[{"format":"PDF"}],"payment_terms":null},"order_additional_fields":[],"order_id":"Order_00001-A","order_lines":[{"category_code":"5216103101","commission_fee":19.05,"commission_taxes":[{"amount":3.81,"code":"TAXDEFAULT","rate":20}],"description":"This is description of the offer 1850: \n Blending a sleek and modern shape with a stylishly embossed back cover, the GALAXY S5 is designed to complement your individual style.","fees":[{"amount":10,"code":"fee1"}],"funding":{"customer":{"fees":{"breakdown":[]},"offer":{"breakdown":[{"amount":30,"method":"VISA_CARD"},{"amount":52.5,"method":"DEFAULT_CUSTOMER"}]},"shipping":{"breakdown":[{"amount":4,"method":"VISA_CARD"}]},"total_amount":86.5,"total_tax_amount":20},"operator":{"offer":{"breakdown":[{"amount":30,"method":"VOUCHER_METHOD"},{"amount":52.5,"method":"PROMOTION_METHOD"}]},"total_amount":86.5,"total_tax_amount":20}},"measurement":null,"offer_id":2083,"offer_leadtime_to_ship":4,"offer_sku":"1850","offer_state_code":"11","order_line_additional_fields":[],"order_line_id":"Order_00001-A-1","order_line_index":1,"order_line_state":"WAITING_ACCEPTANCE","order_line_state_reason_code":null,"order_line_state_reason_label":null,"price":119,"price_additional_info":null,"price_unit":119,"product_shop_sku":"125069","product_sku":"MKP100000000040663","product_title":"Samsung Galaxy S5 - Gold","promotions":[],"quantity":1,"shipping_from":{"address":{"city":"Suresnes City","country_iso_code":"FRA","state":"Suresnes","street_1":"1 Henry Sellier","street_2":null,"zip_code":"92150"}},"shipping_price":8,"shipping_taxes":[],"tax_recalculation_required":true,"taxes":[],"total_commission":22.86,"total_price":127},{"category_code":"5110107","commission_fee":9.16,"commission_taxes":[{"amount":1.83,"code":"TAXDEFAULT","rate":20}],"description":"This is description of the offer 1100: \n The Raco 26cm Stirfry has a heavy guage aluminium body for efficient heat distribution, a high quality non stick coating and a riveted stainless steel and silicone rubber handle for a comfortable, stay cool grip.","fees":[],"funding":null,"measurement":null,"offer_id":2082,"offer_sku":"1100","offer_state_code":"11","order_line_additional_fields":[],"order_line_id":"Order_00001-A-2","order_line_index":2,"order_line_state":"WAITING_ACCEPTANCE","order_line_state_reason_code":null,"order_line_state_reason_label":null,"price":11,"price_additional_info":null,"price_unit":11,"product_sku":"MKP100000000006735","product_title":"Raco 26cm Open Stirfry Pan","promotions":[],"quantity":1,"shipping_from":{"address":{"city":"Suresnes City","country_iso_code":"FRA","state":"Suresnes","street_1":"1 Henry Sellier","street_2":null,"zip_code":"92150"}},"shipping_price":0,"shipping_taxes":[],"tax_recalculation_required":false,"taxes":[],"total_commission":10.99,"total_price":11}],"order_state":"WAITING_ACCEPTANCE","order_state_reason_code":null,"pay_out_psp_code":"NOT_SPECIFIED","payment_destination":null,"payment_duration":null,"payment_type":"Visa","payment_workflow":"NO_CUSTOMER_PAYMENT_CONFIRMATION","price":130,"promotions":{"applied_promotions":[],"total_deduced_amount":0},"quote_id":null,"references":{"order_reference_for_customer":null,"order_reference_for_seller":null},"shipping_deadline":"2022-03-12T17:14:07.570883856Z","shipping_price":8,"shipping_pudo_id":"C1039","shipping_type_code":"STD","shipping_type_standard_code":"CU_ADD-STD","shipping_zone_code":"INT1","shop_id":101,"shop_name":"Four Leaf Clover","total_commission":33.85,"total_price":138,"transaction_date":null,"transaction_number":null,"waiting_tax_confirmation":false},"id":"Order_00001-A","order_tax_mode":"TAX_EXCLUDED","type":"CREATE"}
- The URL of your server
https://your-service.mirakl.net/OrderCloudPayload
application/json
{ "eventType": "ORDER", "payload": { "details": { … }, "id": "Order_00001-A", "order_tax_mode": "TAX_EXCLUDED", "type": "CREATE" } }
Bodyapplication/json
Example: [{"details":{"channel":{"code":"US"},"commercial_id":"Order_00001","created_date":"2022-03-07T17:14:07.673Z","currency_iso_code":"EUR","customer":{"accounting_contact":null,"billing_address":{"city":"New York City","civility":"Mr","company":"LIMARK Company","company_2":"Other Inf. Company","country":"USA","country_iso_code":"USA","firstname":"smith","lastname":"Taylor","phone":null,"phone_secondary":null,"state":"New York","street_1":"113 MacDougal Street","street_2":"1st floor","zip_code":"NY 10012"},"civility":"Mr","customer_id":"Customer_id_001","delivery_contact":null,"email":"customer@mail.com","firstname":"Smith","lastname":"Taylor","locale":"en_US","organization":{"address":{"city":"New York","country_iso_code":"USA","state":"Manhattan","street1":"113 MacDougal Street","street2":"1st floor","zip_code":"NY 10012"},"identification_number":"00410609124541","name":"Limark Company Inc.","organization_id":"123","tax_identification_number":"96-25472919"},"shipping_address":{"additional_info":"One article per box","city":"New York","civility":"Mr","company":"LIMARK Company","company_2":"Other Inf. Company","country":"USA","country_iso_code":"USA","firstname":"Smith","internal_additional_info":"No additional information","lastname":"Taylor","phone":null,"phone_secondary":null,"state":"Manhattan","street_1":"113 MacDougal Street","street_2":"1st floor","zip_code":"NY 10012"}},"customer_debited_date":null,"delivery_date":null,"event_date":"2022-03-07T17:14:07.673Z","fulfillment":{"center":{"code":"DEFAULT"}},"imprint_number":"My_Imprint_Number","invoice_details":{"document_details":[{"format":"PDF"}],"payment_terms":null},"order_additional_fields":[],"order_id":"Order_00001-A","order_lines":[{"category_code":"5216103101","commission_fee":19.05,"commission_taxes":[{"amount":3.81,"code":"TAXDEFAULT","rate":20}],"description":"This is description of the offer 1850: \n Blending a sleek and modern shape with a stylishly embossed back cover, the GALAXY S5 is designed to complement your individual style.","fees":[{"amount":10,"code":"fee1"}],"measurement":null,"offer_id":2083,"offer_leadtime_to_ship":4,"offer_sku":"1850","offer_state_code":"11","order_line_additional_fields":[],"order_line_id":"Order_00001-A-1","order_line_index":1,"order_line_state":"WAITING_ACCEPTANCE","order_line_state_reason_code":null,"order_line_state_reason_label":null,"price":119,"price_additional_info":null,"price_unit":119,"product_shop_sku":"125069","product_sku":"MKP100000000040663","product_title":"Samsung Galaxy S5 - Gold","promotions":[],"quantity":1,"shipping_from":{"address":{"city":"Suresnes City","country_iso_code":"FRA","state":"Suresnes","street_1":"1 Henry Sellier","street_2":null,"zip_code":"92150"}},"shipping_price":8,"shipping_taxes":[],"tax_recalculation_required":true,"taxes":[],"total_commission":22.86,"total_price":127},{"category_code":"5110107","commission_fee":9.16,"commission_taxes":[{"amount":1.83,"code":"TAXDEFAULT","rate":20}],"description":"This is description of the offer 1100: \n The Raco 26cm Stirfry has a heavy guage aluminium body for efficient heat distribution, a high quality non stick coating and a riveted stainless steel and silicone rubber handle for a comfortable, stay cool grip.","fees":[],"funding":{"customer":{"fees":{"breakdown":[]},"offer":{"breakdown":[{"amount":30,"method":"VISA_CARD"},{"amount":52.5,"method":"DEFAULT_CUSTOMER"}]},"shipping":{"breakdown":[{"amount":4,"method":"VISA_CARD"}]},"total_amount":86.5,"total_tax_amount":20},"operator":{"offer":{"breakdown":[{"amount":30,"method":"VOUCHER_METHOD"},{"amount":52.5,"method":"PROMOTION_METHOD"}]},"total_amount":86.5,"total_tax_amount":20}},"measurement":null,"offer_id":2082,"offer_sku":"1100","offer_state_code":"11","order_line_additional_fields":[],"order_line_id":"Order_00001-A-2","order_line_index":2,"order_line_state":"WAITING_ACCEPTANCE","order_line_state_reason_code":null,"order_line_state_reason_label":null,"price":11,"price_additional_info":null,"price_unit":11,"product_sku":"MKP100000000006735","product_title":"Raco 26cm Open Stirfry Pan","promotions":[],"quantity":1,"shipping_from":{"address":{"city":"Suresnes City","country_iso_code":"FRA","state":"Suresnes","street_1":"1 Henry Sellier","street_2":null,"zip_code":"92150"}},"shipping_price":0,"shipping_taxes":[],"tax_recalculation_required":false,"taxes":[],"total_commission":10.99,"total_price":11}],"order_state":"WAITING_ACCEPTANCE","order_state_reason_code":null,"pay_out_psp_code":"NOT_SPECIFIED","payment_destination":null,"payment_duration":null,"payment_type":"Visa","payment_workflow":"NO_CUSTOMER_PAYMENT_CONFIRMATION","price":130,"promotions":{"applied_promotions":[],"total_deduced_amount":0},"quote_id":null,"references":{"order_reference_for_customer":null,"order_reference_for_seller":null},"shipping_deadline":"2022-03-12T17:14:07.570883856Z","shipping_price":8,"shipping_pudo_id":"C1039","shipping_type_code":"STD","shipping_type_standard_code":"CU_ADD-STD","shipping_zone_code":"INT1","shop_id":101,"shop_name":"Four Leaf Clover","total_commission":33.85,"total_price":138,"transaction_date":null,"transaction_number":null,"waiting_tax_confirmation":false},"id":"Order_00001-A","order_tax_mode":"TAX_EXCLUDED","type":"CREATE"}]
- The URL of your server
https://your-service.mirakl.net/OrderHttpWebhook
application/json
{ "eventType": "ORDER", "payload": [ { … } ] }