> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirakl (Carrefour Brasil and other marketplaces) as a data source

> Bring your seller data from Carrefour Brasil and any other Mirakl marketplace to Nekt: orders, order lines, offers, transactions, invoices, payouts, returns and messages.

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.

> [!NOTE]
>
> 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](https://app.nekt.ai/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](https://marketplace.carrefour.com.br/login)), 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.

> [!WARNING]
>
> 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](https://docs.nekt.com/runs/scheduling-and-triggers.md), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/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.

| Tables | What Mirakl needs |
| :- | :- |
| Orders, Order Lines | Access to orders. |
| Offers | Access to offers. |
| Transactions | Access to accounting (transaction logs). |
| Invoices, Billing Cycles, Accounting Documents | Access to accounting. **Billing Cycles** and **Accounting Documents** exist only on marketplaces that use Mirakl's enhanced seller invoicing; on those, **Invoices** stops receiving new documents. If your marketplace does not offer them, deselect them. |
| Returns | Access to orders and returns, on marketplaces that handle returns in Mirakl. |
| Messages | Access to messages. |
| Shop, Categories | Access to the shop account (any shop administrator key has it). |

# 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.

| Stream | Slug | Description |
| - | - | - |
| Orders | `orders` | Orders of your shop, with state, customer, shipping, prices, commission and payment information. |
| Order Lines | `order_lines` | Items of each order: offer, product, quantity, prices, commissions, taxes, refunds and cancellations. |
| 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). |
| Transactions | `transactions` | Transaction lines of your shop's payment account: order amounts, commissions, refunds, fees, adjustments and payouts. |
| Invoices | `invoices` | Accounting documents issued by the marketplace to your shop: automatic invoices, manual invoices and manual credit notes. |
| Billing Cycles | `billing_cycles` | Payout (billing) cycles: what each cycle transferred to your shop and to the marketplace. |
| Accounting Documents | `accounting_documents` | Accounting document requests (invoices, credit notes, fee documents) on marketplaces with Mirakl's enhanced invoicing. |
| Returns | `returns` | Returns requested by customers on your orders, with their lines and tracking. |
| Messages | `threads` | Message threads with customers and the marketplace, with their last 100 messages. |
| 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. |
| Categories | `categories` | Catalog categories of the marketplace, to name the category codes of orders and offers. |

## Fields by stream

