Custom Order Integration via the Mergado Marketplaces API#

Mergado Marketplaces has ready-made order integrations for systems like POHODA, Shoptet Premium, WooCommerce, UNAS and Upgates. If you manage orders in a different system — for example your own ERP, warehouse management software or an internal application — you can connect them yourself via the Mergado Marketplaces API. All you need is a developer to program the integration on your system’s side.

With the API you can:

  • download orders from all marketplaces connected in Mergado Marketplaces (Allegro, Kaufland, Amazon), including all data available in the CSV order export: customer details, billing and delivery addresses, payment, shipping, order items, documents and notes,
  • mark orders as imported by writing their ID from your system, so the next download returns only new orders,
  • change the order status, including the tracking number and carrier. The change is sent directly to Allegro or Kaufland,
  • upload an invoice for an order on Allegro or Kaufland.

The complete technical documentation is in the Mergado Marketplaces API documentation. It lists all endpoints, their parameters and response formats. You can try out calls directly against your e-shop’s data.

📝 Good to know:

What you’ll need#

  • An active Mergado Marketplaces extension with at least one marketplace connected.
  • A Personal Access Token (PAT) from your Mergado account with the Read e-shop data permission.
  • Your e-shop ID in Mergado.
  • A developer to program the integration in your system.

⚠️ Use either the API or a ready-made e-shop integration — not both at the same time. If you have an active order integration with an e-commerce platform (such as Shoptet Premium, Upgates or WooCommerce) in Mergado Marketplaces and also process the same orders via the API, the two systems may overwrite each other’s order statuses.

How to set up the integration#

1. Create a personal access token#

  1. In Mergado Editor, click your profile in the top right and open API and Access.
  2. Click + Create token, give the token a name (for example “Order integration for ERP”) and set its validity period.
  3. In the permissions, tick Read e-shop data under the E-shop group. The Mergado Marketplaces API does not need any other permissions.
  4. Create the token, copy it and store it securely. It will not be shown again after you leave the page.

You can find the detailed procedure in the article Personal Access Token (PAT).

⚠️ Do not confuse Read e-shop data (E-shop group) with Read user’s e-shops (User group). The Mergado Marketplaces API needs the former.

The token has access to the same e-shops as your account. Reading orders only requires read access to the e-shop. Changing an order status, uploading an invoice or writing a custom order ID requires write access to the e-shop.

2. Find your e-shop ID#

Every API call includes the numeric e-shop ID in Mergado. The easiest way to find it is to enable the display of internal IDs in the API and Access settings. The e-shop ID will then appear in brackets next to its name. The procedure is described in Displaying Internal Entity IDs.

3. Try out the API in the documentation#

  1. Open the Mergado Marketplaces API documentation.
  2. Click Authorize and enter your personal access token.
  3. Select, for example, the endpoint for listing orders, enter your e-shop ID and click Try it out and then Execute.

The documentation will show you a real response with your order data as well as the exact request URL that your developer can use directly.

4. Integrate your system#

All calls go through the Mergado API at https://api.mergado.com/apps/ordelogyproducts/proxy. The token is sent in the Authorization: Bearer <your token> header. Your developer will find the specific endpoints and parameters in the documentation.

For regularly pulling orders into your system, we recommend the following approach:

  1. Download changes at regular intervals. When listing orders, use the updated_since parameter with the time of the last download. You’ll receive new orders as well as any orders where something has changed since then — for example status, details, a synchronisation error or an uploaded invoice.
  2. Mark each order after import. Save the ID the order has in your system. With the imported=false parameter you can then list only orders that have not yet been imported.
  3. Write changes back. When you dispatch an order in your system, send the status SENT with the tracking number via the API. The change is written directly to the marketplace. You can upload an invoice the same way.

Times without a specified time zone are interpreted by the API as Central European Time (Europe/Prague). All times in the API responses are in the same time zone.

Order statuses#

Mergado Marketplaces maps the statuses from individual marketplaces to a unified set. In the API they appear as follows:

API status Status in Mergado Marketplaces
OPEN open
READY not shipped
PROCESSING processing
SENT shipped
ONHOLD on hold
RETURNED returned
CANCELLED cancelled
UNKNOWN unknown

The following statuses can be set via the API:

Marketplace Settable statuses
Allegro PROCESSING, SENT, CANCELLED, ONHOLD
Kaufland PROCESSING, SENT, CANCELLED

For Amazon, orders can only be read via the API.

The status in Mergado Marketplaces updates only once the marketplace accepts it. If the marketplace rejects it, the API returns an error with the marketplace’s reason, and the error is also shown on the order in Mergado Marketplaces. Failed changes are not retried automatically. You can resend a status the order already has — for example when you want to add a tracking number to an order that is already marked as shipped.

Invoices#

You can upload a PDF invoice of up to 5 MB, together with an invoice number, to an order on Allegro or Kaufland via the API. The upload result is visible in the order history in Mergado Marketplaces.

Limits#

  • You can send at most 60 requests per minute from a single IP address.
  • A single call returns at most 1,000 orders. Additional orders can be loaded using pagination.

FAQ#

Do I need a special connection in Mergado Marketplaces to use the API?#

No. A personal access token and an e-shop ID are all you need. In the Connections section, just check that order synchronisation is enabled for the relevant marketplaces. You do not need to configure anything else for the API.

The API returns a 403 error “Missing required scope: shop.read”. What should I do?#

The token does not have the Read e-shop data permission. Create a new token and tick this permission under the E-shop group.

The API returns a 403 error “Access denied for this eshop”. What should I do?#

Your account does not have the required access to the e-shop, or the e-shop ID does not match. Check the e-shop ID and your access to it. Changing a status, uploading an invoice and writing an order ID all require write access. Newly granted access may take up to 5 minutes to take effect.

The API returns a 401 error. What should I do?#

The request does not contain a token, or the token is invalid. Check that you are sending the complete token in the Authorization header and that it has not expired or been revoked.

Why am I missing status changes on older orders when downloading by date?#

The date_from and date_to parameters filter by the date the customer placed the order. They do not capture status changes on older orders, such as cancellations. Use the updated_since parameter for regular synchronisation.

Can I use the API alongside an e-shop platform integration?#

We do not recommend it. If orders are processed simultaneously by an e-shop integration (such as Shoptet Premium or Upgates) and your system via the API, they may overwrite each other’s order statuses. Use either the API or the ready-made integration for order transfer.

Can I work with multiple e-shops via the API?#

Yes. The token works for all e-shops your Mergado account has access to. Each call specifies the e-shop ID you want to work with.

Can you help us with the integration?#

The integration itself is programmed by your developer following the documentation. If you run into a problem during the integration or find that the API is missing a piece of data you need, contact Mergado support.

Was this article helpful?