Products API

Manage your product catalog with the Products API. Create, update, list, and retrieve products programmatically.

The Products API supports multiple product types including physical products, digital services, and subscription plans. Each product can have pricing information, inventory tracking, images, and can be assigned to categories for better organization.

Use Cases

E-commerce Stores: Sync products from your inventory management system
SaaS Platforms: Create service plans and pricing tiers
Marketplaces: Enable vendors to manage their catalogs via API

Endpoints

Method	Endpoint	Description
`GET`	`/business/product/list`	List all products
`GET`	`/business/product/details/:id`	Get product details
`POST`	`/business/product/create`	Create a new product
`PATCH`	`/business/product/update/:id`	Update a product

List Products

Retrieve a paginated list of products.

http

GET /business/product/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: `published`, `draft`, `archived`
`type`	string	-	Filter by type: `product`, `service`, `plan`
`categoryid`	string	-	Filter by category ID

Example Request

cURLJavaScriptPHPPython

bash

curl -X GET "https://api.cashfin.africa/business/product/list?page=1&limit=10&status=published" \
  -H "Authorization: cs_your_client_secret"

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/product/list?page=1&limit=10&status=published",
  {
    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/list?page=1&limit=10&status=published",
  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/list',
    params={'page': 1, 'limit': 10, 'status': 'published'},
    headers={'Authorization': 'cs_your_client_secret'}
)

data = response.json()

Example Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Premium Widget",
      "description": "High-quality widget with advanced features",
      "price": 1999.99,
      "stock": 100,
      "sku": "WDG-001",
      "type": "product",
      "status": "published",
      "featured": true,
      "featuredimage": "https://cdn.cashfin.africa/images/widget.jpg",
      "categoryid": "507f191e810c19729de860ea",
      "variants": [],
      "createdat": "2024-01-15T10:30:00.000Z",
      "updatedat": "2024-01-16T14:45:00.000Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}

Get Product Details

Retrieve details of a specific product.

http

GET /business/product/details/:id

Path Parameters

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

Example Request

cURLJavaScript

bash

curl -X GET "https://api.cashfin.africa/business/product/details/507f1f77bcf86cd799439011" \
  -H "Authorization: cs_your_client_secret"

javascript

const productId = "507f1f77bcf86cd799439011";

const response = await fetch(
  `https://api.cashfin.africa/business/product/details/${productId}`,
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

const data = await response.json();

Example Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Premium Widget",
    "description": "High-quality widget with advanced features",
    "price": 1999.99,
    "stock": 100,
    "sku": "WDG-001",
    "type": "product",
    "status": "published",
    "featured": true,
    "featuredimage": "https://cdn.cashfin.africa/images/widget.jpg",
    "categoryid": "507f191e810c19729de860ea",
    "variants": [
      {
        "_id": "507f1f77bcf86cd799439012",
        "attributetitle": "Size",
        "valuetitle": "Large",
        "valueprice": 2199.99,
        "valuestock": 30,
        "active": true
      },
      {
        "_id": "507f1f77bcf86cd799439013",
        "attributetitle": "Size",
        "valuetitle": "Small",
        "valueprice": 1799.99,
        "valuestock": 70,
        "active": true
      }
    ],
    "active": true,
    "sourceorigin": "api",
    "createdat": "2024-01-15T10:30:00.000Z",
    "updatedat": "2024-01-16T14:45:00.000Z"
  }
}

Create Product

Create a new product in your catalog.

http

POST /business/product/create

Request Body

Field	Type	Required	Description
`title`	string	Yes	Product name
`description`	string	No	Product description
`price`	number	Yes	Base price (must be > 0)
`stock`	integer	No	Available quantity (default: 0)
`sku`	string	No	Stock Keeping Unit (auto-generated if not provided)
`type`	string	No	Product type: `product`, `service`, or `plan` (default: `product`)
`status`	string	No	Status: `published`, `draft`, or `archived` (default: `published`)
`featured`	boolean	No	Whether to feature this product (default: false)
`featuredimage`	string	No	URL to product image
`categoryid`	string	No	Category ID to assign the product
`variants`	array	No	Product variants (see below)

Variant Object