> [accordion] 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `acceptance_decision_date` | Datetime | The date where the shop decided to accept or refuse the order. Null when the order was automatically refused or accepted. |
> | `can_cancel` | Boolean | Indicate if the order can be cancelled. |
> | `can_shop_ship` | Boolean | Indicates if shops can or cannot ship orders. |
> | `channel` | JSON (string) | The channel of the commercial's order (JSON object with: code, label). |
> | `commercial_id` | String | Commercial order's identifier. |
> | `created_date` | Datetime | Order's creation date. |
> | `currency_iso_code` | String | Shop's currency (iso format). |
> | `customer` | JSON (string) | Information of the customer who ordered (JSON object with: accounting\_contact, billing\_address, civility, customer\_id, delivery\_contact, firstname, lastname, locale). |
> | `customer_debited_date` | Datetime | The payment's date of the order by the customer. |
> | `customer_directly_pays_seller` | Boolean | True if order is paid directly to seller. False otherwise. |
> | `customer_notification_email` | String | Anonymized customer email usable for notifications that do not expect an answer. |
> | `delivery_date` | JSON (string) | Expected order delivery date (JSON object with: earliest, latest). |
> | `discount_campaigns` | JSON (string) | List of discount campaigns applied to one or more order lines in this order. This field aggregates all unique discount campaigns present across all order lines. Empty or absent if no discount campaigns were applied to any order line. |
> | `fulfillment` | JSON (string) | Fulfillment information (JSON object with: center). |
> | `fully_refunded` | Boolean | Refunds have been requested and their cumulated amounts correspond to the sum of all remaining active order lines. |
> | `has_customer_message` | Boolean | Indicate if the customer has sent a message related to this order. |
> | `has_incident` | Boolean | Indicate if order has incident on at least one order line. |
> | `has_invoice` | Boolean | Is an invoice available for this order. |
> | `invoice_details` | JSON (string) | Invoice information linked to the order (JSON object with: document\_details, payment\_terms). |
> | `last_updated_date` | Datetime | Order's last updated date. |
> | `order_additional_fields` | JSON (string) | Order's custom fields. |
> | `order_id` | String | Order's identifier. |
> | `order_refunds` | JSON (string) | The list of refunds aggregated by group identifier Available when feature ‘order level tax calculation’ is enabled. |
> | `order_state` | String | Order's state. |
> | `order_state_reason_code` | String | Reason's code of the order state. |
> | `order_state_reason_label` | String | Reason's label of the order state. |
> | `order_tax_mode` | String | Please note: In case there is no tax, the prices will show the same amount in TAX\_EXCLUDED and TAX\_INCLUDED mode. The tax mode is only useful if taxes are specified in the order. Possible values: TAX\_EXCLUDED : the price fields (price, unit price, shipping price, cancellation amount, refund amount and order total prices) are expressed without tax (taxes should be added to these prices in order to get the full amount including taxes). TAX\_INCLUDED : the price fields include the tax amount. |
> | `order_taxes` | JSON (string) | Total amount of taxes aggregated per tax code and rate Available when feature ‘order level tax calculation’ is enabled. |
> | `payment_duration` | Integer | The payment's duration (i.e. the delay after which the order is supposed to be paid), in days. Only applicable for PAY\_ON\_DUE\_DATE orders, null otherwise. Note that this field has currently no impact on the order workflow, it is provided for information purposes. |
> | `payment_type` | String | The payment's type used by the customer to pay this order. |
> | `payment_workflow` | String | The payment workflow followed by the order. |
> | `price` | Number | Order's price (sum of order line's price). |
> | `promotions` | JSON (string) | Promotions' summary applied to the order (JSON object with: applied\_promotions, total\_deduced\_amount). |
> | `quote_id` | String | Quote's id from which the order has been placed, or null if it was not from a quote. |
> | `references` | JSON (string) | Order references (JSON object with: order\_reference\_for\_customer, order\_reference\_for\_seller). |
> | `shipping_carrier_code` | String | Shipping carrier code (associated with the Shipping company label). |
> | `shipping_carrier_scac_code` | String | The SCAC code of the order's first shipment. |
> | `shipping_carrier_standard_code` | String | Shipping carrier standard code (associated with the shipping carrier code). |
> | `shipping_company` | String | Shipping company. |
> | `shipping_deadline` | Datetime | Order's shipping deadline. |
> | `shipping_price` | Number | Order's shipping price (sum of order line's shipping price). |
> | `shipping_pudo_id` | String | PickUp DropOff (PUDO) point identifier. |
> | `shipping_tracking` | String | Shipping tracking. |
> | `shipping_tracking_url` | String | Shipping tracking url. |
> | `shipping_type_code` | String | Code of shipping's type. |
> | `shipping_type_label` | String | Label of shipping's type. |
> | `shipping_type_standard_code` | String | Shipping type's standard code. |
> | `shipping_zone_code` | String | Code of shipping's zone. |
> | `shipping_zone_label` | String | Label of shipping's zone. |
> | `total_commission` | Number | Order's total commission (sum of the order line's total commission). |
> | `total_price` | Number | Total order's price (sum of the order's price with shipping price and fees). |
> | `transaction_date` | Datetime | Payment's transaction date. |
> | `transaction_number` | String | Payment's transaction number. |

