Magalu (Magazine Luiza) is one of Brazil’s largest retail and e-commerce platforms. The Magalu Seller API provides access to your marketplace seller data including orders (with their embedded deliveries), delivery invoices (NF-e), product catalog (SKUs), pricing, and inventory. This connector enables you to extract and analyze your Magalu Marketplace operations data.

Configuring Magalu as a Source

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

1. Add account access

You’ll need to authorize Nekt to access your Magalu Seller data. Click on the Magalu Authorization button and log in with your Magalu account. Grant the necessary permissions for the seller account you want to extract data from.

Make sure you’re logged in with a Magalu account that has seller access and appropriate permissions to view orders, deliveries, and product catalog data.

The following configurations are available:

Start Date: (Optional) Lower bound for the incremental Orders sync (updated_at__gte filter on the API). Deliveries invoices are fetched for the deliveries of the synced orders, so they follow the same bound indirectly (their own bookmark is issued_at). If omitted, orders are synced from the full history available in the API. SKUs, Prices and Stocks are full-table extractions and ignore this setting.

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 new data - which is good if, for example, you want to keep every record ever fetched.
- Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.

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). Optionally, you can define some additional settings:

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.
Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

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.

Streams and Fields

Below you’ll find all available data streams from Magalu and their corresponding fields:

SKUs

Product catalog stream containing all SKUs (Stock Keeping Units) from your Magalu seller portfolio.Key Fields:

Field	Type	Description
`sku`	String	SKU identifier - unique code that identifies the product
`title`	String	Product title or name
`description`	String	Detailed product description
`brand`	String	Brand name of the product
`status`	String	Current status (e.g., ‘active’, ‘inactive’, ‘pending’, ‘rejected’)
`active`	Boolean	Whether the SKU is currently active and available for sale
`condition`	String	Product condition (e.g., ‘new’, ‘used’, ‘refurbished’)
`type`	String	Product type classification
`created_at`	Timestamp	When the SKU was created
`updated_at`	Timestamp	When the SKU was last updated (the skus stream syncs as full table; this field is useful for change tracking)
`creator`	String	User who created the SKU
`updater`	String	User who last updated the SKU
`attributes`	Array	Array of product attributes (name/value pairs for characteristics like Color, Size)
`datasheet`	Array	Array of technical specifications (name/value pairs like Voltage, Power, Warranty)
`extra_data`	Array	Array of additional custom data fields
`identifiers`	Array	Array of product identifier objects (type, value)
`has_ean`	Boolean	Whether the product has an EAN barcode
`group`	Object	Product group information linking related SKUs/variants (id)
`categories`	Array	Array of category classifications (categories, sub_categories, product_type, channel)
`channels`	Array	Array of sales channels where product is available (id)
`url_marketplace`	Array	Array of marketplace listing URLs (channel, url)
`dimensions`	Array	Array of dimension sets (name, height, length, width, weight — each measure as value/unit)
`images`	Array	Array of product images (reference, type)
`videos`	Array	Array of product videos (reference, type)
`podcasts`	Array	Array of related podcasts (reference, type)
`fulfillment`	Boolean	Whether the product uses fulfillment services
`perishable`	Boolean	Whether the product is perishable

Orders

Orders stream containing all marketplace orders with customer, payment, and delivery information.Key Fields:

Field	Type	Description
`id`	String	Unique identifier for the order
`code`	String	Order code in the platform
`status`	String	Order status (e.g., ‘new’, ‘approved’, ‘cancelled’, ‘finished’)
`created_at`	Timestamp	When the order was created
`updated_at`	Timestamp	When the order was last updated (replication key)
`approved_at`	Timestamp	When the order was approved
`purchased_at`	Timestamp	When the order was purchased
`channel`	Object	Sales channel information (id, extras, marketplace)
`customer`	Object	Customer details (name, email, document_number, customer_type, birth_date, phones)
`amounts`	Object	Order totals (currency, normalizer, total, commission, discount, freight, tax)
`foreign_amounts`	Object	Foreign currency amounts (currency, normalizer, total, exchange_rate)
`deliveries`	Array	Array of order deliveries (id, code, status, purchased_at, seller, amounts, items). Each delivery carries a `shipping` object with `pickup_details`, `drop_details`, `recipient`, `handling_time`, `deadline`, `provider` (id, name, description, extras), `tracking_url`, `tracking`, `shipped_at`, `delivered_at` and `cancelled_at`
`payments`	Array	Array of payment methods (amount, currency, method, method_brand, description, installments, normalizer, integration_type, authorization_code, gateway, extras)

