Skip to main content
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 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, 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.

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

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