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.
  • 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,
    "status": "live",
    "stock": 10,
    "reserved_quantity": 1,
    "in_stock": true,
    "sku": "0001",
    "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"
  }, {
    "id": 2,
    "price": 166.67,
    "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": "Sample product",
    "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 product attributes: id, name, sku, price, 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)",
    "sku": "0004",
    "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": [],
    "translations": {
      "name": {
        "en": "Product (en)", "et": "Product (et)"
      }
    }
  }
}

Example response:

Status: 201 Created

{
  "id": 5,
  "price": 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)",
  "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
        }
      ]
    }
  ]
}

Parameters

  • price - Product price (without tax)
  • status - ('live' | 'draft') Product status
  • name - Product name 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 tock quantity when stock management is turned on. It allows to correct the value.
  • sku - stock keeping unit identifier / product code
  • variant_types - array of product variant type objects: {name, translations, values: [{name, translations}]}
  • 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,
  "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)",
  "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
        }
      ]
    }
  ]
}

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",
  "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"}
          }
        }
      ]
    }
  ],
  "translations": {
    "name": {"en": "Product", "et": "Product (et)"}
  }
}

Example response:

Status: 200 OK

{
  "id": 5,
  "price": 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",
  "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
        }
      ]
    }
  ]
}

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