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:- 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 ishttps://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). - 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.
- Mirakl API URL: Address of your marketplace’s Mirakl instance, e.g.
https://carrefourbr-prod.mirakl.netfor 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.
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.
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.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
Orders
Orders of your shop, with state, customer, shipping, prices, commission and payment information.Table:
orders · Primary key: order_id · Sync: Incremental (last_updated_date)Order Lines
Order Lines
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)Offers
Offers
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)Transactions
Transactions
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)Invoices
Invoices
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 tableBilling Cycles
Billing Cycles
Payout (billing) cycles: what each cycle transferred to your shop and to the marketplace.Table:
billing_cycles · Primary key: id · Sync: Full tableAccounting Documents
Accounting Documents
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
Returns
Returns requested by customers on your orders, with their lines and tracking.Table:
returns · Primary key: id · Sync: Incremental (last_updated)Messages
Messages
Message threads with customers and the marketplace, with their last 100 messages.Table:
threads · Primary key: id · Sync: Incremental (date_updated)Shop
Shop
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 tableCategories
Categories
Catalog categories of the marketplace, to name the category codes of orders and offers.Table:
categories · Primary key: code · Sync: Full tableImplementation 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.