> [accordion] 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `order_id` | String | Identifier of the order this line belongs to. |
> | `order_commercial_id` | String | Commercial identifier of the order this line belongs to. |
> | `order_created_date` | Datetime | Creation date of the order this line belongs to. |
> | `order_last_updated_date` | Datetime | Last update date of the order this line belongs to, used as the incremental replication key. |
> | `commission_vat` | Number | Commission tax of the order line (deprecated by Mirakl: use commission\_taxes when several taxes apply). |
> | `commission_rate_vat` | Number | Commission tax rate of the order line (deprecated by Mirakl: use commission\_taxes when several taxes apply). |
> | `can_refund` | Boolean | Indicate whether the order line full amount can be refunded. |
> | `cancelations` | JSON (string) | List of the cancellations. |
> | `category_code` | String | Category code of the product associated with the order line. |
> | `category_label` | String | Category label of the product associated with the order line. |
> | `commission_fee` | Number | Order line's commission fee. |
> | `commission_taxes` | JSON (string) | Commission taxes. |
> | `created_date` | Datetime | Order line's creation date. |
> | `debited_date` | Datetime | Order line's debited date. |
> | `description` | String | Order line's description. |
> | `discount_campaign` | JSON (string) | The discount campaign that was applied to this order line (JSON object with: identifier). |
> | `eco_contributions` | JSON (string) | List of eco-contribution amounts and corresponding producer identifiers, if applicable Only available if the operator activates the circular economy information collection. |
> | `fees` | JSON (string) | List of fees applied on the order line. |
> | `last_updated_date` | Datetime | Order line's last updated date. |
> | `measurement` | JSON (string) | Measurement information of the order line (JSON object with: actual\_measurement, measurement\_unit, ordered\_measurement). |
> | `offer_id` | Integer | Associated offer's id. |
> | `offer_sku` | String | Associated offer sku (this is the sku of the offer defined by the shop). |
> | `offer_state_code` | String | State of the offer associated with the order line. |
> | `order_line_additional_fields` | JSON (string) | List of custom fields. |
> | `order_line_id` | String | Order line's identifier. |
> | `order_line_index` | Integer | Order line's index in the order. |
> | `order_line_state` | String | Order line's state. |
> | `order_line_state_reason_code` | String | Reason's code of the order line's state. |
> | `order_line_state_reason_label` | String | Reason's label of the order line's state. |
> | `origin_unit_price` | Number | The original unit price of the offer associated with the order line. |
> | `price` | Number | Order line's price without shipping price. |
> | `price_additional_info` | String | Price's additional information of the offer. |
> | `price_amount_breakdown` | JSON (string) | The breakdown of the price, only available when advanced features are enabled (JSON object with: parts). |
> | `price_unit` | Number | Unit price for the offer associated with the order line. |
> | `product_medias` | JSON (string) | List of all product's media associated to the order line. |
> | `product_shop_sku` | String | Shop SKU of the product associated with the order line. |
> | `product_sku` | String | SKU of the product associated with the order line. |
> | `product_title` | String | Title of the product associated with the order line. |
> | `promotions` | JSON (string) | List of promotions. |
> | `purchase_information` | JSON (string) | Purchase information Only available for One Creditor offers (JSON object with: purchase\_commission\_on\_fees, purchase\_commission\_on\_price, purchase\_commission\_on\_shipping, purchase\_fee\_amount, purchase\_price, purchase\_shipping\_price, purchase\_unit\_price). |
> | `quantity` | Integer | Product's quantity for the order line. |
> | `received_date` | Datetime | Product's date of receipt. |
> | `refunds` | JSON (string) | List of the refunds. |
> | `shipped_date` | Datetime | Order line's shipped date. |
> | `shipping_from` | JSON (string) | Shipping origin (country, full address or warehouse) of the order line (JSON object with: address, warehouse). |
> | `shipping_price` | Number | Total price of the order line's shipping price. |
> | `shipping_price_amount_breakdown` | JSON (string) | The breakdown of the shipping price, only available when advanced features are enabled (JSON object with: parts). |
> | `shipping_taxes` | JSON (string) | List of taxes applied on shipping charges. |
> | `tax_legal_notice` | String | The legal notice applying to the order line’s taxes. |
> | `taxes` | JSON (string) | List of taxes applied on product price. |
> | `total_commission` | Number | Order line's total commission (sum of the commission fee and the commission vat). |
> | `total_price` | Number | Order line's price with shipping price and fees. |

