Product

A Product is an item for sale in a Tiendanube/Nuvemshop's store. It can be either a good or a service.

📢 Important 📢
A new Product API with support for multi inventory is currently being rolled out to every merchant.
For any new development, we strongly recommend you to use the new version. Please contact us to activate this new version in your stores if needed.

Properties

Property	Explanation
id	The unique numeric identifier for the Product
name	List of the names of the Product, in every language supported by the store
description	List of the descriptions of the Product, as HTML, in every language supported by the store
handle	List of the url-friendly strings generated from the Product's names, in every language supported by the store
variants	List of Product Variant objects representing the different version of the Product
images	List of Product Image objects representing the Product's images
categories	List of Category Ids representing the Product's categories
brand	The Product's brand
published	true if the Product is published in the store. false otherwise
free_shipping	true if the Product is elegible for free shipping. false otherwise
video_url	String with a valid URL format. Only admits https links
seo_title	The SEO friendly title for the Product. Up to 70 characters
seo_description	The SEO friendly description for the Product. Up to 320 characters
attributes	List of the names of the attributes whose values define the variants. E.g.: Color, Size, etc. It is important that the number of `attributes` is equal to the number of `values` within the variants. Each product can have a maximum of 3 attributes
tags	String with all the Product's tags, separated by commas
created_at	Date when the Product was created in ISO 8601 format
updated_at	Date when the Product was last updated in ISO 8601 format
requires_shipping	true if the Product is physical. false if it is digital

Endpoints

GET /products

Receive a list of all Products.

Parameter	Explanation
since_id	Restrict results to after the specified ID
language	Specify search language
q	Search Products containing the given text in their names, descriptions or SKU
handle	Show Products with a given URL
category_id	Show Products with a given category
published	Show Products by published status. Valid values are "true" or "false"
free_shipping	Show Products by free_shipping status. Valid values are "true" or "false"
max_stock	Show Products with less or equal stock than the specified value
min_stock	Show Products with more or equal stock than the specified value
has_promotional_price	Show Products that have a defined promotional price. Valid values are true or false
has_weight	Show Products that have a defined weight. Valid values are true or false
has_all_dimensions	Show Products that have a defined depth, width and height. Valid values are true or false
has_weight_and_all_dimensions	Show Products that have a defined weight, depth, width and height. Valid values are true or false
created_at_min	Show Products created after date (ISO 8601 format)
created_at_max	Show Products created before date (ISO 8601 format)
updated_at_min	Show Products last updated after date (ISO 8601 format)
updated_at_max	Show Products last updated before date (ISO 8601 format)
sort_by	Sort Products by a particular criteria (I.E.: sort_by=created-at-ascending)
page	Page to show
per_page	Amount of results
fields	Comma-separated list of fields to include in the response

Sort Criteria	Explanation
user	User manually defined sort
price-ascending, cost-ascending	Sort by price ascending
price-descending, cost-descending	Sort by price descending
alpha-ascending, name-ascending	Sort by Product name ascending
alpha-descending, name-descending	Sort by Product name descending
created-at-ascending	Sort by created date ascending
created-at-descending	Sort by created date descending
best-selling	Sort by number of sold products descending

GET /products

HTTP/1.1 200 OK

