iotoms Docs

Log an expense

POST
/api/v1/ops/day-cycles/{dayCycleId}/expenses

Records a field expense (fuel, tolls, food and so on) against an open day cycle. The signed-in user is recorded as the person who spent it and the expense starts as PENDING. Fails with 400 if the day cycle is already closed.

How to use it

  1. Get the open day cycle ID, for example from Get the active day cycle.
  2. Upload any receipt photo with Upload a file and keep its fileId for attachmentIds.
  3. Send category, amount, title, paymentMode and expenseDate. The expense is saved as PENDING for a manager to approve or reject.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

dayCycleId*string

Day cycle UUID

Formatuuid

Header Parameters

Request Body

application/json
  1. body
category*string

Required. Type of expense: FUEL, VEHICLE_MAINTENANCE, TOLL_PARKING, FOOD_REFRESHMENT or MISCELLANEOUS.

Value in"FUEL""VEHICLE_MAINTENANCE""TOLL_PARKING""FOOD_REFRESHMENT""MISCELLANEOUS"
amount*number

Required. Expense amount in the merchant's currency; must be greater than zero.

title*string

Required. Short description of the expense, for example "Diesel refill".

vendorName?|

Optional. Where the money was spent.

receiptNumber?|

Optional. Receipt or bill number.

paymentMode*string

Required. How it was paid: CASH, CARD, DIGITAL_PAYMENT or REIMBURSEMENT.

Value in"CASH""CARD""DIGITAL_PAYMENT""REIMBURSEMENT"
expenseDate*string

Required. Date of the expense (YYYY-MM-DD).

Formatdate
gpsLat?|

Optional latitude where the expense happened.

Formatdouble
gpsLon?|

Optional longitude where the expense happened.

Formatdouble
notes?|

Optional free-text notes.

attachmentIds?array<>|

Optional IDs of files (for example receipt photos) uploaded first with Upload a file; use the returned fileId. They are stored with the expense but are not returned in the expense response.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when it worked, ERROR when it failed.

message*string

Short human-readable message describing the outcome, for example "Vendor created". Do not parse it.

data?

The expense as stored after the change.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/ops/day-cycles/497f6eca-6276-4993-bfeb-53cbbbba6f08/expenses' \  -H 'Content-Type: application/json' \  -d '{  "category": "FUEL",  "amount": 0,  "title": "string",  "paymentMode": "CASH",  "expenseDate": "2019-08-24"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc",    "dayCycleId": "bbed7a30-80be-4ccf-810d-a33c370a67d1",    "salesExecutiveId": "string",    "category": "FUEL",    "amount": 0,    "title": "string",    "vendorName": "string",    "receiptNumber": "string",    "paymentMode": "CASH",    "expenseDate": "2019-08-24",    "gpsLat": 0,    "gpsLon": 0,    "notes": "string",    "approvalStatus": "PENDING",    "approvedBy": "string",    "approvedAt": "2019-08-24T14:15:22Z",    "rejectionReason": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}