Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
7 contributors

Users who have contributed to this file

@lmangiar @lombo @sdurandeu @pabloruiz23 @mcapodacqua @diegode @cleytonmessias
819 lines (771 sloc) 23.7 KB

Product

A Product is an item for sale in a Tienda Nube/Nuvem Shop's store. It can be either a good or a service.

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
descripton 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 objects representing the Product's categories
published true if the Product is published in the store. false if the Product will not show up on the store
attributes List of the names of the attributes whose values define the variants. E.g.: Color, Size, etc.
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
canonical_url The SEO friendly url for the product in the store

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 or descriptions
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"
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": [],
              "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"
      },
      "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      
       },
       {
         "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      
       },
       {
         "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
       }
      ]
    },
    {
        "id": 435407,
        "name": {
            "es": "Cambiate por favor",
            "en": "OG add image action"
        },
        "description": {
            "es": "<p>Isso!<\/p>\r\n",
            "en": "<p>Isso!<\/p>\r\n"
        },
        "handle": {
            "es": "cambiate-por-favor",
            "en": "og-add-image-action"
        },
        "attributes": [],
        "published": true,
        "free_shipping": true,
        "created_at": "2012-02-19T17:34:36+0000",
        "updated_at": "2014-07-17T14:13:19+0000",
        "variants": [
            {
                "id": 821537,
                "product_id": 435407,
                "position": 5,
                "price": "22.00",
                "promotional_price": null,
                "stock_management": false,
                "stock": null,
                "weight": "0.75",
                "width": "0.00",
                "height": "0.00",
                "depth": "0.00",
                "sku": "ASF",
                "values": [],
                "created_at": "2012-02-19T17:34:37+0000",
                "updated_at": "2014-07-17T14:13:19+0000"
            }
        ],
        "tags": "algo, jojo",
        "images": [
            {
                "id": 634688,
                "product_id": 435407,
                "src": "https:\/\/s3-sa-east-1.amazonaws.com\/tiendanube-mati\/stores\/046\/products\/blog%2024-1024-1024.jpg",
                "position": 1
            },
            {
                "id": 1021828,
                "product_id": 435407,
                "src": "https:\/\/s3-sa-east-1.amazonaws.com\/tiendanube-mati\/stores\/046\/products\/do-test-1024-1024.jpg",
                "position": 2
            }
        ],
        "categories": [
            {
                "id": 105190,
                "name": {
                    "es": "Pantalones",
                    "en": "Pantalones"
                },
                "description": {
                    "es": "",
                    "en": ""
                },
                "handle": {
                    "es": "pantalones",
                    "en": "pantalones"
                },
                "parent": null,
                "subcategories": [
                    119258
                ],
                "created_at": "2012-02-19T17:34:36+0000",
                "updated_at": "2014-01-28T14:10:12+0000"
            }
        ]
    }
]

GET /products?free_shipping=true

HTTP/1.1 200 OK

[
    {
        "id": 435407,
        "name": {
            "es": "Cambiate por favor",
            "en": "OG add image action"
        },
        "description": {
            "es": "<p>Isso!<\/p>\r\n",
            "en": "<p>Isso!<\/p>\r\n"
        },
        "handle": {
            "es": "cambiate-por-favor",
            "en": "og-add-image-action"
        },
        "attributes": [],
        "published": true,
        "free_shipping": true,
        "created_at": "2012-02-19T17:34:36+0000",
        "updated_at": "2014-07-17T14:13:19+0000",
        "variants": [
            {
                "id": 821537,
                "product_id": 435407,
                "position": 5,
                "price": "22.00",
                "promotional_price": null,
                "stock_management": false,
                "stock": null,
                "weight": "0.75",
                "width": "0.00",
                "height": "0.00",
                "depth": "0.00",
                "sku": "ASF",
                "values": [],
                "created_at": "2012-02-19T17:34:37+0000",
                "updated_at": "2014-07-17T14:13:19+0000"
            }
        ],
        "tags": "algo, jojo",
        "images": [
            {
                "id": 634688,
                "product_id": 435407,
                "src": "https:\/\/s3-sa-east-1.amazonaws.com\/tiendanube-mati\/stores\/046\/products\/blog%2024-1024-1024.jpg",
                "position": 1
            },
            {
                "id": 1021828,
                "product_id": 435407,
                "src": "https:\/\/s3-sa-east-1.amazonaws.com\/tiendanube-mati\/stores\/046\/products\/do-test-1024-1024.jpg",
                "position": 2
            }
        ],
        "categories": [
            {
                "id": 105190,
                "name": {
                    "es": "Pantalones",
                    "en": "Pantalones"
                },
                "description": {
                    "es": "",
                    "en": ""
                },
                "handle": {
                    "es": "pantalones",
                    "en": "pantalones"
                },
                "parent": null,
                "subcategories": [
                    119258
                ],
                "created_at": "2012-02-19T17:34:36+0000",
                "updated_at": "2014-01-28T14:10:12+0000"
            }
        ]
    }
]

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": [],
          "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"
  },
  "published": true,
  "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      
   },
   {
     "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      
   },
   {
     "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
   }
  ]
}

POST /products

Create a new Product

POST /products

{
    "invalid_name": "foobar"
}

HTTP/1.1 422 Unprocessable Entity

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

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"
    },
    "variants": [
        {
            "price": "10.00",
            "stock_management": true,
            "stock": 12,
            "weight": "2.00"
        }
    ]
}

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": [],
            "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"
    },
    "published": true,
    "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      
       }
    ]
}

PUT /products/#{id}

Modify an existing Product

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": [],
            "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"
    },
    "published": 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      
     },
     {
       "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      
     },
     {
       "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
     }
    ]
}

DELETE /products/#{id}

Remove a Product

DELETE /products/1234

HTTP/1.1 200 OK

{}
You can’t perform that action at this time.