> [accordion] 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `active` | Boolean | Indicates if the offer is active or inactive (not for sale or discontinued). |
> | `allow_quote_requests` | Boolean | Allow customers to request quotes on this offer. |
> | `available_end_date` | String | The date when the offer will be deactivated. |
> | `available_start_date` | String | The date when the offer will be activated. |
> | `channels` | JSON (string) | List of channel codes on which the offer can be sold. (JSON). |
> | `currency_iso_code` | String | ISO code of the currency. |
> | `date_created` | Datetime | Date and time of the offer creation. |
> | `deleted` | Boolean | Indicates whether the offer exists or is deleted. |
> | `description` | String | Offer description. |
> | `eco_contributions` | JSON (string) | Eco-contributions of the offer - only available if the operator setting Data collection related to circular economy regulations has been enabled. (JSON). |
> | `favorite_rank` | Integer | If present, indicates that the offer is a favorite offer ranked. |
> | `fulfillment` | JSON (string) | Fulfillment (JSON). |
> | `is_professional` | Boolean | Indicates if the store is professional or not. |
> | `last_updated` | Datetime | Date and time of the last update of the offer. |
> | `leadtime_to_ship` | Integer | The lead time to ship corresponding to the offer. |
> | `logistic_class` | JSON (string) | Logistic class (JSON). |
> | `max_order_quantity` | Integer | The maximum order quantity customers must select to be able to place an order for that offer. |
> | `measurement` | JSON (string) | Measurement (JSON). |
> | `min_order_quantity` | Integer | The minimum order quantity customers must select to be able to place an order for that offer. |
> | `min_shipping_price` | Number | Minimum shipping charges for the offer. |
> | `min_shipping_price_additional` | Number | Additional shipping charges for the offer. |
> | `min_shipping_type` | String | Shipping method with the minimum shipping charges (code referenced by the operator). |
> | `min_shipping_zone` | String | Shipping zone with the minimum shipping charges (code referenced by the operator). |
> | `msrp` | Number | The retail price recommendation, also referred to as manufacturer's suggested retail price (MSRP) or recommended retail price (RRP). |
> | `offer_additional_fields` | JSON (string) | Custom fields of the offer (JSON). |
> | `offer_id` | Integer | Unique offer identifier assigned by Mirakl. |
> | `ongoing_discount_campaigns` | JSON (string) | Ongoing discount campaigns the offer is currently participating in. (JSON). |
> | `package_quantity` | Integer | For one order, customers can only add packages of product items. |
> | `premium` | Boolean | Indicates if the store is premium or not. |
> | `price_additional_info` | String | Information about the offer price. |
> | `prices` | JSON (string) | List of prices for the offer. (JSON). |
> | `product_sku` | String | Product identifier within the operator's system. |
> | `product_tax_code` | String | Tax code for the product. |
> | `quantity` | Integer | Offer quantity available. |
> | `retail_prices` | JSON (string) | List retail prices for the offer, also referred to as selling prices. (JSON). |
> | `shipping_types` | JSON (string) | List of shipping types for the offer. (JSON). |
> | `shop_id` | Integer | Unique identifier for the store providing this offer (assigned by Mirakl). |
> | `shop_name` | String | Name of the store providing this offer. |
> | `shop_sku` | String | Shop's sku of the offer. |
> | `state_code` | String | Offer condition code. |
> | `warehouses` | JSON (string) | The breakdown of the available quantities of the offer in each warehouse (JSON). |

> [accordion] 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `accounting_document_creation_date` | Datetime | The related accounting document creation date. This field is only available when the referenced accounting document is an automatic invoice or a manual document. |
> | `accounting_document_id` | String | The related accounting document id. This field is only available when the referenced accounting document is a seller or purchase document request. |
> | `accounting_document_number` | String | The related accounting document number. This field is only available when the referenced accounting document is: - an automatic invoice or a manual document, - an **issued** seller or purchase document request. |
> | `amount` | Number | The amount. |
> | `amount_credited` | Number | The amount credited. |
> | `amount_debited` | Number | The amount debited. |
> | `balance` | Number | The balance of the transaction. |
> | `currency_iso_code` | String | The currency of the shop (iso format). |
> | `date_created` | Datetime | Creation date of the transaction line. |
> | `entities` | JSON (string) | Node containing additional information depending on type of the transaction and the domain. (JSON object with: channel, debit, domain, fee, manual\_accounting\_document, one\_off\_item, order, order\_fee). |
> | `id` | String | Identifier of the transaction. |
> | `last_updated` | Datetime | Date of last update of the transaction line. |
> | `pay_out_psp_code` | String | Pay-out PSP code associated with the transaction. |
> | `payment_state` | String | The payment state of the transaction. |
> | `psp_balance` | Number | The Pay-out balance of the transaction. |
> | `seller_billing_cycle_id` | String | The Seller Billing Cycle ID associated with the transaction. |
> | `type` | String | Type of transaction (refund, transaction fee, etc ...). |

