Categories

Summary of category endpoints

• GET /admin/api/ecommerce/v1/categories - list all available categories for the current site.
• POST /admin/api/ecommerce/v1/categories - create a new category for the current site.
• GET /admin/api/ecommerce/v1/categories/1 - get data of a single category.
• PUT /admin/api/ecommerce/v1/categories/1 - update a category.
• DELETE /admin/api/ecommerce/v1/categories/1 - remove a category.

To add products into categories and remove them from categories, the following endpoints can be used:

• PUT /admin/api/ecommerce/v1/categories/1/products - add products to category.
• DELETE /admin/api/ecommerce/v1/categories/1/products - remove products from category.

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

• include — enhance the response objects (e.g. include=subcategories,translations). Supported values are:
  • subcategories — includes subcategories.
  • products — includes products assigned to categories.
  • 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/categories?include=subcategories

This endpoint also allows anonymous access returning only live categories.

Example response:

Status: 200 OK

[
  {
    "id": 1,
    "name": "Bikes",
    "slug": "bikes",
    "parent_id": null,
    "depth": 0,
    "created_at": "2021-10-26T12:48:40.000Z",
    "updated_at": "2021-11-01T09:10:30.000Z",
    "subcategories": [
      {
        "id": 3,
        "name": "City Bikes",
        "slug": "city-bikes",
        "parent_id": 1,
        "created_at": "2021-10-27T07:25:24.000Z",
        "updated_at": "2021-11-01T09:22:32.000Z",
        "subcategories": []
      }
    ]
  },
  {
    "id": 2,
    "name": "Campaign",
    "slug": "campaign",
    "parent_id": null,
    "depth": 0,
    "created_at": "2021-10-26T13:00:21.000Z",
    "updated_at": "2021-11-01T09:14:29.000Z",
    "subcategories": []
  }
]

Filter attributes

Read more about filters.

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

Parameters

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

Create new category

POST /admin/api/ecommerce/v1/categories

Example data:

{
  "category": {
    "name": "City Bikes",
    "slug": "city-bikes",
    "translations": {
      "name": {
        "en": "City Bikes",
        "et": "Linnarattad"
      },
      "slug": {
        "en": "city-bikes",
        "et": "linnarattad"
      }
    }
  }
}

Example response:

Status: 201 Created

{
  "id": 3,
  "name": "City Bikes",
  "slug": "city-bikes",
  "parent_id": null,
  "depth": 0,
  "created_at": "2021-10-27T07:25:24.000Z",
  "updated_at": "2021-11-01T09:22:32.691Z",
  "translations": {
    "name": {
      "en": "City Bikes",
      "et": "Linnarattad"
    },
    "slug": {
      "en": "city-bikes",
      "et": "linnarattad"
    }
  }
}

Parameters

• name — category name.
• slug — category address.
• translations — Read more about translations.

Get data for a single category

GET /admin/api/ecommerce/v1/categories/1

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

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/categories/1?include=translations&language_code=en

Example response:

Status: 200 OK

{
  "id": 1,
  "name": "Bikes",
  "slug": "bikes",
  "parent_id": null,
  "depth": 0,
  "created_at": "2021-10-26T12:48:40.000Z",
  "updated_at": "2021-11-01T09:10:30.000Z",
  "subcategories": [
    {
      "id": 3,
      "name": "City Bikes",
      "slug": "city-bikes",
      "parent_id": 1,
      "depth": 1,
      "created_at": "2021-10-27T07:25:24.000Z",
      "updated_at": "2021-11-01T09:22:32.000Z",
      "subcategories": [],
      "translations": {
        "name": {
          "en": "City Bikes",
          "et": "Linnarattad"
        },
        "slug": {
          "en": "city-bikes",
          "et": "linnarattad"
        }
      }
    }
  ],
  "translations": {
    "name": {
      "en": "Bikes",
      "et": "Jalgrattad"
    },
    "slug": {
      "en": "bikes",
      "et": "jalgrattad"
    }
  }
}

Update attributes of a category

PUT /admin/api/ecommerce/v1/categories/1

Example request:

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/categories/3?include=subcategories,translations&language_code=en

Example data:

{
  "category": {
    "name": "City Bikes",
    "slug": "city-bikes",
    "translations": {
      "name": {
        "en": "City Bikes",
        "et": "Linnarattad"
      },
      "slug": {
        "en": "city-bikes",
        "et": "linnarattad"
      }
    }
  }
}

Example response:

Status: 200 OK

{
  "id": 3,
  "name": "City Bikes",
  "slug": "city-bikes",
  "parent_id": null,
  "depth": 0,
  "created_at": "2021-10-27T07:25:24.000Z",
  "updated_at": "2021-11-01T09:22:32.691Z",
  "translations": {
    "name": {
      "en": "City Bikes",
      "et": "Linnarattad"
    },
    "slug": {
      "en": "city-bikes",
      "et": "linnarattad"
    }
  }
}

Remove a category

DELETE /admin/api/ecommerce/v1/categories/3

This request deletes the category, all its subcategories and associations with products.

Example request:

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

Example response:

Status: 204 No Content

Add products to category

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

This request adds products with provided ids to category. Please note that the order of products is determined by the order of the product ID-s in the list.

Example request:

PUT http://helloworld.voog.co/admin/api/ecommerce/v1/categories/3/products?include=products

Example data:

{
  "category": {
    "product_ids": [1]
  }
}

Example response:

Status: 200 OK

{
  "id": 3,
  "name": "City Bikes",
  "slug": "city-bikes",
  "parent_id": null,
  "depth": 0,
  "created_at": "2021-10-27T07:25:24.000Z",
  "updated_at": "2021-11-01T09:22:32.000Z",
  "products": [
    {
      "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",
      "description": "Product description"
    }
  ],
}

Parameters

Required parameters:

• product_ids - array of products that should be added to category (e.g. [1, 2, 3]).

Remove products from category

DELETE /admin/api/ecommerce/v1/categories/1/products

Removes products with given ID-s from category.

Example request:

DELETE http://helloworld.voog.co/admin/api/ecommerce/v1/categories/3/products

Example data:

{
  "category": {
    "product_ids": [2, 3]
  }
}

Example response:

Status: 200 OK

{
  "id": 3,
  "name": "City Bikes",
  "slug": "city-bikes",
  "parent_id": null,
  "depth": 0,
  "created_at": "2021-10-27T07:25:24.000Z",
  "updated_at": "2021-11-01T09:22:32.000Z",
  "products": [
    {
      "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",
      "description": "Product description"
    }
  ],
}