Bills API

Record and manage vendor bills programmatically.

The Bills API lets you create payable records when you receive invoices from suppliers. Bills track what you owe to vendors and their payment status, feeding directly into your accounts payable workflow.

Use Cases

• AP Automation: Automatically record bills when vendor invoices arrive
• ERP Integration: Sync payables from your ERP into Cashfin
• Vendor Portal: Let vendors submit bills through your own interface

Endpoints

Method	Endpoint	Description
POST	/business/bill/create	Create a new bill
GET	/business/bill/list	List all bills
GET	/business/bill/details/:id	Get bill details

---

Create Bill

Record a new vendor bill.

POST /business/bill/create

Request Body

Field	Type	Required	Description
title	string	Yes	Bill title or description
amount	number	Yes	Total bill amount
billdate	string	Yes	Date of the bill (ISO 8601)
duedate	string	Yes	Payment due date (ISO 8601)
vendorid	string	No	Vendor ID to associate this bill with
description	string	No	Additional notes
status	string	No	Initial status (default: draft)
items	array	No	Line items (see Item Object below)

Item Object

Field	Type	Description
itemid	string	Product ID
name	string	Item name
quantity	integer	Quantity
rate	number	Price per unit

Example Request

cURL

curl -X POST "https://api.cashfin.africa/business/bill/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Office supplies - January",
    "amount": 12500.00,
    "billdate": "2024-01-10",
    "duedate": "2024-02-10",
    "vendorid": "507f1f77bcf86cd799439060",
    "description": "Stationery and printing supplies"
  }'

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/bill/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Office supplies - January",
      amount: 12500.0,
      billdate: "2024-01-10",
      duedate: "2024-02-10",
      vendorid: "507f1f77bcf86cd799439060",
      description: "Stationery and printing supplies",
    }),
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/bill/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'title'       => 'Office supplies - January',
    'amount'      => 12500.00,
    'billdate'    => '2024-01-10',
    'duedate'     => '2024-02-10',
    'vendorid'    => '507f1f77bcf86cd799439060',
    'description' => 'Stationery and printing supplies',
  ]),
  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/bill/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Office supplies - January',
        'amount': 12500.00,
        'billdate': '2024-01-10',
        'duedate': '2024-02-10',
        'vendorid': '507f1f77bcf86cd799439060',
        'description': 'Stationery and printing supplies',
    }
)

Success Response

{
  "success": true,
  "message": "Bill created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439080",
    "billno": "BILL-2024-001",
    "title": "Office supplies - January",
    "amount": 12500.0,
    "balance": 12500.0,
    "status": "draft",
    "billdate": "2024-01-10T00:00:00.000Z",
    "duedate": "2024-02-10T00:00:00.000Z",
    "sourceorigin": "api",
    "active": true,
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

---

List Bills

Retrieve a paginated list of bills.

GET /business/bill/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by title, bill number, or description
status	string	-	Filter by status: draft, approved, paid, partially_paid, rejected

Example Request

cURL

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

JavaScript

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439080",
      "billno": "BILL-2024-001",
      "title": "Office supplies - January",
      "amount": 12500.0,
      "balance": 12500.0,
      "status": "draft",
      "billdate": "2024-01-10T00:00:00.000Z",
      "duedate": "2024-02-10T00:00:00.000Z",
      "vendor_name": "Acme Supplies Ltd",
      "vendor_email": "[email protected]",
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "limit": 10,
    "pages": 1
  }
}

---

Get Bill Details

Retrieve full details of a specific bill, including vendor and account information.

GET /business/bill/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const billId = "507f1f77bcf86cd799439080";

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

Python

import requests

bill_id = '507f1f77bcf86cd799439080'

response = requests.get(
    f'https://api.cashfin.africa/business/bill/details/{bill_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439080",
    "billno": "BILL-2024-001",
    "title": "Office supplies - January",
    "amount": 12500.0,
    "balance": 12500.0,
    "tax": 0,
    "taxamount": 0,
    "discount": 0,
    "status": "draft",
    "description": "Stationery and printing supplies",
    "billdate": "2024-01-10T00:00:00.000Z",
    "duedate": "2024-02-10T00:00:00.000Z",
    "items": [],
    "vendor": {
      "_id": "507f1f77bcf86cd799439060",
      "name": "Acme Supplies Ltd",
      "email": "[email protected]",
      "phone": "+254700000001"
    },
    "account": null,
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

---

Error Responses

Bill Not Found

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

Invalid Date Format

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