Developers

Products

Summary of product endpoints

All endpoints take optional query parameters that enhance the response objects:

  • include — enhance the response objects (e.g. include=variants,translations). Supported values are:
    • variants — includes variants for products that have variants.
    • locations — includes locations (Voog Page, Article, Element) of the button to where the product has been attached. This will be ignored for anonymous requests.
    • translations — includes translations for all translatable objects and keys.
    • details — includes project details (image data).
    • categories — includes list of product categories associated with product.
  • language_code — display all top-level values in the given language context.

List all available products for the current site

GET /admin/api/ecommerce/v1/products?include=variants

This endpoint also allows anonymous access returning live products only.

Example response:

Status: 200 OK

[
  {
    "id": 1,
    "price": 166.67,
    "price_min": 166.67,
    "price_max": 166.67,
    "status": "live",
    "stock": 10,
    "reserved_quantity": 1,
    "in_stock": true,
    "sku": "0001",
    "image_id": null,
    "uses_variants": false,
    "variants_count": 0,
    "created_at": "2016-12-10T15:59:23.000Z",
    "updated_at": "2016-12-10T15:59:23.000Z",
    "name": "Sample product",
    "slug": "sample-product",
    "description": "Product description"
  }, {
    "id": 2,
    "price": 166.67,
    "price_min": 200.0,
    "price_max": 250.0,
    "status": "live",
    "stock": null,
    "reserved_quantity": 0,
    "in_stock": true,
    "sku": null,
    "image_id": null,
    "uses_variants": true,
    "variants_count": 2,
    "created_at": "2016-12-10T09:14:15.000Z",
    "updated_at": "2016-12-11T18:41:53.000Z",
    "name": "Sample product",
    "slug": "sample-product-1",
    "description": "Product description",
    "variant_types": [
      {
        "id": 1,
        "name": "Color",
        "values": [
          {
            "id": 1,
            "name": "Red"
          }, {
            "id": 2,
            "name": "Blue"
          }
        ]
      }
    ],
    "variants": [
      {
        "id": 3,
        "price": 200.0,
        "status": "live",
        "stock": null,
        "reserved_quantity": 0,
        "in_stock": true,
        "sku": "0002",
        "created_at": "2017-03-22T12:47:44.000Z",
        "updated_at": "2017-03-22T12:53:07.000Z",
        "variant_attributes_text": "Color: Red",
        "variant_attributes": [
          {
            "type_id": 1,
            "value_id": 1
          }
        ]
      }, {
        "id": 4,
        "price": 250.0,
        "status": "live",
        "stock": null,
        "reserved_quantity": 0,
        "in_stock": true,
        "sku": "0003",
        "created_at": "2017-03-22T12:47:44.000Z",
        "updated_at": "2017-03-22T12:53:07.000Z",
        "variant_attributes_text": "Color: Blue",
        "variant_attributes": [
          {
            "type_id": 1,
            "value_id": 2
          }
        ]
      }
    ]
  }
]

Parameters

  • per_page — products per response (default: 50; maximum: 250).
  • page — requested page (default: 1).

Filter attributes

Read more about filters.

  • Object category attributes: id, name, slug, parent_id, depth, created_at, updated_at.
  • Object product attributes: id, name, slug, description, sku, price, price_min, price_max, status, stock, reserved_quantity, uses_variants, created_at, updated_at.

Create a new product

POST /admin/api/ecommerce/v1/products?include=translations&language_code=en

Example data:

{
  "product": {
    "price": 21.0,
    "status": "live",
    "name": "Product (en)",
    "slug": "product-en",
    "description": "Product description",
    "sku": "0004",
    "image_id": 88,
    "variant_types": [
      {
        "name": "Color",
        "translations": {
          "name": {"en": "Color", "et": "Värv"}
        },
        "values": [
          {
            "name": "Blue",
            "translations": {
              "name": {"en": "Blue", "et": "Sinine"}
            }
          },
          {
            "name": "Red",
            "translations": {
              "name": {"en": "Red", "et": "Punane"}
            }
          }
        ]
      }
    ],
    "variants": [],
    "category_ids": [14556, 32321, 11679],
    "translations": {
      "name": {
        "en": "Product (en)", "et": "Product (et)"
      },
      "slug": {
        "en": "product-en", "et": "product-et"
      },
      "description": {
        "en": "Product description", "et": "Tootekirjeldus"
      }
    }
  }
}

