> ## 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.
# Tray
> Bring data from your Tray Commerce store to your Lakehouse.
Tray Commerce (also known as commercesuite) is a Brazilian e-commerce platform that powers online stores, from catalog and inventory management to orders, customers, and marketplace integrations. This connector uses the store's Tray Web API to extract your products, product variants, brands, categories, orders, order statuses, sold products, customers, and customer addresses.
## Configuring Tray 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 Tray option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
Tray works as a store-authorized application. Before configuring the source, authorize the Tray application on your store: the store owner installs and authorizes the app (its `consumer_key` and `consumer_secret` are issued by Tray's partnership team), and the store admin then displays an authorization `code`. Nekt uses that authorization code to mint and automatically refresh its access tokens, so there is no recurring manual token step.
Keep the `consumer_key`, `consumer_secret`, and `code` from the same authorized application. The authorization `code` is consumed to generate the first access token, after which Nekt refreshes tokens automatically.
The following configurations are available:
* **API Address**: The base URL of your store's Tray Web API, for example `https://yourstore.commercesuite.com.br/web_api`.
* **Consumer Key**: The `consumer_key` of the authorized Tray application, issued by Tray's partnership team.
* **Consumer Secret**: The `consumer_secret` of the authorized Tray application, issued by Tray's partnership team.
* **Code**: The authorization code shown in your store admin after authorizing the Tray application.
* **Start Date**: (Optional) The earliest date from which records will be synced. Applies to the incremental streams (products, product variants, orders, and customers).
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](https://docs.nekt.com/get-started/core-concepts/triggers), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](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.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# 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.
| Stream | Slug | Description |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Products | `products` | Product catalog with pricing, stock, dimensions, SEO, and nested images/variants. Incremental on `modified`. |
| Product Variants | `product_variants` | Variants (SKUs) of products, with per-variant pricing, stock, and attribute axes. Incremental on `modified`. |
| Brands | `brands` | Brands registered in your store. |
| Categories | `categories` | Category tree used to organize the product catalog. |
| Orders | `orders` | Orders placed in your store, including status, financial totals, payment, and shipping information. Incremental on `modified`. |
| Order Statuses | `order_statuses` | Order status definitions available in your store. |
| Sold Products | `sold_products` | Line items sold across orders, linking orders to the products and variants purchased. |
| Customers | `customers` | Customers with contact, document, address, and commercial information. Incremental on `modified`. |
| Customer Addresses | `customer_addresses` | Addresses associated with your customers. |
# Streams and Fields
Below you'll find all available data streams from Tray and their corresponding fields.
The Tray Web API returns all field values as strings, including numeric, boolean, and date values. Cast them to the appropriate types in your queries when needed. Nested objects and arrays are delivered as JSON-encoded strings.
The following streams sync incrementally using the `modified` timestamp as the replication key: **Products**, **Product Variants**, **Orders**, and **Customers**. All other streams are full-table.
Product catalog stream containing every product in your store. Incremental sync using `modified` as the replication key.
**Identifiers:**
* `id` - Unique product code (primary key)
* `reference` - Internal product reference/SKU
* `ean` - EAN barcode of the product
* `ncm` - NCM fiscal classification code
* `model` - Product model
* `slug` - Final segment of the product's URL
**Descriptive:**
* `name` - Product name
* `title` - SEO/product title
* `description` - Full product description
* `description_small` - Short product description
* `brand` - Brand name
* `brand_id` - Brand code
* `category_id` - Main category code
* `category_name` - Main category name (detail only)
**Pricing:**
* `price` - Sale price
* `cost_price` - Cost price
* `dollar_cost_price` - Cost price in US dollars
* `promotional_price` - Promotional price
* `current_price` - Effective current price
* `percentage_discount` - Discount percentage
* `start_promotion` - Promotion start date
* `end_promotion` - Promotion end date
* `ipi` - IPI tax rate
* `ipi_value` - IPI tax amount
* `payment_option` - Payment option text
* `payment_option_html` - Payment option HTML
* `payment_option_details` - Installment/payment detail objects (JSON-encoded)
**Dimensions & Stock:**
* `weight` - Weight in grams
* `length` - Length dimension
* `width` - Width dimension
* `height` - Height dimension
* `cubic_weight` - Cubic (dimensional) weight
* `stock` - Available stock quantity
* `minimum_stock` - Minimum stock level
* `minimum_stock_alert` - Minimum-stock alert flag
**Availability & Flags:**
* `available` - Availability flag (0/1)
* `available_in_store` - Store visibility (inverted enum: 0=available, 1=unavailable)
* `availability` - Availability text
* `availability_days` - Days until availability
* `available_for_purchase` - Purchasable flag
* `hot` - Featured product flag (0/1)
* `release` - New-release flag (0/1)
* `release_date` - Launch date
* `additional_button` - Additional-button flag
* `has_variation` - Whether the product has variants (0/1)
* `has_acceptance_terms` - Whether acceptance terms apply (0/1)
* `has_buy_together` - Whether buy-together applies (0/1)
* `is_kit` - Whether the product is a kit (0/1)
* `virtual_product` - Whether the product is virtual (0/1)
* `upon_request` - Sold-on-request flag
* `free_shipping` - Free-shipping flag (0/1)
* `promotion_id` - Promotion code applied
**Content & SEO:**
* `additional_message` - Additional message shown on the product
* `warranty` - Warranty text
* `warranty_days` - Warranty duration in days
* `rating` - Average rating
* `count_rating` - Number of ratings
* `quantity_sold` - Total units sold
* `included_items` - Items included with the product
* `acceptance_term_option` - Acceptance-term option
* `acceptance_term` - Acceptance term
* `shortcut` - URL shortcut
* `video` - Product video URL
* `metatag` - SEO meta tags (type, content), JSON-encoded
* `url` - Product URLs (http, https), JSON-encoded
**Relationships & Nested (JSON-encoded):**
* `related_products` - Related product IDs
* `related_categories` - Additional category IDs
* `all_categories` - All associated category IDs
* `Properties` - Product characteristics (name: \[values])
* `ProductImage` - Inline product images (http, https, thumbs)
* `Variant` - Inline variant ID stubs (`[{id}]`); full data in the product\_variants stream
* `ProductSettings` - Product settings (stock-out behavior, lead times)
* `AdditionalInfos` - Additional product info fields and their options
**Timestamps:**
* `activation_date` - Activation date
* `deactivation_date` - Deactivation date
* `created` - Creation timestamp
* `modified` - Last-modification timestamp, used as the incremental replication key
Variants (SKUs) of products, including per-variant pricing, stock, and attribute axes. Incremental sync using `modified` as the replication key.
**Key Fields:**
* `id` - Unique variant code (primary key)
* `product_id` - Parent product code
* `reference` - Variant internal reference/SKU
* `ean` - EAN barcode of the variant
* `order` - Display order of the variant
* `available` - Variant availability flag (0/1)
* `quantity_sold` - Units sold of this variant
**Pricing:**
* `price` - Variant sale price
* `cost_price` - Variant cost price
* `promotional_price` - Variant promotional price
* `start_promotion` - Variant promotion start date
* `end_promotion` - Variant promotion end date
* `payment_option` - Variant payment option text
* `payment_option_details` - Installment/payment detail objects (JSON-encoded)
**Dimensions & Stock:**
* `weight` - Variant weight in grams
* `cubic_weight` - Variant cubic weight
* `length` - Variant length dimension
* `width` - Variant width dimension
* `height` - Variant height dimension
* `stock` - Variant stock quantity
* `minimum_stock` - Variant minimum stock level
**Attributes:**
* `color_id_1` - First color attribute ID
* `color_id_2` - Second color attribute ID
* `Sku` - Attribute axes of the variant (type, value, image), JSON-encoded
* `VariationSettings` - Variant settings (stock-out behavior, lead times), JSON-encoded
**Media:**
* `illustrative_image` - Variant illustrative image (http, https), JSON-encoded
* `VariantImage` - Variant images (http, https, thumbs), JSON-encoded
**Timestamps:**
* `modified` - Last-modification timestamp, used as the incremental replication key
Brands registered in your store. Full-table sync.
**Key Fields:**
* `id` - Unique brand code (primary key)
* `brand` - Brand name
* `slug` - Final segment of the brand's URL
Category tree used to organize the product catalog. Full-table sync.
**Key Fields:**
* `id` - Unique category code (primary key)
* `parent_id` - Parent category code (0 for root)
* `name` - Category name
* `slug` - Final segment of the category's URL
* `order` - Display order of the category
* `title` - SEO/category title
* `small_description` - Short category description
* `has_acceptance_term` - Whether an acceptance term applies (0/1)
* `acceptance_term` - Acceptance term text
**Nested (JSON-encoded):**
* `link` - Category URLs (http, https)
* `Images` - Category images (http, https)
* `metatag` - SEO meta tags (type, content)
Orders placed in your store, including status, financial totals, payment, and shipping information. Incremental sync using `modified` as the replication key.
**Key Fields:**
* `id` - Unique order code (primary key)
* `status` - Current order status label
* `status_id` - Current order status code
* `date` - Order date (YYYY-MM-DD)
* `hour` - Order time of day
* `customer_id` - Customer code that placed the order
* `total` - Order grand total
* `partial_total` - Subtotal before shipping/discounts
* `taxes` - Total taxes applied
* `discount` - Total discount applied
* `interest` - Interest amount charged
* `cost` - Order cost
**Delivery & Shipping:**
* `delivery_date` - Delivery date
* `delivery_time` - Estimated delivery time
* `estimated_delivery_date` - Estimated delivery date
* `shipment` - Freight/shipping method name
* `shipment_value` - Shipping cost
* `shipment_date` - Shipment date
* `delivered` - Delivered flag
* `delivered_status` - Delivery status
* `shipping_cancelled` - Shipping-cancelled flag
* `sending_code` - Shipping tracking code
* `sending_date` - Date the order was sent
* `is_traceable` - Whether the shipment is traceable
* `tracking_url` - Shipment tracking URL
* `shipment_integrator` - Shipping integrator name
* `has_shipment` - Whether the order has a shipment
**Payment:**
* `payment_method_id` - Payment method code
* `payment_method` - Payment method name
* `payment_method_type` - Payment method type
* `payment_method_rate` - Payment method rate/fee
* `payment_form` - Payment form label
* `installment` - Number of installments
* `value_1` - Auxiliary payment value
* `payment_date` - Payment confirmation date
* `has_payment` - Whether the order has a payment
* `has_invoice` - Whether the order has an invoice
**Channel & Origin:**
* `point_sale` - Point-of-sale channel
* `partner_id` - Partner/marketplace code
* `partner_name` - Partner/marketplace name
* `external_code` - External/marketplace order code
* `app_id` - Originating application code
* `store_segment` - Store segment
* `client_ip` - Customer IP address
* `session_id` - Checkout session identifier
* `access_code` - Order access code
* `dc_id` - Distribution center code
* `dc_order_origin` - Distribution-center order origin
**Discounts & Commission:**
* `discount_coupon` - Discount coupon code used
* `coupon` - Coupon detail (code, discount), JSON-encoded
* `progressive_discount` - Progressive discount detail, JSON-encoded
* `shipping_progressive_discount` - Progressive shipping discount detail, JSON-encoded
* `cart_additional_values_discount` - Cart-level additional discount value
* `cart_additional_values_increase` - Cart-level additional increase value
* `total_comission` - Total commission
* `total_comission_user` - Total commission for the user
**Notes & Flags:**
* `store_note` - Internal store note
* `customer_note` - Note left by the customer
* `printed` - Whether the order was printed
* `id_quotation` - Related quotation code
* `billing_address` - Billing address text
**Nested objects (JSON-encoded):**
* `OrderStatus` - Inline order-status object
* `ProductsSold` - Order items; stub `[{id}]` in the list, full detail via /complete
* `Payment` - Order payment objects
* `OrderInvoice` - Order invoice objects
* `Customer` - Embedded customer object (in /complete)
* `CustomerAddress` - Customer address stub
* `OrderTransactions` - Payment transaction URLs
* `MlOrder` - Mercado Livre order metadata
* `MarketplaceOrder` - Marketplace order metadata
* `PickupLocation` - Pickup-location details
* `DistributionCenter` - Distribution-center package detail
* `ShippingLabel` - Shipping label (application, url)
* `payments_notification` - Payment notification object
**Timestamps:**
* `modified` - Last-modification timestamp, used as the incremental replication key
Order status definitions available in your store. Full-table sync.
**Key Fields:**
* `id` - Unique status code (primary key)
* `status` - Status name
* `show_backoffice` - Whether the status shows in the backoffice (0/1)
* `default` - Whether it is a platform default status (0=default, 1=additional)
Line items sold across orders, linking orders to the products and variants purchased. Full-table sync.
**Key Fields:**
* `id` - Unique sold-item code (primary key)
* `product_id` - Product code sold
* `order_id` - Order code the item belongs to
* `variant_id` - Variant code sold, if any
* `name` - Product name at time of sale
* `price` - Sold unit price
* `original_price` - Original unit price before discounts
* `quantity` - Quantity sold
* `model` - Product model
* `reference` - Product reference/SKU
* `additional_information` - Additional item information
Customers registered in your store, with contact, document, address, and commercial information. Incremental sync using `modified` as the replication key.
**Key Fields:**
* `id` - Unique customer code (primary key)
* `name` - Customer full name
* `email` - Email address
* `nickname` - Customer nickname/username
* `token` - Unique customer token
* `type` - Customer type (0=individual, 1=company)
* `gender` - Gender (0=male, 1=female)
* `birth_date` - Date of birth
**Documents:**
* `rg` - Customer RG (Brazilian ID) number
* `cpf` - Customer CPF (individual taxpayer ID)
* `cnpj` - Company CNPJ (business taxpayer ID)
* `company_name` - Company (legal) name
* `state_inscription` - State inscription number
**Contact:**
* `phone` - Landline phone number
* `cellphone` - Mobile phone number
**Primary Address:**
* `address` - Primary street address
* `number` - Primary address number
* `complement` - Primary address complement
* `neighborhood` - Primary address neighborhood
* `city` - Primary address city
* `state` - Primary address state (UF)
* `zip_code` - Primary postal code (CEP)
* `country` - Primary address country
**Commercial:**
* `total_orders` - Total number of orders placed
* `reseller` - Whether the customer is a reseller
* `discount` - Default discount for the customer
* `blocked` - Whether the customer is blocked (0/1)
* `credit_limit` - Customer credit limit
* `indicator_id` - Referrer/indicator code
* `profile_customer_id` - Customer profile (price list) code
* `observation` - Internal observation about the customer
* `newsletter` - Newsletter subscription flag (0/1)
**Activity Dates:**
* `last_sending_newsletter` - Last newsletter-send date
* `last_purchase` - Last purchase date
* `last_visit` - Last visit date
* `last_modification` - Last modification date
* `created` - Creation timestamp
* `registration_date` - Registration date
* `modified` - Last-modification timestamp, used as the incremental replication key
**Nested (JSON-encoded):**
* `CustomerAddress` - Customer address ID stubs (`[{id}]`); full data in the customer\_addresses stream
Addresses associated with your customers. Full-table sync.
**Key Fields:**
* `id` - Unique address code (primary key)
* `customer_id` - Customer code the address belongs to
* `address` - Street address (logradouro)
* `number` - Address number
* `complement` - Address complement
* `neighborhood` - Neighborhood
* `city` - City
* `state` - State (UF)
* `zip_code` - Postal code (CEP)
* `country` - Country
* `type` - Address type (0=billing, 1=delivery)
* `active` - Whether the address is active (0/1)
* `description` - Address description/label
* `recipient` - Recipient name
* `type_delivery` - Delivery type
* `not_list` - Whether the address is excluded from listings
# Data Model
The following diagram illustrates the relationships between the core data streams in Tray. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.
```mermaid theme={null}
graph TD;
subgraph "Product Catalog"
Products("Products");
ProductVariants("Product Variants");
Brands("Brands");
Categories("Categories");
end
subgraph "Sales Data"
Orders("Orders");
OrderStatuses("Order Statuses");
SoldProducts("Sold Products");
end
subgraph "Customer Data"
Customers("Customers");
CustomerAddresses("Customer Addresses");
end
ProductVariants -- "product_id" --> Products;
Products -- "brand_id" --> Brands;
Products -- "category_id" --> Categories;
Categories -- "parent_id" --> Categories;
Orders -- "customer_id" --> Customers;
Orders -- "status_id" --> OrderStatuses;
SoldProducts -- "order_id" --> Orders;
SoldProducts -- "product_id" --> Products;
SoldProducts -- "variant_id" --> ProductVariants;
CustomerAddresses -- "customer_id" --> Customers;
```