> [accordion] 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 table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `currency_iso_code` | String | The currency of the shop. |
> | `date_created` | Datetime | Accounting document creation date. |
> | `details` | JSON (string) | Accounting details. |
> | `due_date` | Datetime | Due date for the payment of the accounting document. |
> | `id` | String | Accounting document identifier (use it for draft document). |
> | `invoice_id` | Integer | Accounting document identifier (present if the accounting document is issued). |
> | `issue_date` | Datetime | Issue date of an accounting document. |
> | `issuing_user` | JSON (string) | Accounting document issuing user (JSON object with: information, type). |
> | `pay_out_psp_code` | String | PSP code for Pay-out. |
> | `payment` | JSON (string) | Accounting document payment details (JSON object with: failure\_reason, reference, state, transaction\_date). |
> | `shop_address` | JSON (string) | Shop address (JSON object with: city, civility, country, firstname, lastname, phone, phone\_secondary, state). |
> | `shop_corporate_name` | String | Shop corporate name if it is a professional shop. |
> | `shop_id` | Integer | Shop id. |
> | `shop_model` | String | Shop model. |
> | `shop_name` | String | Shop name. |
> | `shop_operator_internal_id` | String | Operator internal id for the shop. |
> | `shop_tax_number` | String | Shop tax number if it is a professional shop. |
> | `state` | String | Accounting document state. |
> | `total_amount_excl_taxes` | Number | Total amount charged to the shop (excluding taxes). |
> | `total_amount_incl_taxes` | Number | Total amount charged to the shop (including taxes). |
> | `total_taxes` | JSON (string) | Total taxes. |
> | `type` | String | Accounting document type. |

> [accordion] Billing Cycles
>
> Payout (billing) cycles: what each cycle transferred to your shop and to the marketplace.
>
> Table: `billing_cycles` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `amount_transferred_to_operator` | Number | Total amount to be transferred to the operator. |
> | `amount_transferred_to_seller` | Number | Total amount to be transferred to the seller. |
> | `currency_iso_code` | String | The currency of the shop. |
> | `date_created` | Datetime | Seller billing cycle creation date. |
> | `id` | String | Seller billing cycle identifier. |
> | `pay_out` | JSON (string) | Pay-out details (JSON object with: failure\_reason, reference, state, transaction\_date). |
> | `pay_out_psp_code` | String | PSP code for Pay-out. |
> | `payment_voucher_number` | String | The payment voucher number. |
> | `shop` | JSON (string) | Shop information (JSON object with: shop\_corporate\_name, shop\_id, shop\_model, shop\_name, shop\_operator\_internal\_id). |
> | `summary` | JSON (string) | Financial summary of the billing cycle (JSON object with: total\_commissions\_excl\_tax, total\_commissions\_incl\_tax, total\_fee\_excl\_tax, total\_fee\_incl\_tax, total\_fee\_operator\_remitted\_excl\_tax, total\_fee\_operator\_remitted\_incl\_tax, total\_mirakl\_ads\_credit\_excl\_tax, total\_mirakl\_ads\_credit\_incl\_tax). |