[
  {
    "attributes": [
      {
        "en": "Size"
      }
    ],
    "categories": [
      {
        "created_at": "2013-01-03T09:11:51-03:00",
        "description": {
          "en": "",
          "es": "",
          "pt": ""
        },
        "handle": {
          "en": "poke-balls",
          "es": "poke-balls",
          "pt": "poke-balls"
        },
        "id": 4567,
        "name": {
          "en": "Poké Balls",
          "es": "Poké Balls",
          "pt": "Poké Balls"
        },
        "parent": null,
        "subcategories": [],
        "google_shopping_category": null,
        "updated_at": "2013-03-11T09:14:11-03:00"
      }
    ],
    "created_at": "2013-01-03T09:11:51-03:00",
    "description": {
      "en": "<p>The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.</p>",
      "es": "<p>La mejor Bola con el nivel máximo de desempeño. Atrapará cualquier Pokémon sin fallar.</p>",
      "pt": "<p>A melhor Bola com o nível máximo de desempenho. Ele vai pegar qualquer Pokémon selvagem sem falhar.</p>"
    },
    "handle": {
      "en": "master-ball",
      "es": "master-ball",
      "pt": "master-ball"
    },
    "id": 1234,
    "images": [
      {
        "id": 101,
        "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/servine-640-0.jpg",
        "position": 1,
        "product_id": 1234
      },
      {
        "id": 112,
        "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
        "position": 2,
        "product_id": 1234
      },
      {
        "id": 123,
        "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/stoutland-640-0.jpg",
        "position": 3,
        "product_id": 1234
      }
    ],
    "name": {
      "en": "Master Ball",
      "es": "Master Ball",
      "pt": "Master Ball"
    },
    "brand": null,
    "video_url": "https://www.youtube.com/watch?v=57aG16_gQcU",
    "seo_title": "Master Ball",
    "seo_description": "The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.",
    "published": true,
    "free_shipping": false,
    "updated_at": "2013-03-11T09:14:11-03:00",
    "variants": [
      {
        "id": 101,
        "promotional_price": "19.00",
        "created_at": "2013-01-03T09:11:51-03:00",
        "depth": null,
        "height": null,
        "values": [
          {
            "en": "Small"
          }
        ],
        "price": "25.00",
        "product_id": 1234,
        "stock_management": true,
        "stock": 5,
        "sku": "BSG1234A",
        "updated_at": "2013-03-11T09:14:11-03:00",
        "weight": "2.00",
        "width": null,
        "cost": null
      },
      {
        "id": 112,
        "promotional_price": "19.00",
        "created_at": "2013-01-03T09:11:51-03:00",
        "depth": null,
        "height": null,
        "values": [
          {
            "en": "Medium"
          }
        ],
        "price": "25.00",
        "product_id": 1234,
        "stock_management": true,
        "stock": 5,
        "sku": "BSG1234B",
        "updated_at": "2013-03-11T09:14:11-03:00",
        "weight": "2.25",
        "width": null,
        "cost": null
      },
      {
        "id": 133,
        "promotional_price": "19.00",
        "created_at": "2013-01-03T09:11:51-03:00",
        "depth": null,
        "height": null,
        "values": [
          {
            "en": "Large"
          }
        ],
        "price": "25.00",
        "product_id": 1234,
        "stock_management": true,
        "stock": 5,
        "sku": "BSG1234C",
        "updated_at": "2013-03-11T09:14:11-03:00",
        "weight": "2.50",
        "width": null,
        "cost": "10.99"
      }
    ],
    "tags": "Brinquedos, pokeball, oferta, colecionismo"
  }
]

GET /products?created_at_min=2013-01-01T00:00:00-03:00&fields=id,name

HTTP/1.1 200 OK

[
  {
    "id": 1234,
    "name": {
      "en": "Master Ball",
      "es": "Master Ball",
      "pt": "Master Ball"
    }
  }
]

GET /products/{id}

Receive a single Product

Parameter	Explanation
fields	Comma-separated list of fields to include in the response

GET /products/1234

HTTP/1.1 200 OK

