Skip to main content
Mirakl is the platform that runs many online marketplaces, including Carrefour Brasil (marketplace.carrefour.com.br). If you sell on a Mirakl marketplace, this connector reads your shop’s data through Mirakl’s seller API: orders and their items, your offers with stock and prices, the transaction lines of your payment account (sales, commissions, refunds and payouts), the invoices and payout cycles of the marketplace, returns and customer messages. The same connector works for every Mirakl marketplace: you only tell it the address of your marketplace’s Mirakl instance.
The connector only reads data. It never changes orders, offers or anything else in your shop. To prepare the offers file, it asks Mirakl to generate an offer export, which does not change your offers.

Configuring Mirakl as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Mirakl option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

You need two things from your marketplace:
  1. The Mirakl API URL of the marketplace. It always ends in .mirakl.net (other addresses are not accepted; if your marketplace gives you a different API address, contact Nekt support). For Carrefour Brasil it is https://carrefourbr-prod.mirakl.net. For other marketplaces, ask the marketplace’s seller support for the “Mirakl API URL” (it is not the address of the seller panel).
  2. An API key of your shop. In the marketplace’s seller back office (for Carrefour Brasil, marketplace.carrefour.com.br), open your user settings, go to API Key and generate a key. The key reads what that user can see, so generate it with the shop administrator (or a user with access to orders, offers and accounting). Generating a new key replaces the old one: update the source when you do.
The following configurations are available:
  • Mirakl API URL: Address of your marketplace’s Mirakl instance, e.g. https://carrefourbr-prod.mirakl.net for Carrefour Brasil.
  • API Key: Your shop’s API key.
  • Start Date: Earliest date read on the first sync. Orders, transactions, accounting documents, returns and messages changed since this date are brought in.
  • Shop ID (advanced, optional): Only if your user has access to several shops on the marketplace: the identifier of the shop to read. Leave it empty to read your default shop. To sync several shops, create one source per shop.
Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the records changed since the last sync (with a one-hour margin). We recommend it for Orders, Order Lines, Offers, Transactions, Accounting Documents, Returns and Messages. Keep Order Lines incremental: its rows come with the orders read in each sync.
    • Full table: every time the extraction happens, we’ll get the current state of the data. Shop, Invoices, Billing Cycles and Categories are always full table.
Mirakl allows a full offer export only once a day. Keep Offers incremental and avoid running more than one Full sync of this source on the same day; otherwise the offers table is not updated in that run and the run log says so.
Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Mirakl limits how often some data can be read (transaction lines: 60 reads per hour, shared with your other integrations), so an hourly or less frequent trigger is a good fit. Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here. Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

Permissions and marketplace features

The API key reads what its user can see. If the user cannot read an area (for example, accounting), the tables of that area are skipped in each run, marked as failed with a message naming them, and the other tables keep syncing. Generate the key with the shop administrator, or deselect those tables.

Streams and Fields

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Nested values (customer, addresses, taxes, refunds, prices per channel, messages) are stored as JSON text.

Fields by stream

Orders of your shop, with state, customer, shipping, prices, commission and payment information.Table: orders · Primary key: order_id · Sync: Incremental (last_updated_date)
Items of each order: offer, product, quantity, prices, commissions, taxes, refunds and cancellations.Table: order_lines · Primary key: order_line_id · Sync: Incremental (order_last_updated_date)
Your offers (SKU, product, stock, prices, shipping) as exported by Mirakl, including inactive offers and, after the first run, the ones deleted (deleted = true).Table: offers · Primary key: offer_id · Sync: Incremental (last_updated)
Transaction lines of your shop’s payment account: order amounts, commissions, refunds, fees, adjustments and payouts.Table: transactions · Primary key: id · Sync: Incremental (last_updated)
Accounting documents issued by the marketplace to your shop: automatic invoices, manual invoices and manual credit notes (column type).Table: invoices · Primary key: type, id · Sync: Full table
Payout (billing) cycles: what each cycle transferred to your shop and to the marketplace.Table: billing_cycles · Primary key: id · Sync: Full table
Accounting document requests (invoices, credit notes, fee documents) on marketplaces with Mirakl’s enhanced invoicing.Table: accounting_documents · Primary key: id · Sync: Incremental (last_updated)
Returns requested by customers on your orders, with their lines and tracking.Table: returns · Primary key: id · Sync: Incremental (last_updated)
Message threads with customers and the marketplace, with their last 100 messages.Table: threads · Primary key: id · Sync: Incremental (date_updated)
Your shop’s account information on the marketplace: state, grade, counters, balances, shipping and billing settings. One row. Bank account details are not synced.Table: shop · Primary key: shop_id · Sync: Full table
Catalog categories of the marketplace, to name the category codes of orders and offers.Table: categories · Primary key: code · Sync: Full table

Implementation notes

  • Orders are read by their last update date: every sync brings the orders created or changed since the previous one, so a status change (shipped, refunded, cancelled) updates the order and its lines.
  • Offers come from Mirakl’s offer export. The first sync (and a Full sync) exports every offer, active and inactive (Mirakl allows this full export once a day, so don’t run more than one Full sync of this source per day); later syncs export only the offers changed since the previous one, including the ones deleted, which arrive with deleted = true and only a few fields filled.
  • Messages carry the last 100 messages of each thread, a limit set by Mirakl.
  • Amounts are in the shop’s currency (currency_iso_code). All dates are in UTC.
  • Product details come with the offers (product_sku) and with the order lines (product_title, category_code); Mirakl’s seller API has no list of the shop’s products.