
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. The following configurations are available:- Start Date: (Optional) The earliest date from which records will be synced. If not provided, all historical data will be extracted.
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.
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.
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.Streams and Fields
Below you’ll find all available data streams from Magalu and their corresponding fields:SKUs
SKUs
Product catalog stream containing all SKUs (Stock Keeping Units) from your Magalu seller portfolio.Key Fields:
sku- SKU identifier - unique code that identifies the producttitle- Product title or namedescription- Detailed product descriptionbrand- Brand name of the productstatus- Current status (e.g., ‘active’, ‘inactive’, ‘pending’, ‘rejected’)active- Whether the SKU is currently active and available for salecondition- Product condition (e.g., ‘new’, ‘used’, ‘refurbished’)type- Product type classification
created_at- When the SKU was createdupdated_at- When the SKU was last updated (replication key)creator- User who created the SKUupdater- User who last updated the SKU
attributes- Array of product attributes (name/value pairs for characteristics like Color, Size)datasheet- Array of technical specifications (name/value pairs like Voltage, Power, Warranty)extra_data- Array of additional custom data fields
identifiers- Array of product identifiers (EAN, UPC, ISBN, GTIN)has_ean- Whether the product has an EAN barcodegroup- Product group information linking related SKUs/variantsid- Product group identifier
categories- Array of category classificationscategories- List of category namessub_categories- List of subcategory namesproduct_type- Type of product within the categorychannel- Channel information (id)
channels- Array of sales channels where product is availableid- Channel identifier
url_marketplace- Array of marketplace URLs by channel
dimensions- Array of dimension setsname- Dimension set name (e.g., ‘product’, ‘package’)height- Height (value, unit)length- Length (value, unit)width- Width (value, unit)weight- Weight (value, unit)
images- Array of product images (reference, type)videos- Array of product videos (reference, type)podcasts- Array of related podcasts (reference, type)
fulfillment- Whether the product uses fulfillment servicesperishable- Whether the product is perishable
Orders
Orders
Orders stream containing all marketplace orders with customer, payment, and delivery information.Key Fields:
id- Unique identifier for the ordercode- Order code in the platformstatus- Order status (e.g., ‘new’, ‘approved’, ‘cancelled’, ‘finished’)
created_at- When the order was createdupdated_at- When the order was last updated (replication key)approved_at- When the order was approvedpurchased_at- When the order was purchased
channel- Sales channel informationid- Channel identifierextras- Additional channel info (alias)marketplace- Marketplace info (document)
customer- Customer detailsname- Customer nameemail- Customer emaildocument_number- Customer document (CPF/CNPJ)customer_type- Type (cnpj/cpf)birth_date- Customer birth datephones- Array of phone numbers (area_code, country_code, number, type)
amounts- Order totalscurrency- Currency codenormalizer- Price normalizertotal- Total amountcommission- Commission amounts (currency, normalizer, total, type)discount- Discount amounts (currency, normalizer, total)freight- Freight amounts (currency, normalizer, total)tax- Tax amounts (currency, normalizer, total)
foreign_amounts- Foreign currency amountscurrency- Foreign currency codenormalizer- Price normalizertotal- Total in foreign currencyexchange_rate- Exchange rate informationcurrency- Currency codeexternal_id- External identifiernormalizer- Exchange rate normalizervalue- Exchange rate value
deliveries- Array of order deliveriesid- Delivery identifiercode- Delivery codestatus- Delivery statuspurchased_at- Purchase timestampseller- Seller info (id, name)amounts- Delivery amounts (total, commission, discount, freight, tax)items- Array of items in deliveryquantity- Item quantitysequencial- Item sequence numbermeasure_unit- Unit of measureinfo- Item information (id, sku, name, images, attributes, extras)amounts- Item amounts (currency, normalizer, total, commission, discount, freight, taxes)unit_price- Unit price (currency, normalizer, value)
shipping- Shipping informationpickup_details- Pickup address and store infodrop_details- Drop-off address and store inforecipient- Recipient info (name, document, address)handling_time- Handling time (value, precision, workday, limit_date)deadline- Delivery deadline (value, precision, workday, limit_date)provider- Shipping provider (id, name, description, extras)tracking_url- Tracking URL for the delivery (string)tracking- Tracking information object (url)shipped_at- When shippeddelivered_at- When deliveredcancelled_at- When cancelled
payments- Array of payment methodsamount- Payment amountcurrency- Currency codemethod- Payment methodmethod_brand- Payment method branddescription- Payment descriptioninstallments- Number of installmentsnormalizer- Price normalizerintegration_type- Integration typeauthorization_code- Authorization codegateway- Gateway info (document)extras- Additional payment data
Deliveries
Deliveries
Deliveries stream providing detailed shipping and fulfillment information for orders.Key Fields:
id- Unique identifier for the deliverycode- Delivery codestatus- Delivery statuspurchased_at- When the order was purchased
order- Associated order informationid- Order identifiercode- Order codechannel- Channel info (id, extras, marketplace)
seller- Seller detailsid- Seller identifiername- Seller name
amounts- Delivery totalscurrency- Currency codenormalizer- Price normalizertotal- Total amountfreight- Freight amountsdiscount- Discount amountstax- Tax amounts
items- Array of items in the deliverysequencial- Item sequence numberquantity- Item quantitymeasure_unit- Unit of measureinfo- Item informationsku- SKU identifierid- Item IDname- Item nameimages- Array of image URLsattributes- Item attributesextras- Additional item data
unit_price- Unit price (currency, normalizer, value)amounts- Item amounts (currency, normalizer, total, freight, taxes)
shipping- Shipping detailstracking- Tracking info (url)recipient- Recipient detailscustomer_type- Customer type (cpf/cnpj)document_number- Document numbername- Recipient nameaddress- Full address (zipcode, street, number, district, city, state, country, complement, reference)
drop_details- Drop-off locationstore- Store info (document)address- Drop address
handling_time- Handling time detailsvalue- Time valueprecision- Time precisionworkday- Is workday-basedlimit_date- Limit date
deadline- Delivery deadlinevalue- Deadline valueprecision- Precision (e.g., ‘days’)workday- Is workday-basedlimit_date- Limit date
provider- Shipping providerid- Provider IDname- Provider namedescription- Provider descriptionextras- Additional info (is_mle, is_fulfillment, shipping_type, shipping_name, tags)
Prices
Prices
Pricing information for each SKU per sales channel. This is a child stream of SKUs.Key Fields:
sku- SKU identifier - unique code that identifies the productchannel_id- Channel identifier where this price is valid
created_at- When the price record was createdupdated_at- When the price was last updated
price- Current selling price of the productlist_price- List price or original price before discountscurrency- Currency code (e.g., ‘BRL’)normalizer- Price normalizer value used for price calculations
channel- Channel informationid- Channel identifier
Stocks
Stocks
Stock/inventory information for each SKU per sales channel. This is a child stream of SKUs.Key Fields:
sku- SKU identifier - unique code that identifies the productchannel_id- Channel identifier where this stock is available
created_at- When the stock record was createdupdated_at- When the stock was last updated
quantity- Available quantity of the product in stocktype- 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
SQL query
- AWS
- GCP
Sample Result
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
SQL query
- AWS
- GCP
Sample Result
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. Business Value:- Track delivery success rates
- Identify slow shipping providers
- Optimize fulfillment processes
SQL query
SQL query
- AWS
- GCP
Sample Result
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
Data Normalization
Magalu uses a normalizer pattern for monetary values. To get the actual value, divide by the normalizer:Common normalizers:
100for values stored as cents1for values already in the base currency unit
Order Status Flow
Order Status Flow
Orders in Magalu typically follow this status flow:
new- Order just placedapproved- Payment confirmedinvoiced- Invoice generatedshipped- Order dispatcheddelivered- Order delivered to customerfinished- Order completed
cancelled- Order was cancelledreturned- Customer returned the order
Brazilian Context
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
Incremental Sync
The connector supports incremental sync for:
- Orders: Uses
updated_atas the replication key - SKUs: Uses
updated_atas the replication key - Deliveries: Full table sync (no replication key)
- Prices: Full table sync (child of SKUs - one request per SKU)
- Stocks: Full table sync (child of SKUs - one request per SKU)
Child Streams Performance
Child Streams Performance
The Prices and Stocks streams are child streams of SKUs. This means:
- For each SKU in your catalog, an additional API request is made to fetch price/stock data
- If you have 1,000 SKUs, selecting both streams will result in 2,000+ additional API calls
- Extraction time scales linearly with the number of SKUs
- Only enable these streams if you need channel-specific pricing or inventory data
- Consider scheduling extractions during off-peak hours for large catalogs
- If you have thousands of SKUs, expect extraction times to increase significantly
Nested Data Structures
Nested Data Structures
Magalu data contains deeply nested structures. When querying:
- Use
UNNEST(orCROSS JOIN UNNESTin Athena) to flatten arrays - Access nested objects using dot notation (e.g.,
customer.name) - Handle NULL values in nested fields with
COALESCE