Example response:

Status: 201 Created

{
  "id": 5,
  "price": 21.0,
  "price_min": 21.0,
  "price_max": 21.0,
  "status": "live",
  "stock": null,
  "reserved_quantity": 0,
  "in_stock": true,
  "sku": null,
  "uses_variants": true,
  "variants_count": 2,
  "created_at": "2016-12-10T09:14:15.000Z",
  "updated_at": "2016-12-11T18:41:53.000Z",
  "name": "Product (en)",
  "slug": "product-en",
  "description": "Product description",
  "image_id": 88,
  "image": {
    "content_type": "image/jpeg",
    "width": 948,
    "height": 506,
    "url": "http://media.voog.com/0000/0000/0001/photos/img.jpg",
    "thumbnail": {
      "content_type": "image/jpeg",
      "width": 150,
      "height": 80,
      "url": "http://media.voog.com/0000/0000/0001/photos/img_medium.jpg"
    },
    "sizes": [
      {
        "content_type": "image/jpeg",
        "width": 600,
        "height": 320,
        "url": "http://media.voog.com/0000/0000/0001/photos/img_block.jpg"
      },
      {
        "content_type": "image/jpeg",
        "width": 948,
        "height": 506,
        "url": "http://media.voog.com/0000/0000/0001/photos/img.jpg"
      }
    ]
  },
  "variant_types": [
    {
      "id": 2,
      "name": "Color",
      "translations": {
        "name": {"en": "Color", "et": "Värv"}
      },
      "values": [
        {
          "id": 3,
          "name": "Blue",
          "translations": {
            "name": {"en": "Blue", "et": "Sinine"}
          }
        },
        {
          "id": 4,
          "name": "Red",
          "translations": {
            "name": {"en": "Red", "et": "Punane"}
          }
        }
      ]
    }
  ],
  "variants": [
    {
      "id": 6,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Blue",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 3
        }
      ]
    }, {
      "id": 7,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Red",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 4
        }
      ]
    }
  ],
  "translations": {
    "name": {
      "en": "Product (en)", "et": "Product (et)"
    },
    "slug": {
      "en": "product-en", "et": "product-et"
    },
    "description": {
      "en": "Product description", "et": "Tootekirjeldus"
    }
  }
}

Parameters

  • price — Product price (without tax)
  • status — ('live' | 'draft') Product status
  • name — Product name in the current language context
  • slug — Product URL path suffix in the current language context
  • description — Product description in the current language context
  • stock — Product stock quantity as integer (e.g. 10). Set to null to turn of automatic stock management.
  • reserved_quantity — Booked quantity when stock management is turned on. It allows to correct the value.
  • sku — stock keeping unit identifier / product code
  • image_id — product image id (Asset ID)
  • variant_types — array of product variant type objects: {name, translations, values: [{name, translations}]}
  • category_ids — array of category IDs the product belongs to
  • translations — Read more about translations.

Get data for a single product

GET /admin/api/ecommerce/v1/products/5

This endpoint also allows anonymous access, returning live products only.

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/products/5?include=translations,variants&language_code=en

Example response:

Status: 200 OK

{
  "id": 5,
  "price": 21.0,
  "price_min": 21.0,
  "price_max": 21.0,
  "status": "live",
  "stock": null,
  "reserved_quantity": 0,
  "in_stock": true,
  "sku": null,
  "uses_variants": true,
  "variants_count": 2,
  "created_at": "2016-12-10T09:14:15.000Z",
  "updated_at": "2016-12-11T18:41:53.000Z",
  "name": "Product (en)",
  "slug": "product-en",
  "description": "Product description",
  "image_id": 88,
  "image": {
    "content_type": "image/jpeg",
    "width": 948,
    "height": 506,
    "url": "http://media.voog.com/0000/0000/0001/photos/img.jpg",
    "thumbnail": {
      "content_type": "image/jpeg",
      "width": 150,
      "height": 80,
      "url": "http://media.voog.com/0000/0000/0001/photos/img_medium.jpg"
    },
    "sizes": [
      {
        "content_type": "image/jpeg",
        "width": 600,
        "height": 320,
        "url": "http://media.voog.com/0000/0000/0001/photos/img_block.jpg"
      },
      {
        "content_type": "image/jpeg",
        "width": 948,
        "height": 506,
        "url": "http://media.voog.com/0000/0000/0001/photos/img.jpg"
      }
    ]
  },
  "variant_types": [
    {
      "id": 2,
      "name": "Color",
      "translations": {
        "name": {"en": "Color", "et": "Värv"}
      },
      "values": [
        {
          "id": 3,
          "name": "Blue",
          "translations": {
            "name": {"en": "Blue", "et": "Sinine"}
          }
        },
        {
          "id": 4,
          "name": "Red",
          "translations": {
            "name": {"en": "Red", "et": "Punane"}
          }
        }
      ]
    }
  ],
  "variants": [
    {
      "id": 6,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Blue",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 3
        }
      ]
    }, {
      "id": 7,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Red",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 4
        }
      ]
    }
  ],
  "translations": {
    "name": {
      "en": "Product (en)", "et": "Product (et)"
    },
    "slug": {
      "en": "product-en", "et": "product-et"
    },
    "description": {
      "en": "Product description", "et": "Tootekirjeldus"
    }
  }
}