{
  "attributes": [
    {
      "en": "Size"
    }
  ],
  "categories": [
    {
      "created_at": "2013-01-03T09:11:51-03:00",
      "description": {
        "en": "",
        "es": "",
        "pt": ""
      },
      "handle": {
        "en": "poke-balls",
        "es": "poke-balls",
        "pt": "poke-balls"
      },
      "id": 4567,
      "name": {
        "en": "Poké Balls",
        "es": "Poké Balls",
        "pt": "Poké Balls"
      },
      "parent": null,
      "subcategories": [],
      "google_shopping_category": null,
      "updated_at": "2013-03-11T09:14:11-03:00"
    }
  ],
  "created_at": "2013-01-03T09:11:51-03:00",
  "description": {
    "en": "<p>The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.</p>",
    "es": "<p>La mejor Bola con el nivel máximo de desempeño. Atrapará cualquier Pokémon sin fallar.</p>",
    "pt": "<p>A melhor Bola com o nível máximo de desempenho. Ele vai pegar qualquer Pokémon selvagem sem falhar.</p>"
  },
  "handle": {
    "en": "master-ball",
    "es": "master-ball",
    "pt": "master-ball"
  },
  "id": 1234,
  "images": [
    {
      "id": 101,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/servine-640-0.jpg",
      "position": 1,
      "product_id": 1234
    },
    {
      "id": 112,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
      "position": 2,
      "product_id": 1234
    },
    {
      "id": 123,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/stoutland-640-0.jpg",
      "position": 3,
      "product_id": 1234
    }
  ],
  "name": {
    "en": "Master Ball",
    "es": "Master Ball",
    "pt": "Master Ball"
  },
  "brand": null,
  "video_url": "https://www.youtube.com/watch?v=57aG16_gQcU",
  "seo_title": "Master Ball",
  "seo_description": "The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.",
  "published": true,
  "free_shipping": false,
  "updated_at": "2013-03-11T09:14:11-03:00",
  "variants": [
    {
      "id": 101,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Small"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234A",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.00",
      "width": null,
      "cost": null
    },
    {
      "id": 112,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Small"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234B",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.25",
      "width": null,
      "cost": null
    },
    {
      "id": 133,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Small"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234C",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.50",
      "width": null,
      "cost": "10.99"
    }
  ],
  "tags": "Brinquedos, pokeball, oferta, colecionismo"
}

GET /products/sku/{sku}

Returns the first Product found where one of its variants has the given SKU.

GET /products/sku/1234abcd

POST /products

Creates a new Product

Note: To guarantee a fluid process, we recommended that you create a product with a maximum of 9 images linked to the object in this endpoint. If the product has more images, use this endpoint: POST /products/{product_id}/images

POST /products

{
  "invalid_name": "foobar"
}

HTTP/1.1 422 Unprocessable Entity

{
  "name": ["can't be blank"]
}

HTTP/1.1 422 Unprocessable Entity

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Store has reached maximum limit of 100000 allowed products"
}

HTTP/1.1 422 Unprocessable Entity

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Product is not allowed to have more than 250 images"
}

HTTP/1.1 422 Unprocessable Entity

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Product is not allowed to have more than 1000 variants"
}

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "The video url field is not a secure url"
}

POST /products

{
  "images": [
    {
      "src": "http://images1.wikia.nocookie.net/__cb20101106022321/pokemon/images/f/f1/UltraBallArt.png"
    }
  ],
  "name": {
    "en": "Ultra Ball",
    "es": "Ultra Ball",
    "pt": "Ultra Ball"
  },
  "video_url": "https://www.youtube.com/watch?v=57aG16_gQcU",
  "variants": [
    {
      "price": "10.00",
      "stock_management": true,
      "stock": 12,
      "weight": "2.00",
      "cost": "10.99"
    }
  ],
  "categories": [11654304, 11654305]
}

HTTP/1.1 201 Created

{
  "attributes": [],
  "categories": [
    {
      "created_at": "2013-01-03T09:11:51-03:00",
      "description": {
        "en": "",
        "es": "",
        "pt": ""
      },
      "handle": {
        "en": "poke-balls",
        "es": "poke-balls",
        "pt": "poke-balls"
      },
      "id": 4567,
      "name": {
        "en": "Poké Balls",
        "es": "Poké Balls",
        "pt": "Poké Balls"
      },
      "parent": null,
      "subcategories": [],
      "google_shopping_category": null,
      "updated_at": "2013-03-11T09:14:11-03:00"
    }
  ],
  "created_at": "2013-06-01T12:15:11-03:00",
  "description": {
    "en": "",
    "es": "",
    "pt": ""
  },
  "handle": {
    "en": "ultra-ball",
    "es": "ultra-ball",
    "pt": "ultra-ball"
  },
  "id": 2435,
  "images": [
    {
      "id": 231,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/UltraBallArt.jpg",
      "position": 1,
      "product_id": 2435
    }
  ],
  "name": {
    "en": "Ultra Ball",
    "es": "Ultra Ball",
    "pt": "Ultra Ball"
  },
  "brand": null,
  "video_url": "https://www.youtube.com/watch?v=57aG16_gQcU",
  "seo_title": "Ultra Ball",
  "seo_description": "",
  "published": true,
  "free_shipping": false,
  "created_at": "2013-06-01T12:15:11-03:00",
  "variants": [
    {
      "id": 101,
      "promotional_price": null,
      "created_at": "2013-06-01T12:15:11-03:00",
      "depth": null,
      "height": null,
      "values": [],
      "price": "10.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 12,
      "sku": null,
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.00",
      "width": null,
      "cost": "10.99"
    }
  ],
  "tags": ""
}

