Product Categories API: Organize Your Shop Catalog

Categories help you organize your products so staff can find them quickly at the point of sale and customers can browse them on your storefront. Each shop maintains its own category tree, and you can create unlimited subcategories by linking a category to a parent_id.

Create a category

POST /api/v1/shops/{shop_id}/categories/ Creates a new category in the specified shop. To create a top-level category, omit parent_id. To create a subcategory, pass the ID of an existing category in the same shop as parent_id.

Request body

string

required

The display name of the category in the primary language.

string

default:"\"\""

The Arabic name of the category. Used in bilingual storefronts. Leave blank if you do not need Arabic labels.

integer

ID of the parent category, creating a subcategory relationship. Omit or pass null to create a top-level category.

curl -X POST https://api.mutasib.com/api/v1/shops/42/categories/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dairy & Eggs",
    "name_ar": "الألبان والبيض",
    "parent_id": null
  }'

Returns 201 Created with a CategoryOut object.

GET /api/v1/shops/{shop_id}/categories Returns the full category tree for the shop. Top-level categories are returned as root objects, and each category includes a children array containing its subcategories, recursively nested.

curl https://api.mutasib.com/api/v1/shops/42/categories \
  -H "Authorization: Bearer <your_token>"

Returns 200 OK with an array of top-level CategoryOut objects, each with a nested children array.

[
  {
    "id": 10,
    "shop_id": 42,
    "name": "Dairy & Eggs",
    "name_ar": "الألبان والبيض",
    "parent_id": null,
    "is_active": true,
    "created_at": "2024-03-15T09:00:00Z",
    "children": [
      {
        "id": 11,
        "shop_id": 42,
        "name": "Milk",
        "name_ar": "حليب",
        "parent_id": 10,
        "is_active": true,
        "created_at": "2024-03-15T09:05:00Z",
        "children": []
      }
    ]
  }
]

Update a category

PATCH /api/v1/shops/{shop_id}/categories/{category_id}/ Partially updates a category. You can rename it, add or update the Arabic name, reassign its parent, or toggle its active status.

string

Updated display name.

string

Updated Arabic name.

integer | null

Updated parent category ID. Pass null to promote the category to the top level.

boolean

Set to false to hide the category and all its products from the storefront.

curl -X PATCH https://api.mutasib.com/api/v1/shops/42/categories/10/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dairy, Eggs & Cheese"
  }'

Returns 200 OK with the updated CategoryOut object.

Delete a category

DELETE /api/v1/shops/{shop_id}/categories/{category_id}/ Permanently deletes the category. Products currently assigned to this category will have their category_id set to null — they are not deleted.

curl -X DELETE https://api.mutasib.com/api/v1/shops/42/categories/11/ \
  -H "Authorization: Bearer <your_token>"

Returns 204 No Content on success.

Deleting a parent category also removes all of its subcategories. Products assigned to the deleted categories are not deleted but will become uncategorized.

CategoryOut fields

integer

Unique numeric identifier for the category.

integer

ID of the shop this category belongs to.

string

Display name of the category in the primary language.

string

Arabic display name of the category.

integer | null

ID of the parent category, or null if this is a top-level category.

boolean

Whether this category is currently active and visible.

array

Nested array of child CategoryOut objects. Empty array if the category has no subcategories.

string

ISO 8601 timestamp of when the category was created.

Shops

Products

Sales & Inventory

Public & Misc

Product Categories API: Organize Your Shop Catalog

Create a category

Request body

Update a category

Delete a category

CategoryOut fields

​Create a category

​Request body

​List categories

​Update a category

​Delete a category

​CategoryOut fields

Create a category

Request body

List categories

Update a category

Delete a category

CategoryOut fields