Tiendanube / Nuvemshop

Tiendanube / Nuvemshop

This connector talks to the Tiendanube REST API (Nuvemshop in Brazil, same platform and same API), version 2025-03, at https://api.tiendanube.com/2025-03/<store id>. Every request goes to one store.

Credentials

Tiendanube has no API keys in the store admin: access is granted to an app. To get a token for your own store:

1. Register at the Tiendanube or Nuvemshop Partners portal and create an app under Apps. Choose the scopes you need (read_products, write_products, read_orders, write_orders, read_customers, read_coupons...); a write scope includes its read scope.
2. Install the app on your store by opening https://www.tiendanube.com/apps/<app id>/authorize. You are redirected to the app's redirect URL with a code (valid 5 minutes).
3. Exchange it: POST https://www.tiendanube.com/apps/authorize/token with client_id, client_secret, grant_type=authorization_code and code. The answer has access_token (put it in TIENDANUBE_ACCESS_TOKEN) and user_id, which is the store id (put it in TIENDANUBE_STORE_ID). Tokens do not expire; they stop working when a new one is issued for the same app or the app is uninstalled.

The token is sent as Authorization: Bearer <token>. Older integrations use the legacy header Authentication: bearer <token>, which the API still accepts; a token works with either. Tiendanube also requires a User-Agent with the app name and a contact; without it the API answers 400. The connector sends AnythingMCP ([email protected]).

Start here

tiendanube_get_store returns the store name, languages, currency and plan. Then tiendanube_list_orders or tiendanube_list_products.

Pagination and limits

• Lists return 30 items by default; per_page goes up to 200, page starts at 1. The total count is in the x-total-count header and the next page in the Link header (both returned in _headers / _pagination).
• Order queries stop at 10,000 results: narrow them with created_at_min / created_at_max or a status filter.
• Rate limit: a leaky bucket of 40 requests draining at 2 per second per store and app (10x on Next and Evolution plans). Over it the API returns 429.

Data conventions

• Ids are integers. Product variants have their own ids; stock and price live on the variant, not on the product.
• Product and category names, descriptions and handles are objects keyed by language ({"es": "...", "pt": "..."}). When creating, pass such an object or a plain string, which is applied to every language.
• Money values are strings with two decimals ("5400.00") in the store currency (currency on the order).
• Dates are ISO 8601 with offset, e.g. 2026-09-01T00:00:00-03:00.
• Orders have three separate states: status (open, closed, cancelled), payment_status (pending, authorized, paid, abandoned, refunded, voided) and shipping_status (unpacked, unfulfilled, fulfilled).

Pitfalls

• published and visibility on products cannot be sent together (422); this connector uses visibility.
• A 402 means the store's API access is suspended for an unpaid subscription.
• tiendanube_cancel_order restocks and e-mails the customer by default.