Data Dictionary
Order Structure
| Field | Description |
|---|---|
| order_id | Unique order identifier in the system |
| origin | Order origin (Physical Store, Marketplace, Ecommerce) |
| channel | E-commerce sales channels include own virtual store, sales via Instagram Shopping, Facebook Shop, WhatsApp, and own apps. In marketplaces, the main examples are Mercado Livre, Amazon, Magalu, Shopee, Americanas, Via Varejo, Carrefour, and OLX. In physical retail, channels range from street stores and shopping malls to kiosks, pop-up stores, fairs, events, and franchises. |
| status | Current status of the order (open, paid, closed, cancelled) |
| total_value | Total order value (already includes discounts and shipping) |
| discount_value | Total discount value applied to the order |
| created_at | Date when the order was placed, in the ISO format YYYY-MM-DDTHH:mm:ss and on the local date and time.IMPORTANT: You MUST provide the local date and time that the order was placed, with the required pattern( YYYY-MM-DDTHH:mm:ss). This way the API can ensure period filtering and maintain date and time standardization across all your orders.Example: order placed in Brasília(UTC-03:00) at 2025-07-01T15:30:45, this is the local date and time value needed |
| customer_email | Email of the customer who placed the order |
| customer_unique_identifier | Unique customer identifier in the database |
| customer_document | Customer’s identification document number |
| customer_fullname | Customer's full name |
| customer_phone | Customer's phone number |
| customer_destination_address_city | Delivery address city |
| customer_destination_address_state | Delivery address state |
| customer_destination_address_country | Delivery address country |
| coupon | Promotional coupon used, if any |
| invoice_number | Issued invoice number |
| shipping_method | Selected shipping method (e.g.: PAC, Sedex, In-store Pickup) |
| shipping_price | Total shipping cost |
| source_platform | System where the data was registered (ERPs, E-commerce platforms, and Marketplaces) |
| shipping_type | Shipping type (paid, free) |
| shipping_price_paid_by_customer | Shipping amount paid by the customer. If the shipping was R$10.00, the field value would be 10. If the shipping was paid by the company, the field value would be 0. |
Possible Order Statuses and Their Meanings
| Status | Description |
|---|---|
| open | Order created, not yet paid or processed |
| paid | Payment made. The order may be awaiting other steps, but has already been paid for |
| closed | Order completed, delivered, or concluded as per business flow |
| cancelled | Order canceled at any stage, will not be processed or delivered |
Payment Structure
| Field | Description |
|---|---|
| order_id | Unique order identifier |
| payment_id | Unique payment identifier |
| payment_method | Payment method used (e.g.: Credit Card, Pix) |
| forms_of_payment | Description of payment form (e.g.: Visa, Mastercard) |
| payment_installment | Number of installments |
| payment_value | Transacted payment amount and the amount paid on the order |
Item Structure
| Field | Description |
|---|---|
| order_id | Unique order identifier |
| product_id | Unique product identifier |
| product_sku_id | Unique SKU identifier of the product |
| product_name | Product name |
| product_sku_name | SKU name (e.g.: color, size) |
| quantity_sold | Quantity sold of the item |
| unit_value | Unit price of the product |
| total_value | Total value of the item (with quantity and discounts) |
| discount_value | Discount value applied to the item |
| shipping_price | Proportional shipping cost for this item |
| item_value_without_shipping_price | Item value excluding shipping |
| shipping_price_paid_by_customer | Shipping cost paid by the customer for this item |
| store_id | The store_id field is generic and serves to identify both the location responsible for the sale and for the stock or pickup of the item. For online purchases, it can be used to inform the ID of the distribution center (DC) responsible for shipping the order. For physical store or franchise sales, this field should indicate the specific unit where the product was sold or will be picked up by the customer. |
| store_name | Name of the store responsible for selling the item. Can be the name of the distribution center (DC), physical unit, or franchise, depending on the channel through which the sale occurred or where the pickup will happen. |
| seller_id | Seller's ID |
| seller_name | Seller's name |
Product Structure
| Field | Description |
|---|---|
| product_sku_id | Unique product SKU identifier, used to specify exactly the variation of the item sold (such as color, size, or model). Essential for stock control and sales tracking of that specific SKU |
| product_sku_name | SKU name (e.g.: color, size) |
| product_id | Unique main product identifier, regardless of variations. This field is used to relate all variations (SKUs) to the same base product, facilitating aggregate analyses and portfolio management |
| product_name | Product name |
| product_image_url | Product image URL – Must be a public and accessible URL, allowing any system or user to view the image without authentication |
| product_page_path | Product page path on the site |
| product_department_id | Product department ID |
| product_department_name | Department name |
| product_category_id | Category ID |
| product_category_name | Category name |
| product_sub_category_id | Subcategory ID |
| product_sub_category_name | Subcategory name |
| product_price | Product price |
| product_cost | Product cost |
| product_sale_price | Promotional or final sale price |
| product_brand | Product brand |
| is_active | Indicates whether the product is currently active(true) or inactive(false) |
Stock Structure
| Field | Description |
|---|---|
| product_id | Unique main product identifier, used to group all variations (SKUs) of the same base product. Allows consolidated analysis and control, regardless of color, size, or model |
| product_sku_id | Unique SKU identifier of the product, used to differentiate each specific variation (such as color, size, or model). Essential for stock control and detailed traceability of each item |
| product_stock_quantity | Available stock quantity |
| product_stock_reserved_quantity | Quantity of items reserved in stock for purchases already made, but not yet actually deducted from stock (for example, orders waiting for invoicing, shipping, or customer pickup) |
| store_id | Store, distribution center, or unit ID where the product's stock is physically located. Can be used to identify stocks in DCs, physical stores, franchises, or any storage or pickup point |