PUT /products/{id}

Modify an existing Product

Note: If you create a product without the Product Variant object and want to change information such as price and stock, in the API there is a "virtual" variant which is linked to the typical properties of a variant (prices, stock, dimensions, etc). Therefore, in these cases, changes in any of the properties mentioned above must be made on its "virtual" variant, not on the product itself. That is, the endpoint to use is: PUT /products/{product_id}/variants/{id}

Important: If the product has an associated category, and the categories field is sent empty, the product ends up without a category. In other words, the category is removed from the product. So, if you want to keep the current category, you must include the category_id in the field or else you must omit the categories field.

PUT /products/5123

{
  "categories": [4567],
  "id": 1234,
  "published": false
}

HTTP/1.1 200 OK

{
  "attributes": [
    {
      "en": "Size"
    }
  ],
  "categories": [
    {
      "created_at": "2013-01-03T09:11:51-03:00",
      "description": {
        "en": "",
        "es": "",
        "pt": ""
      },
      "handle": {
        "en": "poke-balls",
        "es": "poke-balls",
        "pt": "poke-balls"
      },
      "id": 4567,
      "name": {
        "en": "Poké Balls",
        "es": "Poké Balls",
        "pt": "Poké Balls"
      },
      "parent": null,
      "subcategories": [],
      "google_shopping_category": null,
      "updated_at": "2013-03-11T09:14:11-03:00"
    }
  ],
  "created_at": "2013-01-03T09:11:51-03:00",
  "description": {
    "en": "<p>The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.</p>",
    "es": "<p>La mejor Bola con el nivel máximo de desempeño. Atrapará cualquier Pokémon sin fallar.</p>",
    "pt": "<p>A melhor Bola com o nível máximo de desempenho. Ele vai pegar qualquer Pokémon selvagem sem falhar.</p>"
  },
  "handle": {
    "en": "master-ball",
    "es": "master-ball",
    "pt": "master-ball"
  },
  "id": 1234,
  "images": [
    {
      "id": 101,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/servine-640-0.jpg",
      "position": 1,
      "product_id": 1234
    },
    {
      "id": 112,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
      "position": 2,
      "product_id": 1234
    },
    {
      "id": 123,
      "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/stoutland-640-0.jpg",
      "position": 3,
      "product_id": 1234
    }
  ],
  "name": {
    "en": "Master Ball",
    "es": "Master Ball",
    "pt": "Master Ball"
  },
  "brand": null,
  "video_url": null,
  "seo_title": "Master Ball",
  "seo_description": "The best Ball with the ultimate level of performance. It will catch any wild Pokémon without fail.",
  "published": false,
  "free_shipping": false,
  "updated_at": "2013-06-01T12:15:11-03:00",
  "variants": [
    {
      "id": 101,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Small"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234A",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.00",
      "width": null,
      "cost": null
    },
    {
      "id": 112,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Medium"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234B",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.25",
      "width": null,
      "cost": null
    },
    {
      "id": 133,
      "promotional_price": "19.00",
      "created_at": "2013-01-03T09:11:51-03:00",
      "depth": null,
      "height": null,
      "values": [
        {
          "en": "Large"
        }
      ],
      "price": "25.00",
      "product_id": 1234,
      "stock_management": true,
      "stock": 5,
      "sku": "BSG1234C",
      "updated_at": "2013-03-11T09:14:11-03:00",
      "weight": "2.50",
      "width": null,
      "cost": null
    }
  ],
  "tags": ""
}