> [accordion] 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`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `currency_iso_code` | String | The currency used for the accounting document request. |
> | `date_created` | Datetime | The accounting document request creation date. |
> | `document_details` | JSON (string) | Details about each accounting document representation. |
> | `document_number` | String | The accounting document number. It is only populated once an accounting document has been issued (e.g. when state is `ISSUED` or `CANCELED`). |
> | `document_upload_date` | Datetime | The last upload date of the accounting document representations. It is only populated once an accounting document has been issued (e.g. when state is `ISSUED` or `CANCELED`). |
> | `due_date` | Datetime | The accounting document due date. |
> | `entities` | JSON (string) | Node containing additional information depending on the type of the accounting document request. Sub-fields are selectively populated depending on `entity_type`; see individual field descriptions. (JSON object with: delivery\_bill\_information, order\_additional\_fields, ship\_to\_iso\_country\_code, shipping\_information, shop\_billing\_cycle). |
> | `entity_date_created` | Datetime | The creation date of the entity the accounting document request relates to. This is not applicable when entity\_type is `SHOP_BILLING_CYCLE_PURCHASE_ORDER`. |
> | `entity_id` | String | The identifier of the entity the accounting document request relates to. The format varies by `entity_type`. |
> | `entity_type` | String | The type of the entity the accounting document request relates to. |
> | `id` | String | The accounting document request unique identifier. |
> | `initial_documents` | JSON (string) | Information about the initial accounting document(s) or accounting document request(s). It is only provided in the case of a `CREDIT_NOTE` or a reissued `INVOICE`. |
> | `initial_payment_state` | String | The accounting document payment state when the document request was created. |
> | `issue_date` | Datetime | The accounting document request issue date. |
> | `issuer` | JSON (string) | The issuer details for the accounting document. (JSON object with: id, locale, organization, type). |
> | `last_updated` | Datetime | The accounting document request last updated date. |
> | `payment` | JSON (string) | The accounting document payment details. It is only populated after the payment has been confirmed. (JSON object with: reference, state, transaction\_date). |
> | `payment_destination` | JSON (string) | Information about how the accounting document payment should be settled. (JSON object with: @type, payment\_reference). |
> | `payment_terms` | JSON (string) | The accounting document payment terms. It is always provided when `entity_type` is `SHOP_BILLING_CYCLE_PURCHASE_ORDER`, `LOGISTIC_PURCHASE_ORDER`, `FEES`, `ONE_OFF_FEES`. It is optional when `entity_type` is `PRODUCT_LOGISTIC_ORDER`. (JSON object with: days, type). |
> | `recipient` | JSON (string) | The recipient details for the accounting document. (JSON object with: billing\_address, id, locale, organization, shipping\_address, type). |
> | `state` | String | The accounting document request state. |
> | `taxes` | JSON (string) | A breakdown of `total_tax_amount` by tax code and rate. |
> | `total_amount_excluding_taxes` | Number | The total amount for the accounting document, excluding taxes. |
> | `total_amount_including_taxes` | Number | The total amount for the accounting document, including taxes. |
> | `total_tax_amount` | Number | The total tax amount for the accounting document. |
> | `type` | String | The accounting document request type. |

> [accordion] Returns
>
> Returns requested by customers on your orders, with their lines and tracking.
>
> Table: `returns` · Primary key: `id` · Sync: Incremental (`last_updated`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date_created` | Datetime | Return creation date. |
> | `description` | String | Description. |
> | `documents` | JSON (string) | Return documents. |
> | `id` | String | Return id. |
> | `label_url` | String | Label URL. |
> | `last_updated` | Datetime | Return last updated date. |
> | `method_code` | String | Return method code. |
> | `order_commercial_id` | String | Order commercial id. |
> | `order_id` | String | Order id. |
> | `reason_code` | String | Return reason code. |
> | `rejection_reason_code` | String | Return rejection reason code. |
> | `return_address` | JSON (string) | The address where items must be returned (JSON object with: city, country\_iso\_code, state, street1, street2, zip\_code). |
> | `return_lines` | JSON (string) | Return lines. |
> | `rma` | String | Return RMA. |
> | `state` | String | Return state. |
> | `tracking` | JSON (string) | Return tracking details (JSON object with: carrier\_code, carrier\_name, carrier\_standard\_code, tracking\_number, tracking\_url). |