Deliveries invoices

Performance Impact: This stream calls the invoices endpoint once per delivery embedded in the synced Orders (deliveries[]). Large delivery volumes increase API traffic and extraction time. Enable it only when you need NF-e (Nota Fiscal eletrônica) keys or XML payloads.

Brazilian electronic invoice (NF-e) metadata and XML for each delivery. Child stream of Orders: one request is made per delivery listed in each order, except deliveries with status cancelled, which never carry an invoice and are skipped. Deliveries for which the API answers 403 or 404 (no invoice available) are skipped with a warning instead of failing the run.Key Fields:

Field	Type	Description
`key`	String	NF-e access key (chave de acesso); primary key for this stream
`delivery_id`	String	Delivery identifier (from the parent order’s `deliveries[].id`)
`status`	String	Invoice status (e.g., approved)
`issued_at`	Timestamp	When the invoice was issued (ISO 8601); replication key for incremental sync
`xml`	String	Full NF-e XML content

Prices

Performance Impact: This stream requires an additional API request for each SKU in your catalog. If you have a large number of SKUs, selecting this stream will significantly increase extraction time. Only enable this stream if you need real-time pricing data per channel.

SKUs that have no pricing document in Magalu (the API answers 404 Document not found) are skipped with a warning instead of failing the sync.

Pricing information for each SKU per sales channel. This is a child stream of SKUs.Key Fields:

Field	Type	Description
`sku`	String	SKU identifier - unique code that identifies the product
`channel_id`	String	Channel identifier where this price is valid
`created_at`	Timestamp	When the price record was created
`updated_at`	Timestamp	When the price was last updated
`price`	Number	Current selling price of the product
`list_price`	Number	List price or original price before discounts
`currency`	String	Currency code (e.g., ‘BRL’)
`normalizer`	Number	Price normalizer value used for price calculations
`channel`	Object	Channel information (id)

Stocks

SKUs that have no inventory document in Magalu (the API answers 404 Document not found) are skipped with a warning instead of failing the sync.

Stock/inventory information for each SKU per sales channel. This is a child stream of SKUs.Key Fields:

Field	Type	Description
`sku`	String	SKU identifier - unique code that identifies the product
`channel_id`	String	Channel identifier where this stock is available
`created_at`	Timestamp	When the stock record was created
`updated_at`	Timestamp	When the stock was last updated
`quantity`	Number	Available quantity of the product in stock
`type`	String	Type of stock (e.g., ‘AVAILABLE’)

Data Model

The following diagram illustrates the relationships between the core data streams in Magalu. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.

Use Cases for Data Analysis

This guide outlines valuable business intelligence use cases when consolidating Magalu Marketplace data, along with ready-to-use SQL queries that you can run on Explorer.

1. Order Status Overview

Track the distribution of order statuses to understand your sales pipeline and identify potential bottlenecks. Business Value:

Monitor order fulfillment rates
Identify issues with specific order statuses
Track cancellation rates and reasons

SQL query

