Reason codes

A Mirakl operator publishes a list of reason codes — short labels that classify why an order was refused, why a return was opened, or why a refund was granted. The plugin downloads this list per connection and stores it as reference data you can browse from the admin.

Despite living in the Mapping section of these docs, the Reason Codes page is listing-only. There is no mapping form, no default-reason picker and no link from reason codes to Shopware order states. The plugin’s current order-state automation refuses Mirakl orders by sending an “accepted: false” decision per order line, without picking a reason code, so the codes you see on this page are informational reference data: useful for your customer-service team when they handle returns or refusals manually with the operator.

Where to find it

Open the Mirakl admin module and click the Reason Codes tile in the Quick Start section. The list has these columns:

• Code — the operator’s short identifier (for example OUT_OF_STOCK).
• Label — the operator’s display label.
• Type — the operator’s category grouping for the code (refund reasons, refusal reasons, and so on — what each operator returns differs).
• Connections — which of your connections accept this code.

The toolbar has a single button, Refresh Reason Codes.

Refresh

• The setup wizard refreshes the list for you in step 5 (Reason Codes).
• On the Reason Codes page, click Refresh Reason Codes any time. The plugin downloads the operator’s current list, adds any new codes, updates the labels of existing ones, and links the codes to the connection. Running the refresh twice does not duplicate anything.

What is stored

Each row carries:

• Code — the operator’s short identifier.
• Label — the human-readable label.
• Type — the operator’s category (refund vs refusal vs other; varies by operator).
• The connections that accept this code.

The same code published by two different operators is shown as a single row; the Connections column tells you on which connections it is available.

Tips & gotchas

Tip

Walk through the operator’s reason-code list with your customer-service team. The codes are not interchangeable — some affect your seller score, some do not. The operator’s seller documentation explains the consequences of each code, even though the plugin does not pick one for you automatically.

Caution

Some operators change their reason-code list over time. Refresh once a quarter to catch new and retired codes — the listing on this page is your only source of truth inside the plugin for what the operator currently accepts.

Note

If you need refusals to include a specific reason code on the operator side, push the refusal manually through the operator’s own seller portal. The plugin’s automatic refusal currently does not pass a reason code through.

Related

• Order state sync — how the plugin handles order acceptance, shipping and refusal
• Order import — how orders enter Shopware from the operator
• Connecting Mirakl — setup wizard step 5 runs the initial refresh