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"
    }
  }
}

Products bulk update

Apply requested updates to all requested main products in query (target_ids). This endpoint also supports filter parameters to narrow down the list of products to be updated.

When update of some product fails then other products are still updated and the response contains the error details.

Example request:

PUT /admin/api/ecommerce/v1/products

{
  "actions": [
    {
      "target_field": "price",
      "action": "increase_by_percent",
      "value": 10,
      "source_field": "price"
    },
    {
      "target_field": "price",
      "action": "round_upwards",
      "value": 2
    },
    {
      "target_field": "status",
      "action": "set",
      "value": "live"
    },
    {
      "target_field": "stock",
      "action": "increase_by_fixed",
      "value": 10
    },
    {
      "target_field": "category_ids",
      "action": "merge",
      "value": [1, 2]
    }
  ],
  "target_ids": [1, 2, 3]
}

Example response:

Status: 200 OK

{
  "counters": {
    "processed": 3,
    "failed": 0
  },
  "processed_ids": [
    1, 2, 3
  ],
  "failed_ids": []
}

Example payload error response:

Status: 400 Bad Request

{
  "errors": {
    "payload": {
      "actions": [
        {
          "index": 0,
          "errors": [
            {
              "target_field": "action_not_supported"
            }
          ]
        }
      ],
      "target_ids": "empty"
    }
  }
}

Example items error response:

Status: 409 Conflict

{
  "counters": {
    "processed": 0,
    "failed": 1
  },
  "processed_ids": [],
  "failed_ids": [
    999
  ],
  "errors": {
    "items": [
      {
        "id": 999,
        "errors": {
          "category_ids": [
            "not_found"
          ]
        }
      }
    ]
  }
}

Parameters

  • actions – array of actions to apply to products (required);
    • target_field - field to update (required).
    • source_field - optional field name to use as source for the action. If not specified, the field itself is used as source.
    • action – the action to perform on the field (required), one of:
    • set – set the field to the given value. source_field value is copied to target_field when value is not specified or is blank.
    • increase_by_fixed – increase the field by the given value.
    • decrease_by_fixed – decrease the field by the given value.
    • increase_by_percent – increase the field by the given value percent.
    • decrease_by_percent – decrease the field by the given value percent.
    • round – round the field to the nearest decimal place given by value where value is any positive or negative integer (e.g value: 0, 11.2545 => 11.0; value: 1, 11.2545 => 11.3; value: -1, 11.2545 => 10.0).
    • round_upwards – round the field up to the nearest decimal place given by value where value is any positive or negative integer (e.g value: 0, 11.2545 => 12.0; value: 1, 11.2545 => 11.3; value: -1, 11.2545 => 20.0).
    • round_downwards – round the field down to the nearest decimal place given by value where value is any positive or negative integer (e.g value: 0, 11.2545 => 11.0; value: 1, 11.2545 => 11.2; value: -1, 11.2545 => 10.0).
    • merge – merge values to the field. value must be an array of values to merge.
    • remove – remove values from the field. value must be an array of values to remove.
    • value – the value to use by the action (required). It can be a number, string or array depending on the action:
    • any type – supported in set action.
    • number – decimal or integer, supported in increase_by_fixed, decrease_by_fixed, increase_by_percent, decrease_by_percent, round, round_upwards and round_downwards actions.
    • array – supported in merge and remove actions.
    • integer – positive or negative integer, supported in round, round_upwards and round_downwards actions.
  • target_ids – array of product ids to apply the actions to or string all to apply to all products (required).

Note: Action is skipped if the source_field value is null (except for set, merge and remove actions).

Supported target_field and source_field values by action:

Action category_ids price reserved_quantity status stock
set ✔️ ✔️ ✔️ ✔️ ✔️
increase_by_fixed ✔️ ✔️ ✔️
decrease_by_fixed ✔️ ✔️ ✔️
increase_by_percent ✔️ ✔️ ✔️
decrease_by_percent ✔️ ✔️ ✔️
round ✔️ ✔️ ✔️
round_upwards ✔️ ✔️ ✔️
round_downwards ✔️ ✔️ ✔️
merge ✔️
remove ✔️

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

Products bulk delete

This request deletes all main products and all its variants (if any) requested in query (target_ids).

This endpoint also supports filter parameters to narrow down the list of products to be deleted.

Parameters

  • target_ids – array of product ids to apply the actions to or string "all" to apply to all products (required). Can be provided as a query parameter or in the request body:

    • as array (e.g. ?target_ids[]=1&target_ids[]=2)
    • or as comma separated (e.g. ?target_ids=1,2)
    • or as request body parameter (e.g. {"target_ids": [1, 2]}).

Example request 1:

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

Example data 1:

{
  "target_ids": [1, 2, 3]
}

Example data 2:

{
  "target_ids": "all"
}

Example request 2:

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/products?target_ids=1,2,3

Example response:

Status: 204 No Content