> ## 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.
# Nuvemshop as a data source
> Bring data from Nuvemshop (Tiendanube) to Nekt.
Nuvemshop (Tiendanube in Spanish-speaking countries) is Latin America's leading e-commerce platform, letting merchants build online stores, manage catalogs and inventory, process orders and payments, and sell across channels. Its REST API exposes the store's products, orders, customers, coupons and more.
## Configuring Nuvemshop 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 Nuvemshop option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
Nuvemshop uses OAuth 2 with the *authorization code* flow. An app installed on your store receives an **access token** that never expires (it is only revoked when the app is uninstalled or a new token is issued). Follow [Nuvemshop's authentication guide](https://dev.nuvemshop.com.br/en/docs/applications/authentication) to install your app and obtain the token.
The following configurations are available:
* **Access Token**: The `access_token` returned by Nuvemshop's token endpoint for your store.
* **Store ID**: The numeric identifier of your store — the `user_id` returned together with the access token. It also appears in the API base URL (`https://api.nuvemshop.com.br/v1/{store_id}`).
* **Initial sync date**: The earliest date from which records will be synced. Incremental streams only fetch records updated after this date.
The app must have **read** permission on the resources you want to sync (products, orders, customers, coupons, etc.). Changing the app's scopes requires reinstalling it and generating a new token.
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/runs/scheduling-and-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.
# Streams and Fields
## 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 |
| ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Store | `store` | Profile of the store (name, plan, country, currency, languages, domains). Single record. |
| Products | `products` | Catalog products, incremental on `updated_at`. |
| Product Variants | `product_variants` | One row per product variant (price, stock, SKU, attributes), flattened from products. |
| Categories | `categories` | Product categories and their hierarchy, incremental on `updated_at`. |
| Orders | `orders` | Orders of every status (open, closed, cancelled), incremental on `updated_at`. |
| Order Products | `order_products` | One row per order line item, flattened from orders. |
| Transactions | `transactions` | Payment transactions of each order (captures, refunds, failures). *Not selected by default:* requires one request per order, so enable it only when payment-level detail is needed. |
| Customers | `customers` | Store customers with contact, billing and marketing opt-in data, incremental on `updated_at`. |
| Abandoned Checkouts | `abandoned_checkouts` | Checkouts started but not completed, incremental on `updated_at`. |
| Coupons | `coupons` | Discount coupons and their usage, incremental on `updated_at`. |
| Locations | `locations` | Stock locations (warehouses / branches). Full table. |
Nested objects returned by the API (multi-language names, addresses, line items, payment details, amounts with currency) are delivered as **JSON strings** so the tables keep a stable, flat schema. Parse them in a Query when you need individual attributes.
## Fields by stream
Profile of the connected store.
* `id` - Unique numeric identifier of the store
* `name` - Store name per language (JSON object keyed by language code)
* `description` - Store description per language (JSON object)
* `type` - Store type/segment (e.g. clothing, sports)
* `email` - Email address of the store owner
* `logo` - Store logo URL
* `contact_email` - Public contact email
* `facebook`, `twitter`, `google_plus`, `instagram`, `pinterest`, `blog` - Social/blog URLs
* `address` - Physical address of the store
* `phone` - Store phone number
* `whatsapp_phone_number` - WhatsApp contact number
* `business_id` - Business tax identifier (CPF/CNPJ, DNI/CUIT)
* `business_name` - Legal name of the company
* `business_address` - Legal address of the company
* `customer_accounts` - Whether customer accounts are optional or mandatory
* `plan_name` - Nuvemshop subscription plan
* `country` - Country in ISO 3166-1 format
* `languages` - Enabled languages with currency and active flag (JSON object)
* `domains` - Domain names attached to the store
* `original_domain` - Original nuvemshop.com.br / tiendanube.com subdomain
* `current_theme` - Active storefront theme
* `main_language` - Primary language
* `main_currency` - Primary currency (ISO 4217)
* `admin_language` - Admin panel language
* `features` - API features enabled for the store
* `created_at` - Timestamp when the store was created
Catalog products. Incremental on `updated_at`.
* `id` - Unique numeric identifier of the product
* `name` - Product name per language (JSON object)
* `description` - Product description as HTML per language (JSON object)
* `handle` - URL-friendly slug per language (JSON object)
* `variants` - Product variants (JSON array); also available flattened in `product_variants`
* `images` - Product images with URL, position and alt text (JSON array)
* `categories` - Identifiers of the categories the product belongs to
* `brand` - Brand of the product
* `published` - Whether the product is visible in the storefront
* `visibility` - visible, unlisted or hidden
* `free_shipping` - Whether the product is eligible for free shipping
* `video_url` - URL of the product video
* `seo_title` - SEO title per language (JSON object)
* `seo_description` - SEO description per language (JSON object)
* `attributes` - Names of the attributes that define the variants (JSON array)
* `tags` - Comma-separated tags
* `requires_shipping` - Whether the product is physical (true) or digital (false)
* `created_at` - Timestamp when the product was created
* `updated_at` - Timestamp of the last update (replication key)
One row per variant, flattened from the products payload. Incremental on `product_updated_at`.
* `id` - Unique numeric identifier of the variant
* `product_id` - Identifier of the parent product
* `product_updated_at` - Last update of the parent product (replication key)
* `image_id` - Identifier of the image associated with the variant
* `position` - Position of the variant within the product
* `price` - Selling price
* `compare_at_price` - List price shown as comparison when a promotion is active
* `promotional_price` - Promotional price, when set
* `cost` - Cost of the variant for the merchant
* `stock_management` - Whether stock is tracked
* `stock` - Available stock across locations; null when unlimited
* `weight`, `width`, `height`, `depth` - Dimensions (kg / cm)
* `sku` - Stock keeping unit
* `barcode` - Barcode (EAN/UPC)
* `mpn` - Manufacturer part number
* `age_group`, `gender`, `size_type`, `size_system` - Google Shopping attributes
* `values` - Attribute values that identify the variant, per language (JSON array)
* `inventory_levels` - Stock per location (JSON array)
* `created_at` - Timestamp when the variant was created
* `updated_at` - Timestamp of the last update of the variant
Product categories. Incremental on `updated_at`.
* `id` - Unique numeric identifier of the category
* `name` - Category name per language (JSON object)
* `description` - Category description as HTML per language (JSON object)
* `handle` - URL-friendly slug per language (JSON object)
* `parent` - Identifier of the parent category, or null
* `visibility` - visible, hidden or soft-hidden
* `visibility_updated_at` - Last change to the visibility field
* `subcategories` - Identifiers of the first-level subcategories
* `seo_title` - SEO title per language (JSON object)
* `seo_description` - SEO description per language (JSON object)
* `google_shopping_category` - Google product taxonomy category
* `created_at` - Timestamp when the category was created
* `updated_at` - Timestamp of the last update (replication key)
Orders of every status. Incremental on `updated_at`.
**Identification**
* `id` - Unique numeric identifier of the order
* `token` - Token that identifies the order
* `number` - Sequential order number shown to merchants and customers
* `store_id` - Identifier of the store
* `customer_id` - Identifier of the customer (flattened from `customer`)
* `customer` - Customer that placed the order (JSON object)
* `contact_email`, `contact_name`, `contact_phone`, `contact_identification` - Buyer contact data
**Billing**
* `billing_name`, `billing_phone`, `billing_address`, `billing_number`, `billing_floor`, `billing_locality`, `billing_zipcode`, `billing_city`, `billing_province`, `billing_country` - Billing address
* `billing_customer_type` - person or company
* `billing_business_name`, `billing_trade_name`, `billing_state_registration`, `billing_document_type` - Company billing data
* `billing_fiscal_regime`, `billing_invoice_use` - Mexico-specific invoicing fields
**Shipping**
* `shipping_address` - Shipping address (JSON object)
* `shipping_status` - unpacked, unfulfilled, fulfilled, shipped, delivered, partially\_packed or partially\_fulfilled
* `shipping`, `shipping_option`, `shipping_option_code`, `shipping_option_reference` - Shipping method and option
* `shipping_pickup_type` - ship or pickup
* `shipping_pickup_details`, `shipping_store_branch_name`, `shipping_store_branch_extra` - Pickup point data
* `shipping_carrier_name`, `shipping_tracking_number`, `shipping_tracking_url` - Carrier and tracking
* `shipping_suboption` - Sub-options chosen for the shipping method (JSON)
* `shipping_cost_customer` - Shipping cost charged to the customer
* `shipping_cost_owner` - Shipping cost paid by the store owner
* `shipping_min_days`, `shipping_max_days` - Estimated delivery window in weekdays
* `shipped_at` - Timestamp when the order was shipped
* `weight` - Total weight in kilograms
**Amounts & payment**
* `subtotal` - Total of the products before shipping and discounts
* `discount`, `discount_coupon`, `discount_gateway` - Discounts applied
* `total` - Total including shipping and discounts
* `total_usd` - Total converted to US dollars
* `total_paid_by_customer`, `total_paid_by_customer_including_fees` - Amounts actually paid
* `currency` - Currency in ISO 4217 format
* `gateway`, `gateway_id`, `gateway_name`, `gateway_link` - Payment gateway data
* `payment_status` - authorized, pending, paid, partially\_paid, abandoned, refunded, partially\_refunded or voided
* `payment_method`, `payment_credit_card_company`, `payment_installments` - Flattened from `payment_details`
* `payment_details` - Payment details (JSON object)
* `payment_count` - Number of payments made
* `paid_at` - Timestamp when the order was paid
**Status & timestamps**
* `status` - open, closed or cancelled
* `cancelled_at`, `cancel_reason` - Cancellation data
* `closed_at` - Timestamp when the order was archived
* `read_at` - Timestamp when the order was marked as read
* `completed_at` - Completion date with timezone information (JSON object)
* `created_at` - Timestamp when the order was created
* `updated_at` - Timestamp of the last update (replication key)
**Other**
* `products` - Line items (JSON array); also available flattened in `order_products`
* `attributes` - Custom attributes (JSON array)
* `coupon` - Coupons applied (JSON array)
* `promotional_discount` - Promotional discount applied (JSON object)
* `fulfillments` - Fulfillment orders (JSON array)
* `note`, `owner_note` - Customer and store owner notes
* `extra` - Custom information (JSON object)
* `storefront` - store, meli, api, form or pos
* `app_id` - Identifier of the app that created the order
* `client_details` - Browser IP and user agent (JSON object)
* `same_billing_and_shipping_address` - Whether billing and shipping addresses match
* `is_subscription`, `is_subscription_initial` - Subscription flags
* `landing_url` - Landing URL of the session that originated the order
* `has_shippable_products` - Whether the order contains products that require shipping
* `free_shipping_config` - Free shipping configuration applied (JSON)
One row per order line item, flattened from the orders payload. Incremental on `order_updated_at`.
* `id` - Unique numeric identifier of the line item
* `order_id` - Identifier of the parent order
* `order_updated_at` - Last update of the parent order (replication key)
* `product_id` - Identifier of the product purchased
* `variant_id` - Identifier of the variant purchased
* `name` - Product name at the time of purchase
* `price` - Unit price at the time of purchase
* `compare_at_price` - List price at the time of purchase
* `quantity` - Units purchased
* `weight`, `width`, `height`, `depth` - Unit dimensions
* `free_shipping` - Whether the product had free shipping
* `sku` - SKU of the variant purchased
* `barcode` - Barcode of the variant purchased
* `variant_values` - Attribute values of the variant purchased
* `catalog_kit_id`, `order_kit_id`, `kit` - Kit data, when the item belongs to a kit
* `properties` - Custom field values of the line item (JSON array)
* `image` - Image of the product at the time of purchase (JSON object)
* `issues` - Issues detected on the line item
Payment transactions of each order. Child of `orders`; not selected by default.
* `id` - Unique identifier of the transaction
* `order_id` - Identifier of the parent order
* `order_updated_at` - Last update of the parent order (replication key)
* `payment_attempt_id` - Identifier of the payment attempt
* `payment_provider_id` - Identifier of the payment provider
* `payment_provider_tax_id` - Tax identifier of the payment provider (Brazil)
* `payment_method` - Payment method type and identifier (JSON object)
* `info` - Provider-specific payment details (JSON object)
* `status` - authorized, paid, failed, pending, refunded, voided...
* `events` - Events that changed the transaction status (JSON array)
* `captured_amount`, `refunded_amount`, `authorized_amount`, `voided_amount`, `discount_amount` - Amounts with currency (JSON objects)
* `failure_code` - Code describing why the transaction failed
* `created_at` - Timestamp when the transaction was created
Store customers. Incremental on `updated_at`.
* `id` - Unique numeric identifier of the customer
* `name` - Full name
* `email` - Email address
* `phone` - Phone number
* `identification` - Personal/tax identification (CPF/CNPJ, DNI)
* `note` - Store owner's notes
* `default_address` - Default shipping address (JSON object)
* `addresses` - All shipping addresses (JSON array)
* `billing_name`, `billing_phone`, `billing_address`, `billing_number`, `billing_floor`, `billing_locality`, `billing_zipcode`, `billing_city`, `billing_province`, `billing_country` - Billing address
* `extra` - Custom information (JSON object)
* `total_spent` - Total amount spent in the store
* `total_spent_currency` - Currency of `total_spent`
* `last_order_id` - Identifier of the most recent order
* `active` - Whether the account is active
* `first_interaction` - First interaction with the store
* `accepts_marketing` - Whether the customer opted in to email marketing
* `accepts_marketing_updated_at` - Last change to the marketing opt-in
* `created_at` - Timestamp when the customer was created
* `updated_at` - Timestamp of the last update (replication key)
Checkouts started but not completed. Incremental on `updated_at`.
* `id` - Unique numeric identifier of the checkout
* `token` - Token that identifies the checkout
* `store_id` - Identifier of the store
* `abandoned_checkout_url` - URL to recover the checkout
* `contact_email`, `contact_name`, `contact_phone`, `contact_identification` - Customer contact data
* `customer` - Customer that started the checkout, when identified (JSON object)
* `shipping_name`, `shipping_phone`, `shipping_address`, `shipping_number`, `shipping_floor`, `shipping_locality`, `shipping_zipcode`, `shipping_city`, `shipping_province`, `shipping_country` - Shipping address
* `shipping_min_days`, `shipping_max_days` - Estimated delivery window in weekdays
* `billing_name`, `billing_phone`, `billing_address`, `billing_number`, `billing_floor`, `billing_locality`, `billing_zipcode`, `billing_city`, `billing_province`, `billing_country` - Billing address
* `shipping_cost_owner`, `shipping_cost_customer` - Shipping costs
* `coupon` - Coupons applied (JSON array)
* `promotional_discount` - Promotional discount applied (JSON object)
* `subtotal`, `discount`, `discount_coupon`, `discount_gateway`, `total`, `total_usd` - Amounts
* `checkout_enabled` - Whether the checkout can still be resumed
* `weight` - Total weight in kilograms
* `currency` - Currency in ISO 4217 format
* `language` - Language used during checkout
* `gateway`, `gateway_id` - Payment gateway data
* `shipping`, `shipping_option`, `shipping_option_code`, `shipping_option_reference`, `shipping_pickup_details`, `shipping_tracking_number`, `shipping_tracking_url`, `shipping_store_branch_name`, `shipping_pickup_type`, `shipping_suboption` - Shipping method data
* `extra` - Custom information (JSON object)
* `storefront` - store, meli, api, form or pos
* `note` - Note left by the customer
* `next_action` - noop, close, waiting\_ipn or waiting\_manual\_confirmation
* `payment_details` - Payment details (JSON object)
* `attributes` - Line-item properties (JSON array)
* `products` - Products in the cart (JSON array)
* `created_at` - Timestamp when the checkout was created
* `updated_at` - Timestamp of the last update (replication key)
* `completed_at` - Timestamp when the checkout was completed, if it was
Discount coupons. Incremental on `updated_at`.
* `id` - Unique numeric identifier of the coupon
* `code` - Code the customer types to apply the coupon
* `type` - percentage, absolute or shipping
* `valid` - Whether the coupon is currently valid
* `start_date`, `end_date` - Validity window
* `deleted_at` - Timestamp when the coupon was deleted, or null
* `max_uses` - Maximum number of uses; null for unlimited
* `used` - Number of times the coupon has been used
* `value` - Discount amount or percentage
* `includes_shipping` - Whether the discount also applies to shipping
* `first_consumer_purchase` - Whether it applies only to the first purchase
* `min_price` - Minimum cart value required
* `categories` - Categories the coupon is restricted to (JSON array)
* `products` - Products the coupon is restricted to (JSON array)
* `combines_with_other_discounts` - Whether it can be combined with other promotions
* `only_cheapest_shipping` - Whether it applies only to the cheapest eligible shipping option
* `created_at` - Timestamp when the coupon was created
* `updated_at` - Timestamp of the last update (replication key)
Stock locations (warehouses / branches). Full table.
* `id` - Unique identifier of the location
* `store_id` - Identifier of the store
* `name` - Location name per language (JSON object)
* `priority` - Priority used to assign stock at checkout (lower = higher priority)
* `address` - Full address including province, region and country (JSON object)
* `is_default` - Whether this is the default location
* `tags` - Sales-channel tags (e.g. online, offline)
* `created_at` - Timestamp when the location was created
* `updated_at` - Timestamp of the last update
## Rate limits
Nuvemshop enforces a leaky-bucket limit of 40 requests with a refill rate of 2 requests per second (10× higher on Next/Evolution plans). The connector throttles itself when the bucket is nearly full and retries `429` responses honouring the API's reset header, so a large first sync may take a while but will complete without manual intervention.