DELETE /products/{id}

Remove a Product

DELETE /products/1234

HTTP/1.1 200 OK

{}

PATCH /products/stock-price

Updates Stock or Price of multiple products and variants. 50 different variants can be updated at once taking all products into account.

PATCH /products/stock-price

[
    {
        "id": 53786462,
        "variants": [
            {
                "id": 147085180,
                "price": 1000,
                "inventory_levels": [
                    {
                        "stock": 300
                    }
                ]
            }
        ]
    },
    {
        "id": 49819000,
        "variants": [
            {
                "id": 133862417,
                "price": 222.03
            },
            {
                "id": 133862416,
                "inventory_levels": [
                    {
                        "stock": 100
                    }
                ]
            }
        ]
    }
]

Parameter	Mandatory	Description
Main array (no key)	Yes	Array of products
id	Yes	Product id
variants	Yes	Array of variants
id	Yes	Variant id
price	No	Variant price
inventory_levels	No	List with stock levels
stock	No	Stock quantity

Stock field is inside each inventory_levels array element to indicate the stock in accordance with the Multi CD project.

HTTP/1.1 200 OK

[
    {
        "id": 53786462,
        "variants": [
            {
                "id": 147085180,
                "success": true
            }
        ]
    },
    {
        "id": 49819000,
        "variants": [
            {
                "id": 133862417,
                "success": true
            },
            {
                "id": 133862416,
                "success": true
            }
        ]
    }
]

HTTP/1.1 422 Unprocessable Entity

{
    "code": 422,
    "message": "Unprocessable Entity",
    "description": "Validation error",
    "price": [
        "The price must be a number."
    ]
}

HTTP/1.1 422 Unprocessable Entity

{
    "code": 422,
    "message": "Unprocessable Entity",
    "description": "Validation error",
    "stock": [
        "The stock must be at least 0."
    ]
}

HTTP/1.1 422 Unprocessable Entity

{
    "code": 422,
    "message": "Unprocessable Entity",
    "description": "Too many variants sent for update"
}

FAQ

How to set up unlimited/infinite stock?

In order to set unlimited stock for a product or variant, you have to modify the variant's stock to "". Example:

{
    "stock": ""
}

Note: The stock_management property is automatically set by Tiendanube, and can't be modified via API. This property can have the following values:

false: the variant's stock is infinite.
true: the variant's stock is equal or higher than 0.

Why is the stock_management property not being modified?

This property is automatically set by Tiendanube, and can't be modified via API. It can have the following values:

false: when the variant's stock is infinite.
true: when the variant's stock is equal or higher than 0.

In order to set unlimited stock for a product or variant, you have to modify the variant's stock to "". Example:

{
    "stock": ""
}

How many attributes and variants can a product have?

A product can have a maximum of 3 attributes. For example:

    "attributes": [
        {
            "en": "Color"
        },
        {
            "en": "Size"
        },
        {
            "en": "Gender"
        }
    ]

Important: The same name cannot be repeated in two different attributes of the same product.

And a product can have up to 1,000 total variants combined across the three attributes.

The attribute applies to the Product entity. The variants apply to the Product Variant entity.

Product

Properties​

Endpoints​

GET /products​

GET /products​

GET /products?created_at_min=2013-01-01T00:00:00-03:00&fields=id,name​

GET /products/{id}​

GET /products/1234​

GET /products/sku/{sku}​

GET /products/sku/1234abcd​

POST /products​

POST /products​

POST /products​

PUT /products/{id}​

PUT /products/5123​

DELETE /products/{id}​

DELETE /products/1234​

PATCH /products/stock-price​

PATCH /products/stock-price​

FAQ​

Properties

Endpoints

GET /products

GET /products

GET /products?created_at_min=2013-01-01T00:00:00-03:00&fields=id,name

GET /products/{id}

GET /products/1234

GET /products/sku/{sku}

GET /products/sku/1234abcd

POST /products

POST /products

POST /products

PUT /products/{id}

PUT /products/5123

DELETE /products/{id}

DELETE /products/1234

PATCH /products/stock-price

PATCH /products/stock-price

FAQ