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

The simplest way to connect is a Custom App (“Aplicativo sob medida”), created directly in your store admin — no partner account needed (available on the Escala and Next plans):
  1. In the store admin, go to Apps > Custom apps and click Create custom app.
  2. Give it a name (e.g. “Nekt”) and grant read permissions for the resources you want to sync (or full access).
  3. Save, open the app and click Reveal to see the token, then Copy token. The full token is shown only once — copy it right away.
  4. The Store ID is displayed on the same page.
See Nuvemshop’s guide on custom apps. Tokens never expire; they only stop working when the app is deleted or deactivated, or when the token is renewed — if that happens, copy the new token into the source. Partner apps using Nuvemshop’s OAuth flow work the same way (the access_token and user_id from the token endpoint). The following configurations are available:
  • Access Token: The token revealed on the custom app page (or the OAuth access_token).
  • Store ID: The numeric identifier of your store, shown on the custom app page (also the user_id returned with OAuth tokens and the number in https://api.nuvemshop.com.br/v1/{store_id}).
  • Initial sync date: The earliest date from which records will be synced. Incremental streams (orders, products, customers, categories, abandoned checkouts) 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.). Nekt checks the credentials when you validate the source, so a wrong token or Store ID is reported immediately.
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.

​
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.
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, youtube, tiktok, blog - Social/blog URLs
  • url_with_protocol - Primary storefront URL
  • 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
  • updated_at - Timestamp of the last update of the store profile
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)
  • canonical_url - Canonical URL of the product page
  • has_stock, is_kit - Stock availability and kit flags
  • invalid_at - Timestamp when the product became invalid, if applicable
  • videos - Videos attached to the product (JSON array)
  • 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
  • price_without_taxes - Selling price before taxes
  • visible - Whether the variant is visible in the storefront
  • 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)
  • next_action - Next available operation in the order flow
  • subtotal_without_taxes, total_paid - Additional amounts
  • coupon_id - Identifier of the coupon applied
  • order_origin - Origin of the order as reported by the platform
  • checkout_enabled, checkout_enabled_validation_messages, checkout_bot_suspect, checkout_app_blocked - Checkout status flags
  • customer_visit - Attribution data of the visit that led to the order (JSON object)
  • billing_business_activity - Business activity of the billing company
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
  • cost - Unit cost for the merchant
  • name_without_variants - Product name without variant attributes
  • has_promotional_price, is_gift - Item flags
  • promotions - Promotions applied to the item (JSON object)
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
  • customer_type, business_name, trade_name, state_registration, business_activity, document_type - Company data, when the customer is a company
  • fiscal_regime, invoice_use - Mexico-specific invoicing fields
  • 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_status, payment_count, gateway_name - Payment data
  • billing_customer_type, billing_business_name, billing_trade_name, billing_state_registration, billing_business_activity, billing_document_type, billing_fiscal_regime, billing_invoice_use - Company billing data
  • subtotal_without_taxes, total_paid - Additional amounts
  • shipping_store_branch_extra, owner_note, order_origin - Additional order data
  • same_billing_and_shipping_address, is_subscription, is_subscription_initial - Flags
  • contact_accepts_marketing, contact_accepts_marketing_updated_at - Marketing opt-in
  • checkout_enabled_validation_messages, checkout_bot_suspect, checkout_app_blocked, was_notified, has_stock_available - Checkout status flags
  • customer_visit, cart_flags - Attribution and cart flags (JSON objects)
  • 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. Full table.
  • 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
  • start_time, end_time - Time of day bounds of the validity window
  • max_uses_per_client - Maximum uses per customer; null for unlimited
  • max_discount_amount - Cap on the discount amount for percentage coupons
  • is_deleted - Whether the coupon has been deleted
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)
  • additional_days, weekends_and_holidays - Handling-time settings
  • deleted_at - Timestamp when the location was deleted, or null
  • 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.