Update attributes of a product

PUT /admin/api/ecommerce/v1/products/1

This request updates the page with provided attributes. It generates a new list of product variants if the variant_types array changes

Example request:

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/products/5?include=variants,translations&language_code=en

Example data:

{
  "name": "Product",
  "slug": "product",
  "description": "Product description",
  "variant_types": [
    {
      "id": 2,
      "name": "Color",
      "translations": {
        "name": {"en": "Color", "et": "Värv"}
      },
      "values": [
        {
          "id": 3,
          "name": "Blue",
          "translations": {
            "name": {"en": "Blue", "et": "Sinine"}
          }
        },
        {
          "id": 4,
          "name": "Red",
          "translations": {
            "name": {"en": "Red", "et": "Punane"}
          }
        },
        {
          "name": "Green",
          "translations": {
            "name": {"en": "Green", "et": "Roheline"}
          }
        }
      ]
    }
  ],
  "category_ids": [14556, 32321, 11679],
  "translations": {
    "name": {"en": "Product", "et": "Product (et)"},
    "slug": {"en": "product", "et": "product-et"},
    "description": {"en": "Product description", "et": "Tootekirjeldus" }
  }
}

Example response:

Status: 200 OK

{
  "id": 5,
  "price": 21.0,
  "price_min": 21.0,
  "price_max": 21.0,
  "status": "live",
  "stock": null,
  "reserved_quantity": 0,
  "in_stock": true,
  "sku": null,
  "uses_variants": true,
  "variants_count": 2,
  "created_at": "2016-12-10T09:14:15.000Z",
  "updated_at": "2016-12-11T18:41:53.000Z",
  "name": "Product",
  "slug": "product",
  "description": "Product description",
  "variant_types": [
    {
      "id": 2,
      "name": "Color",
      "translations": {
        "name": {"en": "Color", "et": "Värv"}
      },
      "values": [
        {
          "id": 3,
          "name": "Blue",
          "translations": {
            "name": {"en": "Blue", "et": "Sinine"}
          }
        },
        {
          "id": 4,
          "name": "Red",
          "translations": {
            "name": {"en": "Red", "et": "Punane"}
          }
        },
        {
          "id": 5,
          "name": "Green",
          "translations": {
            "name": {"en": "Green", "et": "Roheline"}
          }
        }
      ]
    }
  ],
  "variants": [
    {
      "id": 6,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Blue",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 3
        }
      ]
    }, {
      "id": 7,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Red",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 4
        }
      ]
    }, {
      "id": 8,
      "price": null,
      "status": "live",
      "stock": null,
      "reserved_quantity": 0,
      "in_stock": true,
      "sku": null,
      "created_at": "2017-03-22T12:47:44.000Z",
      "updated_at": "2017-03-22T12:53:07.000Z",
      "variant_attributes_text": "Color: Green",
      "variant_attributes": [
        {
          "type_id": 2,
          "value_id": 5
        }
      ]
    }
  ],
  "translations": {
    "name": {
      "en": "Product (en)", "et": "Product (et)"
    },
    "slug": {
      "en": "product", "et": "product-et"
    },
    "description": {
      "en": "Product description", "et": "Tootekirjeldus"
    }
  }
}

Remove a product

DELETE /admin/api/ecommerce/v1/products/5

This request deletes the product and all its variants (if any) from the database.

Example request:

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products/5

Example response:

Status: 204 No Content