Cashfin Business API

Appearance

Purchase Orders API ​

Create and manage purchase orders to vendors programmatically.

The Purchase Orders API lets you issue POs to vendors and track their fulfilment status. Purchase orders record what you intend to buy, at what price, and from which vendor — forming a clear paper trail before any bill is raised.

Use Cases

  • Procurement Systems: Issue POs from your ERP and track them in Cashfin
  • Approval Workflows: Create POs in draft status pending internal sign-off
  • Vendor Management: Send structured order requests to suppliers

Endpoints ​

MethodEndpointDescription
POST/business/purchase-order/createCreate a new purchase order
GET/business/purchase-order/listList all purchase orders
GET/business/purchase-order/details/:idGet purchase order details

Create Purchase Order ​

Issue a new purchase order.

http
POST /business/purchase-order/create

Request Body ​

FieldTypeRequiredDescription
titlestringYesPurchase order title or description
orderdatestringYesDate of the order (ISO 8601)
deliverydatestringYesExpected delivery date (ISO 8601)
vendoridstringNoVendor ID to associate this order with
descriptionstringNoAdditional notes
statusstringNoInitial status (default: draft)
itemsarrayNoLine items (see Item Object below)

Item Object ​

FieldTypeDescription
itemidstringProduct ID
namestringItem name
quantityintegerQuantity
ratenumberPrice per unit

Example Request ​

bash
curl -X POST "https://api.cashfin.africa/business/purchase-order/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q1 Office Equipment",
    "orderdate": "2024-01-10",
    "deliverydate": "2024-01-25",
    "vendorid": "507f1f77bcf86cd799439060",
    "description": "Monitors and keyboards for new hires",
    "items": [
      {
        "itemid": "507f1f77bcf86cd799439011",
        "name": "27-inch Monitor",
        "quantity": 5,
        "rate": 32000.00
      },
      {
        "itemid": "507f1f77bcf86cd799439012",
        "name": "Mechanical Keyboard",
        "quantity": 5,
        "rate": 8500.00
      }
    ]
  }'
javascript
const response = await fetch(
  "https://api.cashfin.africa/business/purchase-order/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Q1 Office Equipment",
      orderdate: "2024-01-10",
      deliverydate: "2024-01-25",
      vendorid: "507f1f77bcf86cd799439060",
      description: "Monitors and keyboards for new hires",
      items: [
        {
          itemid: "507f1f77bcf86cd799439011",
          name: "27-inch Monitor",
          quantity: 5,
          rate: 32000.0,
        },
        {
          itemid: "507f1f77bcf86cd799439012",
          name: "Mechanical Keyboard",
          quantity: 5,
          rate: 8500.0,
        },
      ],
    }),
  }
);
const data = await response.json();
php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/purchase-order/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'title'        => 'Q1 Office Equipment',
    'orderdate'    => '2024-01-10',
    'deliverydate' => '2024-01-25',
    'vendorid'     => '507f1f77bcf86cd799439060',
    'description'  => 'Monitors and keyboards for new hires',
    'items'        => [
      [
        'itemid'   => '507f1f77bcf86cd799439011',
        'name'     => '27-inch Monitor',
        'quantity' => 5,
        'rate'     => 32000.00,
      ],
      [
        'itemid'   => '507f1f77bcf86cd799439012',
        'name'     => 'Mechanical Keyboard',
        'quantity' => 5,
        'rate'     => 8500.00,
      ],
    ],
  ]),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$result = json_decode(curl_exec($curl), true);
python
import requests

response = requests.post(
    'https://api.cashfin.africa/business/purchase-order/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Q1 Office Equipment',
        'orderdate': '2024-01-10',
        'deliverydate': '2024-01-25',
        'vendorid': '507f1f77bcf86cd799439060',
        'description': 'Monitors and keyboards for new hires',
        'items': [
            {
                'itemid': '507f1f77bcf86cd799439011',
                'name': '27-inch Monitor',
                'quantity': 5,
                'rate': 32000.00,
            },
            {
                'itemid': '507f1f77bcf86cd799439012',
                'name': 'Mechanical Keyboard',
                'quantity': 5,
                'rate': 8500.00,
            },
        ],
    }
)