Field	Type	Required	Description
`attributetitle`	string	Yes	Attribute name (e.g., "Size", "Color")
`valuetitle`	string	Yes	Attribute value (e.g., "Large", "Blue")
`valueprice`	number	Yes	Price for this variant
`valuestock`	integer	Yes	Stock for this variant

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/product/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Widget Pro",
    "description": "Our best-selling widget with advanced features",
    "price": 2999.99,
    "stock": 50,
    "type": "product",
    "status": "published",
    "featured": true,
    "categoryid": "507f191e810c19729de860ea",
    "variants": [
      {
        "attributetitle": "Color",
        "valuetitle": "Blue",
        "valueprice": 2999.99,
        "valuestock": 25
      },
      {
        "attributetitle": "Color",
        "valuetitle": "Red",
        "valueprice": 3099.99,
        "valuestock": 25
      }
    ]
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/product/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Premium Widget Pro",
      description: "Our best-selling widget with advanced features",
      price: 2999.99,
      stock: 50,
      type: "product",
      status: "published",
      featured: true,
      categoryid: "507f191e810c19729de860ea",
      variants: [
        {
          attributetitle: "Color",
          valuetitle: "Blue",
          valueprice: 2999.99,
          valuestock: 25,
        },
        {
          attributetitle: "Color",
          valuetitle: "Red",
          valueprice: 3099.99,
          valuestock: 25,
        },
      ],
    }),
  }
);

const data = await response.json();

php

<?php
$curl = curl_init();

$data = [
  'title' => 'Premium Widget Pro',
  'description' => 'Our best-selling widget with advanced features',
  'price' => 2999.99,
  'stock' => 50,
  'type' => 'product',
  'status' => 'published',
  'featured' => true,
  'categoryid' => '507f191e810c19729de860ea',
  'variants' => [
    [
      'attributetitle' => 'Color',
      'valuetitle' => 'Blue',
      'valueprice' => 2999.99,
      'valuestock' => 25
    ]
  ]
];

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/product/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': 'Premium Widget Pro',
    'description': 'Our best-selling widget with advanced features',
    'price': 2999.99,
    'stock': 50,
    'type': 'product',
    'status': 'published',
    'featured': True,
    'categoryid': '507f191e810c19729de860ea',
    'variants': [
        {
            'attributetitle': 'Color',
            'valuetitle': 'Blue',
            'valueprice': 2999.99,
            'valuestock': 25
        }
    ]
}

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

result = response.json()

Example Response

json

{
  "success": true,
  "message": "Product created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Premium Widget Pro",
    "sku": "PRD-2024-001",
    "price": 2999.99,
    "stock": 50
  }
}

Update Product

Update an existing product.

http

PATCH /business/product/update/:id

Path Parameters

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

Request Body

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

Field	Type	Description
`title`	string	Product name
`description`	string	Product description
`price`	number	Base price
`stock`	integer	Available quantity
`sku`	string	Stock Keeping Unit
`type`	string	Product type
`status`	string	Product status
`featured`	boolean	Featured flag
`featuredimage`	string	Product image URL
`categoryid`	string	Category ID
`variants`	array	Product variants

Example Request

cURLJavaScript

bash

curl -X PATCH "https://api.cashfin.africa/business/product/update/507f1f77bcf86cd799439011" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 3499.99,
    "stock": 75,
    "status": "published"
  }'

javascript

const productId = "507f1f77bcf86cd799439011";

const response = await fetch(
  `https://api.cashfin.africa/business/product/update/${productId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      price: 3499.99,
      stock: 75,
      status: "published",
    }),
  }
);

const data = await response.json();

Example Response

json

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

Error Responses

Product Not Found

json

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

Invalid Product ID

json

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

Validation Error

json

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

Product Object Reference

Field	Type	Description
`_id`	string	Unique product identifier
`title`	string	Product name
`description`	string	Product description
`price`	number	Base price
`stock`	integer	Available quantity
`sku`	string	Stock Keeping Unit
`type`	string	`product`, `service`, or `plan`
`status`	string	`published`, `draft`, or `archived`
`featured`	boolean	Whether product is featured
`featuredimage`	string	Product image URL
`categoryid`	string	Associated category ID
`variants`	array	Product variants
`active`	boolean	Whether product is active
`sourceorigin`	string	Origin of creation (`api`, `dashboard`)
`createdat`	string	ISO 8601 creation timestamp
`updatedat`	string	ISO 8601 last update timestamp

Products API ​

Endpoints ​

List Products ​

Query Parameters ​

Example Request ​

Example Response ​

Get Product Details ​

Path Parameters ​

Example Request ​

Example Response ​

Create Product ​

Request Body ​

Variant Object ​

Example Request ​

Example Response ​

Update Product ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

Error Responses ​

Product Not Found ​

Invalid Product ID ​

Validation Error ​

Product Object Reference ​

Products API

Endpoints

List Products

Query Parameters

Example Request

Example Response

Get Product Details

Path Parameters

Example Request

Example Response

Create Product

Request Body

Variant Object

Example Request

Example Response

Update Product

Path Parameters

Request Body

Example Request

Example Response

Error Responses

Product Not Found

Invalid Product ID

Validation Error

Product Object Reference