Product Categories API

Manage product categories to organize your catalog effectively.

Categories help customers browse and discover products in your store. You can create hierarchical category structures, customize visibility, and filter products by category using the Products API.

Use Cases

Store Navigation: Create categories like "Electronics", "Clothing", "Home & Garden"
Product Filtering: Allow customers to browse products by category
Inventory Organization: Group related products for easier management

Endpoints

Method	Endpoint	Description
`GET`	`/business/product-category/list`	List all categories
`POST`	`/business/product-category/create`	Create a category
`PATCH`	`/business/product-category/update/:id`	Update a category

Retrieve all product categories.

http

GET /business/product-category/list

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	10	Items per page (max: 100)
`status`	string	-	Filter by status: `active`, `draft`, `archived`

Example Request

cURLJavaScriptPHPPython

bash

curl -X GET "https://api.cashfin.africa/business/product-category/list" \
  -H "Authorization: cs_your_client_secret"

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/product-category/list",
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

const data = await response.json();

php

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/product-category/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: cs_your_client_secret"
  ],
]);

$response = curl_exec($curl);
$data = json_decode($response, true);

python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/product-category/list',
    headers={'Authorization': 'cs_your_client_secret'}
)

data = response.json()

Example Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f191e810c19729de860ea",
      "title": "Electronics",
      "description": "Electronic devices and accessories",
      "status": "active",
      "parentid": null,
      "active": true,
      "createdat": "2024-01-10T08:00:00.000Z",
      "updatedat": "2024-01-15T10:30:00.000Z"
    },
    {
      "_id": "507f191e810c19729de860eb",
      "title": "Smartphones",
      "description": "Mobile phones and accessories",
      "status": "active",
      "parentid": "507f191e810c19729de860ea",
      "active": true,
      "createdat": "2024-01-11T09:00:00.000Z",
      "updatedat": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "pages": 2
  }
}

Create Category

Create a new product category.

http

POST /business/product-category/create

Request Body

Field	Type	Required	Description
`title`	string	Yes	Category name (must be unique)
`description`	string	No	Category description
`parentid`	string	No	Parent category ID for nested categories
`status`	string	No	Status: `active`, `draft`, or `archived` (default: `active`)
`imageurl`	string	No	URL to category image

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/product-category/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home Appliances",
    "description": "Kitchen and home appliances",
    "status": "active"
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/product-category/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Home Appliances",
      description: "Kitchen and home appliances",
      status: "active",
    }),
  }
);

const data = await response.json();

php

<?php
$curl = curl_init();

$data = [
  'title' => 'Home Appliances',
  'description' => 'Kitchen and home appliances',
  'status' => 'active'
];

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/product-category/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($data),
  CURLOPT_HTTPHEADER => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

python

import requests

data = {
    'title': 'Home Appliances',
    'description': 'Kitchen and home appliances',
    'status': 'active'
}

response = requests.post(
    'https://api.cashfin.africa/business/product-category/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json=data
)

result = response.json()

Example Response

json

{
  "success": true,
  "message": "Category created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Home Appliances",
    "description": "Kitchen and home appliances",
    "status": "active"
  }
}

Duplicate Title Error

If a category with the same title already exists:

json

{
  "success": false,
  "error": "Category with this title already exists"
}

Create Nested Category

Create a subcategory under a parent category.

Example Request

bash

curl -X POST "https://api.cashfin.africa/business/product-category/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blenders",
    "description": "Kitchen blenders and mixers",
    "parentid": "507f191e810c19729de860ea",
    "status": "active"
  }'

Example Response

json

{
  "success": true,
  "message": "Category created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439012",
    "title": "Blenders",
    "description": "Kitchen blenders and mixers",
    "parentid": "507f191e810c19729de860ea",
    "status": "active"
  }
}

Update Category

Update an existing category.

http

PATCH /business/product-category/update/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Category ID (MongoDB ObjectID)

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`title`	string	Category name
`description`	string	Category description
`parentid`	string	Parent category ID
`status`	string	Status: `active`, `draft`, `archived`

Example Request

cURLJavaScript

bash

curl -X PATCH "https://api.cashfin.africa/business/product-category/update/507f1f77bcf86cd799439011" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for home appliances",
    "status": "active"
  }'

javascript

const categoryId = "507f1f77bcf86cd799439011";

const response = await fetch(
  `https://api.cashfin.africa/business/product-category/update/${categoryId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Updated description for home appliances",
      status: "active",
    }),
  }
);

const data = await response.json();

Example Response

json

{
  "success": true,
  "message": "Category updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "modified": 1
  }
}

No Changes Made

If the update doesn't change any fields:

json

{
  "success": true,
  "message": "No changes made to category",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "modified": 0
  }
}

Error Responses

Category Not Found

json

{
  "success": false,
  "error": "Category not found"
}

Invalid Category ID

json

{
  "success": false,
  "error": "Invalid category ID format"
}

Validation Error

json

{
  "success": false,
  "error": "Title is required"
}

Category Object Reference

Field	Type	Description
`_id`	string	Unique category identifier
`title`	string	Category name
`description`	string	Category description
`parentid`	string	Parent category ID (for nested categories)
`status`	string	`active`, `draft`, or `archived`
`active`	boolean	Whether category is active
`sourceorigin`	string	Origin of creation (`api`, `dashboard`)
`createdat`	string	ISO 8601 creation timestamp
`updatedat`	string	ISO 8601 last update timestamp

Use Cases

Build Category Tree

javascript

async function buildCategoryTree() {
  const response = await fetch(
    "https://api.cashfin.africa/business/product-category/list",
    {
      headers: { Authorization: API_KEY },
    }
  );

  const { data: categories } = await response.json();

  // Group by parent
  const tree = [];
  const lookup = {};

  categories.forEach((cat) => {
    lookup[cat._id] = { ...cat, children: [] };
  });

  categories.forEach((cat) => {
    if (cat.parentid && lookup[cat.parentid]) {
      lookup[cat.parentid].children.push(lookup[cat._id]);
    } else {
      tree.push(lookup[cat._id]);
    }
  });

  return tree;
}

Sync Categories from External System

javascript

async function syncCategories(externalCategories) {
  for (const category of externalCategories) {
    try {
      await fetch(
        "https://api.cashfin.africa/business/product-category/create",
        {
          method: "POST",
          headers: {
            Authorization: API_KEY,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            title: category.name,
            description: category.description,
            status: "active",
          }),
        }
      );
    } catch (error) {
      // Handle duplicate title errors
      if (error.message.includes("already exists")) {
        console.log(`Category "${category.name}" already exists, skipping...`);
      }
    }
  }
}

Product Categories API ​

Endpoints ​

List Categories ​

Query Parameters ​

Example Request ​

Example Response ​

Create Category ​

Request Body ​

Example Request ​

Example Response ​

Duplicate Title Error ​

Create Nested Category ​

Example Request ​

Example Response ​

Update Category ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

No Changes Made ​

Error Responses ​

Category Not Found ​

Invalid Category ID ​

Validation Error ​

Category Object Reference ​

Use Cases ​

Build Category Tree ​

Sync Categories from External System ​

Product Categories API

Endpoints

List Categories

Query Parameters

Example Request

Example Response

Create Category

Request Body

Example Request

Example Response

Duplicate Title Error

Create Nested Category

Example Request

Example Response

Update Category

Path Parameters

Request Body

Example Request

Example Response

No Changes Made

Error Responses

Category Not Found

Invalid Category ID

Validation Error

Category Object Reference

Use Cases

Build Category Tree

Sync Categories from External System