WITH order_stats AS (
   SELECT
      status,
      COUNT(*) AS order_count,
      SUM(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS total_revenue,
      AVG(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS avg_order_value
   FROM
      nekt_raw.magalu_orders
   WHERE
      DATE(created_at) >= CURRENT_DATE - INTERVAL '30' DAY
   GROUP BY
      status
),
total AS (
   SELECT SUM(order_count) AS total_orders FROM order_stats
)
SELECT
   os.status,
   os.order_count,
   ROUND(os.order_count * 100.0 / t.total_orders, 2) AS percentage,
   ROUND(os.total_revenue, 2) AS total_revenue,
   ROUND(os.avg_order_value, 2) AS avg_order_value
FROM
   order_stats os, total t
ORDER BY
   os.order_count DESC

WITH order_stats AS (
   SELECT
      status,
      COUNT(*) AS order_count,
      SUM(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS total_revenue,
      AVG(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS avg_order_value
   FROM
      `nekt_raw.magalu_orders`
   WHERE
      DATE(created_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
   GROUP BY
      status
),
total AS (
   SELECT SUM(order_count) AS total_orders FROM order_stats
)
SELECT
   os.status,
   os.order_count,
   ROUND(SAFE_DIVIDE(os.order_count * 100.0, t.total_orders), 2) AS percentage,
   ROUND(os.total_revenue, 2) AS total_revenue,
   ROUND(os.avg_order_value, 2) AS avg_order_value
FROM
   order_stats os, total t
ORDER BY
   os.order_count DESC

Sample Result

status	order_count	percentage	total_revenue	avg_order_value
finished	1,245	62.25	892,340.50	716.74
approved	456	22.80	312,450.00	685.20
new	189	9.45	145,230.00	768.41
cancelled	110	5.50	78,560.00	714.18

2. Top Selling Products

Identify your best-performing products based on sales volume and revenue. Business Value:

Understand which products drive the most revenue
Optimize inventory for high-demand items
Inform marketing and promotional strategies

SQL query

WITH item_sales AS (
   SELECT
      i.info.sku AS sku,
      i.info.name AS product_name,
      SUM(i.quantity) AS total_quantity,
      SUM(i.amounts.total / COALESCE(NULLIF(i.amounts.normalizer, 0), 1)) AS total_revenue,
      COUNT(DISTINCT o.id) AS order_count
   FROM
      nekt_raw.magalu_orders o
      CROSS JOIN UNNEST(o.deliveries) AS t(d)
      CROSS JOIN UNNEST(d.items) AS t2(i)
   WHERE
      o.status NOT IN ('cancelled')
      AND DATE(o.created_at) >= CURRENT_DATE - INTERVAL '30' DAY
   GROUP BY
      i.info.sku,
      i.info.name
)
SELECT
   sku,
   product_name,
   total_quantity,
   order_count,
   ROUND(total_revenue, 2) AS total_revenue,
   ROUND(total_revenue / NULLIF(total_quantity, 0), 2) AS avg_unit_price
FROM
   item_sales
ORDER BY
   total_revenue DESC
LIMIT 20

WITH item_sales AS (
   SELECT
      i.info.sku AS sku,
      i.info.name AS product_name,
      SUM(i.quantity) AS total_quantity,
      SUM(i.amounts.total / COALESCE(NULLIF(i.amounts.normalizer, 0), 1)) AS total_revenue,
      COUNT(DISTINCT o.id) AS order_count
   FROM
      `nekt_raw.magalu_orders` o,
      UNNEST(o.deliveries) AS d,
      UNNEST(d.items) AS i
   WHERE
      o.status NOT IN ('cancelled')
      AND DATE(o.created_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
   GROUP BY
      i.info.sku,
      i.info.name
)
SELECT
   sku,
   product_name,
   total_quantity,
   order_count,
   ROUND(total_revenue, 2) AS total_revenue,
   ROUND(SAFE_DIVIDE(total_revenue, total_quantity), 2) AS avg_unit_price
FROM
   item_sales
ORDER BY
   total_revenue DESC
LIMIT 20

Sample Result

sku	product_name	total_quantity	order_count	total_revenue	avg_unit_price
SKU-12345	Smart TV 55” 4K Ultra HD	234	230	467,532.00	1,998.00
SKU-67890	Smartphone Galaxy S24	189	185	341,811.00	1,809.00
SKU-24680	Notebook Gamer 16GB RAM	78	75	312,000.00	4,000.00
SKU-13579	Air Fryer Digital 5.5L	456	420	228,456.00	501.00
SKU-11223	Wireless Earbuds Pro	892	845	178,400.00	200.00

3. Delivery Performance Analysis

Monitor delivery times and shipping provider performance to optimize logistics, using the deliveries embedded in each order. Business Value:

Track delivery success rates
Identify slow shipping providers
Optimize fulfillment processes

SQL query

WITH delivery_metrics AS (
   SELECT
      d.shipping.provider.name AS provider_name,
      d.status AS delivery_status,
      COUNT(*) AS delivery_count,
      AVG(d.shipping.deadline.value) AS avg_deadline_days,
      SUM(CASE WHEN d.status = 'delivered' THEN 1 ELSE 0 END) AS delivered_count,
      SUM(CASE WHEN d.status = 'cancelled' THEN 1 ELSE 0 END) AS cancelled_count
   FROM
      nekt_raw.magalu_orders o
      CROSS JOIN UNNEST(o.deliveries) AS t(d)
   WHERE
      DATE(d.purchased_at) >= CURRENT_DATE - INTERVAL '30' DAY
   GROUP BY
      d.shipping.provider.name,
      d.status
)
SELECT
   provider_name,
   SUM(delivery_count) AS total_deliveries,
   SUM(delivered_count) AS total_delivered,
   SUM(cancelled_count) AS total_cancelled,
   ROUND(SUM(delivered_count) * 100.0 / NULLIF(SUM(delivery_count), 0), 2) AS delivery_success_rate,
   ROUND(AVG(avg_deadline_days), 1) AS avg_deadline_days
FROM
   delivery_metrics
GROUP BY
   provider_name
ORDER BY
   total_deliveries DESC

WITH delivery_metrics AS (
   SELECT
      d.shipping.provider.name AS provider_name,
      d.status AS delivery_status,
      COUNT(*) AS delivery_count,
      AVG(d.shipping.deadline.value) AS avg_deadline_days,
      SUM(CASE WHEN d.status = 'delivered' THEN 1 ELSE 0 END) AS delivered_count,
      SUM(CASE WHEN d.status = 'cancelled' THEN 1 ELSE 0 END) AS cancelled_count
   FROM
      `nekt_raw.magalu_orders` o,
      UNNEST(o.deliveries) AS d
   WHERE
      DATE(d.purchased_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
   GROUP BY
      d.shipping.provider.name,
      d.status
)
SELECT
   provider_name,
   SUM(delivery_count) AS total_deliveries,
   SUM(delivered_count) AS total_delivered,
   SUM(cancelled_count) AS total_cancelled,
   ROUND(SAFE_DIVIDE(SUM(delivered_count) * 100.0, SUM(delivery_count)), 2) AS delivery_success_rate,
   ROUND(AVG(avg_deadline_days), 1) AS avg_deadline_days
FROM
   delivery_metrics
GROUP BY
   provider_name
ORDER BY
   total_deliveries DESC

Sample Result

provider_name	total_deliveries	total_delivered	total_cancelled	delivery_success_rate	avg_deadline_days
Magalu Entregas	1,456	1,389	42	95.40	3.2
Correios	892	834	35	93.50	5.8
Jadlog	456	421	18	92.32	4.5
Total Express	234	218	8	93.16	4.1

Implementation Notes

Data normalization

Magalu uses a normalizer pattern for monetary values. To get the actual value, divide by the normalizer:

-- Example: Get actual order total
SELECT
    amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1) AS actual_total
FROM orders

Common normalizers:

100 for values stored as cents
1 for values already in the base currency unit

Order status flow

Orders in Magalu typically follow this status flow:

new - Order just placed
approved - Payment confirmed
invoiced - Invoice generated
shipped - Order dispatched
delivered - Order delivered to customer
finished - Order completed

Orders can also be:

cancelled - Order was cancelled
returned - Customer returned the order

Brazilian context

This connector is designed for the Brazilian marketplace:

Currency: Values are in BRL (Brazilian Real)
Documents: Customer documents are CPF (individuals) or CNPJ (companies)
Addresses: Brazilian address format with CEP (postal code), state abbreviations
Shipping: Includes Brazilian carriers like Correios, Jadlog, and Magalu’s own logistics

Incremental sync and replication keys

Orders: Incremental when configured, using updated_at as the replication key. API requests are sorted by updated_at and filtered with updated_at__gte from the bookmark or Start Date.
Deliveries invoices: Incremental bookmark on issued_at. The invoices endpoint itself is not date-filtered; the set of deliveries to query comes from the orders returned by the incremental Orders sync.
SKUs, Prices, Stocks: Full table sync in the tap (no replication key on those streams). Start Date does not apply to them.

Child streams and API volume

Prices and Stocks are children of SKUs: one extra API request per SKU per stream when enabled.
Deliveries invoices is a child of Orders: one extra API request per delivery listed in each synced order (deliveries with status cancelled are skipped). The API’s standalone /deliveries endpoint is not used because of its pagination limits, so delivery data itself lives in the deliveries array of Orders.

Extraction time scales with SKU count (prices/stocks) and delivery count (in invoices). Prefer off-peak schedules for large catalogs, and enable child streams only when you need that granularity.

Missing documents in child streams

Prices and Stocks: if a SKU listed in your catalog has no pricing or stock document on the seller side, Magalu answers 404 Document not found. The connector skips that SKU (a warning is logged once per stream, naming the first affected SKU) and continues the extraction normally.
Deliveries invoices: a 403 or 404 for a delivery means no invoice is available for it; the delivery is skipped with a warning and the run continues.

Catalog size limits and pagination

The Magalu API enforces a strict offset limit of 20,000 records on the SKUs listing. To ensure complete extraction of large catalogs, the connector automatically escalates through multiple pagination strategies (cursor-based, keyset re-anchoring, and bidirectional per-status sweeps) to bypass this limit. If your catalog has an extremely high volume of SKUs sharing the exact same status (over ~40,000 items), the API’s hard limits might still truncate the extraction for that specific status. In this rare scenario, the connector logs a warning indicating how many SKUs were synced and skips the unreachable ones. Note that any SKUs truncated this way will also be missing from the child Prices and Stocks streams.

Nested data structures

Magalu payloads are deeply nested. When querying:

Use UNNEST (or CROSS JOIN UNNEST in Athena) to flatten arrays
Access nested objects using dot notation (e.g., customer.name)
Handle NULL values in nested fields with COALESCE

Example for accessing delivery items from nested orders:

-- AWS Athena
SELECT d.items
FROM orders o
CROSS JOIN UNNEST(o.deliveries) AS t(d)

-- GCP BigQuery
SELECT i.*
FROM orders o, UNNEST(o.deliveries) AS d, UNNEST(d.items) AS i

Skills for agents

Download Magalu skills file

Magalu connector documentation as plain markdown, for use in AI agent contexts.

Documentation

Get started

Context

Activate

Workspace

Resources

Magalu as a data source

Configuring Magalu as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Use Cases for Data Analysis

1. Order Status Overview

2. Top Selling Products

3. Delivery Performance Analysis

Implementation Notes

Data normalization

Order status flow

Brazilian context

Incremental sync and replication keys

Child streams and API volume

Missing documents in child streams

Nested data structures

Skills for agents

Download Magalu skills file

​Configuring Magalu as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Data Model

​Use Cases for Data Analysis

​1. Order Status Overview

​2. Top Selling Products

​3. Delivery Performance Analysis

​Implementation Notes

​Data normalization

​Order status flow

​Brazilian context

​Incremental sync and replication keys

​Child streams and API volume

​Missing documents in child streams

​Catalog size limits and pagination

​Nested data structures

​Skills for agents

Download Magalu skills file

Configuring Magalu as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Use Cases for Data Analysis

1. Order Status Overview

2. Top Selling Products

3. Delivery Performance Analysis

Implementation Notes

Data normalization

Order status flow

Brazilian context

Incremental sync and replication keys

Child streams and API volume

Missing documents in child streams

Catalog size limits and pagination

Nested data structures

Skills for agents