canonical: https://jentic.com/apis/nuvemshop.com.br/nuvemshop # Nuvemshop Ecommerce API The Nuvemshop API (also known as Tiendanube outside Brazil) is the storefront and order-management surface for one of Latin America's largest hosted e-commerce platforms. It exposes products with variants, categories, customers, orders, and webhook subscriptions, plus convenience operations such as bulk stock and price updates and SKU lookups. The 29-endpoint surface is well suited to building marketplaces, ERP connectors, fulfilment integrations, and AI shopping assistants on top of a Nuvemshop-hosted store. ## For AI agents Manage products, categories, orders, customers, and webhooks on a Nuvemshop or Tiendanube store with bearer authentication. ## Scope Does not handle payment processing, shipping label generation, or storefront theme customisation - use for catalogue, order, and customer management only. ## Capabilities - List, create, update, and delete products with variant-level stock and pricing - Bulk-update variant stock and price across many products in a single call - Find a product by variant SKU for warehouse and POS lookups - Retrieve and update orders for fulfilment and customer-service flows - Manage product categories to organise the storefront tree - Subscribe to webhooks for product, order, and customer change events ## Use cases ### ERP-to-Storefront Inventory Sync Keep an ERP or warehouse system in sync with a Nuvemshop storefront by pushing nightly stock and price updates and reading back confirmed orders. The PATCH `/products/stock-price` endpoint accepts batched variant updates, which avoids the per-product round-trips that otherwise dominate sync runtime. Setup typically takes 1-2 days with a bearer token and the products and orders endpoints. Example prompt: Read tonight's stock CSV and call PATCH `/products/stock-price` with an array of variant updates, then log any failures. ### Order Fulfilment Pipeline Stream new orders into a fulfilment system by subscribing to order webhooks, and resolve catalogue details on demand using the products and customers endpoints. This pattern handles label printing, picking lists, and customer notifications without polling, while keeping the order's current state authoritative on the Nuvemshop side. Example prompt: Subscribe to the 'order/created' webhook, then on each event read the order details and create a shipment record in the WMS. ### AI Shopping Assistant Power a chat-based shopping assistant that lets a customer ask 'do you have black size-medium hoodies in stock?' by searching products and inspecting variant inventory. The product list, single-product retrieve, and SKU lookup endpoints together provide enough surface area to answer availability and price questions with current data. Example prompt: Call GET /products with a search query for 'black hoodie', filter results to size M with stock greater than zero, and return the top three matches. ### Agent-Driven Catalogue Updates Let an AI agent take instructions like 'mark all variants of SKU SHIRT-RED-M as out of stock and discount 10%' and execute them by chaining the SKU lookup and bulk-update endpoints. Through Jentic, the agent searches by intent and gets only the operations it needs, with credentials handled by the platform. Example prompt: Search Jentic for 'update Nuvemshop product stock and price', load the operation, and apply a 10% discount to all variants of a given SKU. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/products` | List all products | | POST | `/products` | Create a new product | | PATCH | `/products/stock-price` | Bulk update stock and price for variants | | GET | `/products/sku/{sku}` | Find product by variant SKU | | GET | `/orders` | Retrieve all orders | ## Key resources - **Products** — Storefront catalogue with variant-level inventory, pricing, and SKU lookup. - **Categories** — Storefront taxonomy used for navigation and merchandising. - **Orders** — Customer orders with fulfilment, payment, and shipping fields. - **Customers** — Buyer records associated with orders. - **Webhooks** — Event subscriptions for product, order, and customer changes. ## Why Jentic - **Setup:** Wiring Nuvemshop by hand means setting up its bearer token auth, folding your store id into the api.nuvemshop.com.br/v1/{store_id} base path, and handling the request plumbing yourself. Through Jentic you install once, import Nuvemshop from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Nuvemshop routes its core catalogue calls through the request body and query, so scope the agent to the operations it needs, such as listing products or reading orders, and leave stock and price updates out unless you add them. You choose the operations it may call, so it only reaches the endpoints you list. - **Credential handling:** Your Nuvemshop bearer token and store id are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list Nuvemshop products' or 'read a Nuvemshop order', and Jentic returns the matching Nuvemshop operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Shopify Admin API** — Global hosted e-commerce platform with broader app ecosystem; main alternative outside Latin America. - **Magento (Adobe Commerce) API** — Self-hosted enterprise commerce platform with deeper customisation than Nuvemshop's hosted model. - **Mailchimp Marketing API** — Sync Nuvemshop customers and orders into Mailchimp audiences for post-purchase email. ## FAQ ### What authentication does the Nuvemshop API use? The API uses bearer-token authentication. After installing your app on a store, you receive an access token that is passed in the Authorization header as 'bearer ' on every request, with the store id encoded in the URL path. Through Jentic, the bearer token is held in the encrypted vault and injected at execution time. ### Can I bulk update stock and price across many products? Yes - PATCH `/products/stock-price` accepts an array of variant updates in a single call, which is the recommended path for nightly catalogue sync from an ERP. Per-product PATCH `/products/{id}` is also available for finer-grained edits. ### What are the rate limits for the Nuvemshop API? The OpenAPI spec does not embed explicit limits. Nuvemshop's published policy is per-store throttling with HTTP 429 returned on excess; back off and retry. Use the bulk stock-price endpoint to reduce call volume. ### How do I subscribe to order events through Jentic? Run pip install jentic, then search for 'subscribe to a Nuvemshop webhook'. Jentic returns the webhook-creation operation with its input schema; supply the event name (for example 'order/created') and your callback URL. Run it through Jentic One, the self-hosted execution layer, to get an agent API key. ### Is the API the same as Tiendanube's API? Yes - Nuvemshop is the Brazilian brand and Tiendanube is the Spanish-language brand of the same platform. The API spec serves both, with two server URLs (api.nuvemshop.com.br and api.tiendanube.com) sharing identical paths and schemas. ### Can I limit what my agent is allowed to do with the Nuvemshop API? Yes. Jentic One is self-hosted by you, so your own rules decide exactly which Nuvemshop operations and credentials the agent may use. You can allow it to list products and read orders while withholding write operations such as PATCH `/products/stock-price`, so it never changes catalogue stock or pricing unless you add those operations to its allowed set. The agent only reaches the endpoints you list, and your bearer token and store id are supplied at execution time rather than exposed to the agent.