Wharfwell for Mirakl marketplaces: setup and user guide
What Wharfwell does
Wharfwell shows the Mirakl marketplace orders a ticket is about in the Zendesk ticket sidebar: the lines and their states, prices, shipping and tracking, refunds, cancellations, open incidents and the order's message thread. Agents you allow can accept or refuse new orders, set tracking, mark orders as shipped, refund or cancel lines, cancel an order, resolve an incident, and reply to the customer or the marketplace operator. Every action asks for confirmation first and is logged on the ticket as an internal note.
It works with marketplaces that run on Mirakl's marketplace platform, through the Seller API each of them offers to its shops. Wharfwell is not made, endorsed or certified by Mirakl. Mirakl is a trademark of Mirakl SAS.
1. What you need from each marketplace
| Setting | Where to find it |
|---|---|
| API host | The host name of the marketplace's Mirakl API, like yourmarketplace-prod.mirakl.net or marketplace-api.example.com. The marketplace's seller API documentation or seller support gives it. Host name only: no https://, no path |
| Shop API key | Seller back office > your user menu (top right) > API Key. Generate one if there is none. Generating a new key replaces the old one, so paste the new key into Wharfwell if you ever do |
| Shop id (optional) | Only if your key reaches several shops on that marketplace: the id of the shop whose orders you support |
The key acts with the rights of the back office user it belongs to. Use a user that may manage orders and messages; if that user cannot do something, Wharfwell shows the marketplace's refusal.
2. Install and configure
- Install Wharfwell from the Zendesk Marketplace and choose the Standard plan ($5 per agent per month, 14-day trial; Zendesk asks for a card).
- For Marketplace 1 enter the Name your agents know, the API host and the Shop API key. Zendesk stores the key as a secure setting: agents' browsers never receive it, and Zendesk only sends it to the API host you entered.
- Add up to four more marketplaces the same way. Optional per marketplace: Shop id, Back
office link (an
https://link; write{order_id}where the order id goes, for examplehttps://yourmarketplace.example/mmp/shop/order/{order_id}if that is how your back office addresses orders), and Brands (Zendesk brand ids whose tickets list this marketplace first). - Optional: Ticket field with the order id (the numeric id of a ticket field), if your team or a form records the order id there.
- Search by email: days of orders (30 by default, 90 at most, 0 turns it off). See section 4.
- Who may take actions:
admin(the default),agentfor everyone, custom role ids, orgroup:<id>, separated by commas. Switch each kind of action on or off, and set the Largest refund without an admin in the order's currency (0 means no limit).
3. How Wharfwell finds the order
Mirakl marketplaces put the order id in their notification emails, like 2210345678-A (the
customer's order number plus a letter for your shop's part of it). When a ticket opens, Wharfwell
looks for order ids in the subject, the conversation and the ticket field you chose, and asks every
connected marketplace for them at once (one request each). Nothing else is read until an agent opens
an order or looks something up.
The lookup box below the orders takes:
- an order id, with or without the
-A(2210345678also finds2210345678-Aand-B), - the order reference the customer sees, when the marketplace shows customers its own number,
- an email address (see section 4).
Choose one marketplace or all of them in the list above the box.
4. Search by email, and why it is limited
Mirakl's Seller API finds orders by order id and reference, not by customer email, and the email it gives shops is usually an anonymized notification address that forwards to the customer. When a ticket has no order id, the sidebar offers Search the last 30 days by email: Wharfwell reads the orders created in that window (newest first, at most 300 per marketplace) and keeps only those whose notification email is exactly one of the requester's addresses. Other orders are discarded at once and never shown. If the requester wrote from their own address rather than the marketplace's, there is nothing to match: ask for the order id.
5. The order view
- Lines: quantity, product, your SKU, price, shipping, the line's state, what was refunded or canceled, and an open incident with its reason.
- Totals and payment, shipping: method, carrier and tracking number with a tracking link, ship-by date, expected delivery and the delivery address. On marketplaces with multi-shipment, each shipment and its tracking.
- Messages: the latest messages of each thread on the order, from the customer, the operator or your shop, with "Waiting for your reply since" when the marketplace expects an answer.
- Insert status in reply: adds the order id, status, carrier, tracking number and expected delivery to the reply you are writing. Nothing is sent.
6. Actions
Each action opens a confirmation panel that says exactly what will happen. Nothing is sent until the agent clicks the button, and the button stays off while anything is wrong (the red box says what).
| Action | When it is offered | What it does on the marketplace |
|---|---|---|
| Accept or refuse | The order waits for your acceptance | Accepts or refuses each line (OR21). A decision is needed for every line |
| Add or change tracking | The order is to ship or shipped | Sets the carrier (from the marketplace's list, or a name and link) and the tracking number (OR23) |
| Mark as shipped | The order is to ship | Confirms shipment (OR24); the customer is told it is on its way |
| Refund | A line has shipped and has money left | Refunds a quantity of each line you pick, with or without its shipping, with a refund reason (OR28). Wharfwell adds the tax part when the marketplace asks shops to state it, in proportion to the amount |
| Cancel lines | A line has not shipped yet | Cancels a quantity of each line you pick, with a cancellation reason (OR30) |
| Cancel order | The marketplace allows canceling the whole order | Cancels every line (OR29) |
| Resolve incident | A line has an open incident | Closes it with a resolution reason (OR64) |
| Reply | The order has a thread | Sends your message in the thread to the customer, the operator or both (M12) |
| New message | Always, on an order | Starts a thread on the order with a subject and your message (OR43) |
After the marketplace accepts, Wharfwell writes one internal note on the ticket (marketplace, order,
lines, amounts, reason, agent, your note) and adds a tag: wharfwell_accept, wharfwell_tracking,
wharfwell_shipped, wharfwell_refund, wharfwell_cancel, wharfwell_incident or
wharfwell_message. If the marketplace's answer is lost, Wharfwell reads the order again and only
then reports what happened; it never sends an action twice on its own.
Reasons and carriers come from each marketplace, so agents only see choices the marketplace accepts. Marketplaces decide which actions shops may take: some review refunds before paying them out, some turn off partial acceptance or shop cancellations, and many filter messages that contain links, emails or phone numbers. When a marketplace refuses, Wharfwell shows its answer and writes nothing.
7. What Wharfwell does not do
- It does not turn marketplace messages into Zendesk tickets. That needs a server watching every marketplace around the clock, and Wharfwell has none. It shows and answers the thread of the order on the ticket.
- It does not show returns or download attachments yet, and does not change offers, prices or stock.
8. Troubleshooting
| The sidebar says | What to do |
|---|---|
| "did not accept the shop API key" | Paste the current key from that marketplace's back office (user menu > API Key). Generating a key there replaces the old one |
| "refused this with the shop API key" | The key's back office user lacks the right for that action, or the marketplace does not allow it for shops |
| "Nothing at ... answers like the Mirakl Seller API" or "answered with a web page" | The API host is wrong: use the API host from the marketplace's seller API documentation, not the back office address |
| "is not set up yet" | The API host setting has https://, a path or capital letters; enter the host name only |
| "is rate limiting requests" | The marketplace limits how often shops may call it. Wait a minute |
| "No order ... on your marketplaces" | The id in the ticket belongs to a marketplace you have not connected, or a different shop (set the Shop id) |
| An action button is missing | The order's state does not allow it, the action is switched off, or your role is not in "Who may take actions". New tickets are read-only until saved |
9. Data and security
Wharfwell runs in the agent's browser with no Great Work server. Keys stay in Zendesk secure settings and are only ever sent, by Zendesk, to the API host you entered for that marketplace. Nothing is stored outside Zendesk and the marketplaces, there is no export, no background work and no AI. The privacy policy lists exactly what is read and why.
Questions: hello@greatwork.company (reply within one business day).