Success Response ​

json
{
  "success": true,
  "message": "Purchase order created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439090",
    "pono": "PO-2024-001",
    "title": "Q1 Office Equipment",
    "amount": 202500.0,
    "status": "draft",
    "orderdate": "2024-01-10T00:00:00.000Z",
    "deliverydate": "2024-01-25T00:00:00.000Z",
    "sourceorigin": "api",
    "active": true,
    "createdat": "2024-01-10T09:00:00.000Z"
  }
}

List Purchase Orders ​

Retrieve a paginated list of purchase orders.

http
GET /business/purchase-order/list

Query Parameters ​

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger10Results per page (max: 100)
searchstring-Search by title, PO number, or description
statusstring-Filter by status: draft, sent, received, cancelled

Example Request ​

bash
curl -X GET "https://api.cashfin.africa/business/purchase-order/list?page=1&limit=10&status=sent" \
  -H "Authorization: cs_your_client_secret"
javascript
const response = await fetch(
  "https://api.cashfin.africa/business/purchase-order/list?page=1&limit=10",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();
python
import requests

response = requests.get(
    'https://api.cashfin.africa/business/purchase-order/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10, 'status': 'sent'}
)

Success Response ​

json
{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439090",
      "pono": "PO-2024-001",
      "title": "Q1 Office Equipment",
      "amount": 202500.0,
      "status": "sent",
      "orderdate": "2024-01-10T00:00:00.000Z",
      "deliverydate": "2024-01-25T00:00:00.000Z",
      "vendor_name": "Acme Supplies Ltd",
      "createdat": "2024-01-10T09:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "pages": 2
  }
}

Get Purchase Order Details ​

Retrieve full details of a specific purchase order, including vendor and line items.

http
GET /business/purchase-order/details/:id

Path Parameters ​

ParameterTypeRequiredDescription
idstringYesPurchase Order ID (MongoDB ObjectID)

Example Request ​

bash
curl -X GET "https://api.cashfin.africa/business/purchase-order/details/507f1f77bcf86cd799439090" \
  -H "Authorization: cs_your_client_secret"
javascript
const poId = "507f1f77bcf86cd799439090";

const response = await fetch(
  `https://api.cashfin.africa/business/purchase-order/details/${poId}`,
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();
python
import requests

po_id = '507f1f77bcf86cd799439090'

response = requests.get(
    f'https://api.cashfin.africa/business/purchase-order/details/{po_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response ​

json
{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439090",
    "pono": "PO-2024-001",
    "title": "Q1 Office Equipment",
    "amount": 202500.0,
    "tax": 0,
    "taxamount": 0,
    "discount": 0,
    "status": "sent",
    "description": "Monitors and keyboards for new hires",
    "orderdate": "2024-01-10T00:00:00.000Z",
    "deliverydate": "2024-01-25T00:00:00.000Z",
    "items": [
      {
        "itemid": "507f1f77bcf86cd799439011",
        "name": "27-inch Monitor",
        "quantity": 5,
        "rate": 32000.0
      },
      {
        "itemid": "507f1f77bcf86cd799439012",
        "name": "Mechanical Keyboard",
        "quantity": 5,
        "rate": 8500.0
      }
    ],
    "vendor": {
      "_id": "507f1f77bcf86cd799439060",
      "name": "Acme Supplies Ltd",
      "email": "[email protected]",
      "phone": "+254700000001"
    },
    "createdat": "2024-01-10T09:00:00.000Z",
    "updatedat": "2024-01-10T09:00:00.000Z"
  }
}

Purchase Order Statuses ​

StatusDescription
draftCreated, awaiting approval
sentSent to vendor
receivedGoods or services received
cancelledOrder cancelled

Error Responses ​

Purchase Order Not Found ​

json
{
  "success": false,
  "error": "Purchase order not found"
}

Invalid Date Format ​

json
{
  "success": false,
  "error": "Invalid orderdate format. Use ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ)"
}

Cashfin Business API Documentation

Copyright © 2024-2026 Cashfin Africa