> [accordion] Messages
>
> Message threads with customers and the marketplace, with their last 100 messages.
>
> Table: `threads` · Primary key: `id` · Sync: Incremental (`date_updated`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `authorized_participants` | JSON (string) | Thread authorized participants Those are the participants who are authorized to join the thread. |
> | `current_participants` | JSON (string) | Thread current participants Those are the participants who have actually participated in the thread, meaning that they are either sender or receivers of at least one message of the thread. These participants must be on the list of the authorized\_participants. |
> | `customer_organization` | JSON (string) | Data related to the customer organization (B2B transactions) (JSON object with: display\_name, id). |
> | `date_created` | Datetime | Thread created date. |
> | `date_updated` | Datetime | Thread updated date. |
> | `entities` | JSON (string) | Thread entities. |
> | `id` | String | Thread id. |
> | `messages` | JSON (string) | Thread messages. Limited to the last 100 messages of the thread. Present if with\_messages query parameter has been set to true. |
> | `metadata` | JSON (string) | Thread metadata (JSON object with: last\_message\_date, last\_sender, shop\_reply\_needed\_since, total\_count). |
> | `no_store_reply_needed` | JSON (string) | Thread "no store reply needed" actions. Present if "with\_messages" query parameter has been set to true. |
> | `topic` | JSON (string) | Thread topic (JSON object with: type, value). |

> [accordion] 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 table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `applicable_taxes` | JSON (string) | List of the shop's applicable taxes. |
> | `approval_delay` | Integer | Average time for a shop to accept or refuse an order (in seconds). |
> | `approval_rate` | Number | Rate of accepted orders. |
> | `banner` | String | Url of the shop's banner image. |
> | `channels` | Array of strings | List of the channel codes associated to the shop. |
> | `closed_from` | Datetime | The start date of the closing of the shop. |
> | `closed_to` | Datetime | The end date of the closing of the shop. |
> | `contact_informations` | JSON (string) | Contact information (JSON object with: city, civility, country, email, fax, firstname, lastname, phone). |
> | `currency_iso_code` | String | The currency of the shop (iso format). |
> | `date_created` | Datetime | Creation date of the shop. |
> | `default_billing_information` | JSON (string) | The default billing information of the shop, used for invoicing and reporting purposes (JSON object with: corporate\_information, default\_language, fiscal\_information, fiscal\_representative, id, personal\_information, registration\_address). |
> | `description` | String | The description of the shop, max length: 3000 characters. |
> | `domains` | Array of strings | Shop domains. |
> | `dropship` | JSON (string) | Dropship configuration (JSON object with: retail\_pricing\_edition\_enabled). |
> | `evaluations_count` | Integer | Number of evaluations for the shop. |
> | `free_shipping` | Boolean | Whether or not this shop offers free shipping to customers. |
> | `grade` | Number | Global grade of the shop. |
> | `is_professional` | Boolean | Whether or not the shop is professional. |
> | `kyc` | JSON (string) | KYC information (only supported when KYC feature is enabled) (JSON object with: reason, status). |
> | `last_updated_date` | Datetime | The date of the last modification of the shop. Note: The following statistics fields do not update the last\_updated date: orders\_count offers\_count evaluations\_count grade approval\_rate approval\_delay order\_messages\_response\_delay. |
> | `logo` | String | Url of the shop's logo image. |
> | `model` | String | Shop platform model, current possible values : MARKETPLACE DROPSHIP ONE\_CREDITOR. |
> | `offers_count` | Integer | Total count of active offers of the shop. |
> | `order_messages_response_delay` | Integer | Average time for a shop to answer to an order message (in seconds). |
> | `orders_count` | Integer | Total count of debited orders (or if Pay on Delivery, accepted) of the shop. |
> | `payment_details` | JSON (string) | Payment details (JSON object with: paid\_balance, payable\_balance, pending\_balance, reserve\_balance, reserve\_target, sub\_balances). |
> | `payment_method_mandatory` | Boolean | Payment method mandatory. |
> | `premium` | Boolean | Whether or not the shop is premium. |
> | `pro_details` | JSON (string) | Professional details (JSON object with: VAT\_number, corporate\_name, identification\_number, tax\_identification\_number). |
> | `producer_identifiers` | JSON (string) | List of shop’s producer identifiers per Extended Producer Responsibility (EPR) categories. Only available if the operator setting Activate data collection related to circular economy regulations is enabled. |
> | `recycling_policy` | String | Recycling policy - only available if the operator setting Activate data collection related to circular economy regulations has been enabled. |
> | `return_policy` | String | Terms of restitution, max length: 60000 characters. |
> | `shipping` | JSON (string) | Shop shipping configuration (JSON object with: lead\_time\_to\_ship). |
> | `shipping_country` | String | Code ISO 3166-1 alpha-3 of the shipping country. |
> | `shipping_types` | Array of strings | List of shipping types of the shop. |
> | `shipping_zones` | Array of strings | List of shipping zones of the shop. |
> | `shippings` | JSON (string) | All the pair shipping zone / shipping type accepted by the shop. |
> | `shop_additional_fields` | JSON (string) | List of additional fields. |
> | `shop_id` | Integer | The identifier of the shop. |
> | `shop_name` | String | The name of the shop. |
> | `shop_state` | String | The state of the shop. |
> | `specific_billing_informations` | JSON (string) | The list of specific billing information of the shop, used for invoicing and reporting purposes Applies only when the shop is professional. |
> | `suspension_type` | String | Shop suspension type, current possible values: MANUAL : Shop account has been manually suspended in the back-office PENDING\_APPROVAL : Shop account has been suspended at creation AUTOMATIC\_SUSPENSION : Shop account has been suspended by Mirakl Quality Control INCOMPLETE\_PROFILE : Shop account is suspended because some mandatory fields are missing in its profile. |

> [accordion] Categories
>
> Catalog categories of the marketplace, to name the category codes of orders and offers.
>
> Table: `categories` · Primary key: `code` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `code` | String | Hierarchy code. |
> | `label` | String | Hierarchy label. |
> | `label_translations` | JSON (string) | Hierarchy label translation. |
> | `level` | Integer | Hierarchy level. |
> | `parent_code` | String | Parent Hierarchy code. |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.