Request Format

This guide explains how to structure your API requests to Cashfin.

Content Type

All API requests that include a body must use JSON format:

Content-Type: application/json

Request Structure

GET Requests

GET requests use query parameters for filtering and pagination:

GET /business/product/list?page=1&limit=10&status=published

POST Requests

POST requests include data in the request body:

POST /business/product/create
Content-Type: application/json

{
  "title": "Premium Widget",
  "price": 1999.99,
  "stock": 100
}

PATCH Requests

PATCH requests update specific fields of an existing resource:

PATCH /business/product/update/507f1f77bcf86cd799439011
Content-Type: application/json

{
  "price": 2499.99,
  "stock": 150
}

Data Types

String Fields

String fields should be UTF-8 encoded:

{
  "title": "Premium Widget",
  "description": "A high-quality widget with émojis 🎉"
}

Numeric Fields

• Integer: Whole numbers without decimals
• Float/Decimal: Numbers with decimals (prices, rates)

{
  "stock": 100,
  "price": 1999.99,
  "quantity": 5
}

Precision

Monetary values use 2 decimal places. Extra precision may be truncated.

Boolean Fields

Boolean values should be true or false (not strings):

{
  "featured": true,
  "active": false
}

Date/Time Fields

Dates should be in ISO 8601 format:

{
  "startDate": "2024-01-15T09:00:00Z",
  "endDate": "2024-12-31T23:59:59Z"
}

Object ID Fields

MongoDB ObjectIDs are 24-character hexadecimal strings:

{
  "categoryid": "507f1f77bcf86cd799439011",
  "customerid": "507f191e810c19729de860ea"
}

Array Fields

Arrays are used for collections of items:

{
  "variants": [
    {
      "attributetitle": "Size",
      "valuetitle": "Large",
      "valueprice": 2099.99,
      "valuestock": 25
    },
    {
      "attributetitle": "Size",
      "valuetitle": "Small",
      "valueprice": 1899.99,
      "valuestock": 50
    }
  ]
}

Common Request Headers

Header	Required	Description
Authorization	Yes	Your API key
Content-Type	Yes (POST/PATCH)	application/json
Idempotency-Key	No	Unique key for idempotent requests
X-Request-ID	No	Custom request identifier

Example: Complete Request

Here's a complete example of a POST request:

cURL

curl -X POST "https://api.cashfin.africa/business/product/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-product-$(date +%s)" \
  -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": "507f1f77bcf86cd799439011",
    "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: process.env.CASHFIN_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": `create-product-${Date.now()}`,
    },
    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: "507f1f77bcf86cd799439011",
      variants: [
        {
          attributetitle: "Color",
          valuetitle: "Blue",
          valueprice: 2999.99,
          valuestock: 25,
        },
      ],
    }),
  }
);

URL Parameters

Path Parameters

Path parameters are part of the URL path and are required:

PATCH /business/product/update/:id
                               ↑
                         Path parameter

Example:

PATCH /business/product/update/507f1f77bcf86cd799439011

Query Parameters

Query parameters are appended to the URL after ?:

GET /business/product/list?page=1&limit=10
                           ↑
                    Query parameters

Request Validation

The API validates all incoming requests. Invalid requests return a 400 Bad Request or 422 Unprocessable Entity:

{
  "success": false,
  "error": "There are problems with your submission",
  "errors": {
    "title": "Title is required",
    "price": "Price must be a positive number"
  }
}

See Error Handling for more details on handling validation errors.