Expenses API

Record and retrieve business expenses programmatically.

The Expenses API allows you to log operating costs from external systems — travel management platforms, expense reporting tools, or corporate card integrations — and have them flow directly into your Cashfin financials.

Use Cases

• Expense Reporting Tools: Push approved expense claims into Cashfin automatically
• Travel Management: Sync travel bookings and costs when they are confirmed
• Card Integrations: Record transactions from corporate card feeds

Endpoints

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

---

Create Expense

Log a new business expense.

POST /business/expense/create

Request Body

Field	Type	Required	Description
title	string	Yes	Expense description
amount	number	Yes	Total expense amount
expensedate	string	Yes	Date of expense (ISO 8601)
description	string	No	Additional notes
vendorid	string	No	Vendor ID to associate this expense with
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/expense/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team lunch",
    "amount": 5000.00,
    "expensedate": "2024-01-15",
    "description": "Monthly team lunch meeting",
    "status": "approved"
  }'

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/expense/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Team lunch",
      amount: 5000.0,
      expensedate: "2024-01-15",
      description: "Monthly team lunch meeting",
      status: "approved",
    }),
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/expense/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'title'       => 'Team lunch',
    'amount'      => 5000.00,
    'expensedate' => '2024-01-15',
    'description' => 'Monthly team lunch meeting',
    'status'      => 'approved',
  ]),
  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/expense/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Team lunch',
        'amount': 5000.00,
        'expensedate': '2024-01-15',
        'description': 'Monthly team lunch meeting',
        'status': 'approved',
    }
)

Success Response

{
  "success": true,
  "message": "Expense created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439070",
    "title": "EXP-2024-001 - Team lunch",
    "amount": 5000.0,
    "status": "approved",
    "expensedate": "2024-01-15T00:00:00.000Z",
    "sourceorigin": "api",
    "active": true,
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

---

List Expenses

Retrieve a paginated list of expenses.

GET /business/expense/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 or description
status	string	-	Filter by status: draft, approved, paid, partially_paid, rejected

Example Request

cURL

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

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/expense/list?status=approved",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439070",
      "title": "EXP-2024-001 - Team lunch",
      "amount": 5000.0,
      "status": "approved",
      "expensedate": "2024-01-15T00:00:00.000Z",
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 30,
    "page": 1,
    "limit": 10,
    "pages": 3
  }
}

---

Get Expense Details

Retrieve full details of a specific expense.

GET /business/expense/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const expenseId = "507f1f77bcf86cd799439070";

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

Python

import requests

expense_id = '507f1f77bcf86cd799439070'

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

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439070",
    "title": "EXP-2024-001 - Team lunch",
    "amount": 5000.0,
    "tax": 0,
    "taxamount": 0,
    "discount": 0,
    "status": "approved",
    "description": "Monthly team lunch meeting",
    "expensedate": "2024-01-15T00:00:00.000Z",
    "items": [],
    "vendor": null,
    "account": null,
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

---

Error Responses

Expense Not Found

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

Invalid Date Format

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