Skip to main content

​
Overview

Cash expenses represent operational costs paid directly from the cash register, such as supplies, utilities, or maintenance. Each expense is linked to a cash session and can be paid via CASH, CARD, or TRANSFER. Expenses start as DRAFT and must be posted to affect session balance.

​
Create Cash Expense

POST /api/v1/cash-expenses

​
Request Body

​
cash_session_id
integer
required
Cash session ID
​
tender_type
string
required
Payment tender type: CASH, CARD, or TRANSFER
​
amount
number
required
Expense amount (0.01 to 999999.99)
​
category
string
required
Expense category (max 100 characters). Common values: SUPPLIES, MAINTENANCE, UTILITIES, MARKETING, OTHER
​
vendor
string
Vendor name (max 255 characters)
​
reference
string
Invoice or receipt reference (max 255 characters)
​
notes
string
Additional notes (max 1000 characters)
​
card_terminal_id
integer
Terminal ID (required when tender_type is CARD)
​
bank_account_id
integer
Bank account ID (required when tender_type is TRANSFER)
​
incurred_at
string
Expense date/time in ISO 8601 format. Defaults to current time if not provided.
​
meta
object
Additional metadata

​
Response

​
message
string
Success message
​
data
object
curl -X POST https://api.sushigo.local/api/v1/cash-expenses \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cash_session_id": 15,
    "tender_type": "CASH",
    "amount": 150.00,
    "category": "SUPPLIES",
    "vendor": "Office Depot",
    "reference": "INV-12345",
    "notes": "Office supplies purchase",
    "incurred_at": "2025-12-13T10:30:00-06:00",
    "meta": {
      "receipt_url": "https://example.com/receipt.pdf"
    }
  }'

{
  "message": "Expense created successfully",
  "data": {
    "id": 89,
    "cash_session_id": 15,
    "tender_type": "CASH",
    "amount": "150.0000",
    "category": "SUPPLIES",
    "vendor": "Office Depot",
    "reference": "INV-12345",
    "notes": "Office supplies purchase",
    "card_terminal_id": null,
    "bank_account_id": null,
    "incurred_at": "2025-12-13T16:30:00+00:00",
    "created_by": 5,
    "posted_by": null,
    "posted_at": null,
    "meta": {
      "receipt_url": "https://example.com/receipt.pdf"
    },
    "created_at": "2025-12-13T16:35:00+00:00",
    "updated_at": "2025-12-13T16:35:00+00:00",
    "cash_session": {
      "id": 15,
      "operating_date": "2025-12-13"
    },
    "card_terminal": null,
    "bank_account": null
  }
}

​
List Cash Expenses

GET /api/v1/cash-expenses

​
Query Parameters

​
cash_session_id
integer
Filter by cash session ID
​
category
string
Filter by expense category
​
tender_type
string
Filter by tender type: CASH, CARD, or TRANSFER
​
status
string
Filter by status: POSTED or DRAFT
​
date_from
string
Filter from date (ISO 8601)
​
date_to
string
Filter to date (ISO 8601)
​
sort_by
string
default:"incurred_at"
Sort field
​
sort_order
string
default:"desc"
Sort order: asc or desc
​
per_page
integer
default:"15"
Items per page

​
Response

Returns paginated list of expenses with session, terminal, bank account, and user information. 
curl https://api.sushigo.local/api/v1/cash-expenses?cash_session_id=15&category=SUPPLIES \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "current_page": 1,
  "data": [
    {
      "id": 89,
      "cash_session_id": 15,
      "tender_type": "CASH",
      "amount": "150.0000",
      "category": "SUPPLIES",
      "vendor": "Office Depot",
      "reference": "INV-12345",
      "incurred_at": "2025-12-13T16:30:00+00:00",
      "posted_at": null,
      "cash_session": {
        "id": 15,
        "cash_register": {
          "id": 1,
          "code": "REG-001"
        }
      },
      "created_by": {
        "id": 5,
        "name": "Juan Pérez"
      }
    },
    {
      "id": 90,
      "tender_type": "CARD",
      "amount": "85.50",
      "category": "SUPPLIES",
      "vendor": "Costco",
      "card_terminal": {
        "id": 1,
        "name": "Terminal CLIP 1"
      }
    }
  ],
  "per_page": 15,
  "total": 2
}

​
Get Cash Expense

GET /api/v1/cash-expenses/{id}

​
Path Parameters

​
id
integer
required
Cash expense ID

​
Response

​
data
object
Expense details with session, terminal, bank account, and user information

​
Update Cash Expense

Only DRAFT expenses can be updated. Posted expenses are immutable.
PUT /api/v1/cash-expenses/{id}

​
Path Parameters

​
id
integer
required
Cash expense ID

​
Request Body

​
tender_type
string
Payment tender type
​
amount
number
Expense amount
​
category
string
Expense category
​
vendor
string
Vendor name
​
reference
string
Invoice/receipt reference
​
notes
string
Additional notes
​
card_terminal_id
integer
Terminal ID (required for CARD)
​
bank_account_id
integer
Bank account ID (required for TRANSFER)
​
incurred_at
string
Expense date/time
​
meta
object
Additional metadata

​
Response

​
message
string
Success message
​
data
object
Updated expense object
curl -X PUT https://api.sushigo.local/api/v1/cash-expenses/89 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 175.00,
    "notes": "Office supplies - updated amount"
  }'

​
Post Cash Expense

Finalizes the expense by marking it as posted. Once posted, the expense affects the session balance calculation and cannot be modified or deleted.
POST /api/v1/cash-expenses/{id}/post

​
Path Parameters

​
id
integer
required
Cash expense ID

​
Response

​
message
string
Success message
​
data
object
Posted expense with posted_at timestamp and posted_by user
curl -X POST https://api.sushigo.local/api/v1/cash-expenses/89/post \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "message": "Expense posted successfully",
  "data": {
    "id": 89,
    "cash_session_id": 15,
    "tender_type": "CASH",
    "amount": "150.0000",
    "category": "SUPPLIES",
    "posted_by": 5,
    "posted_at": "2025-12-13T19:00:00+00:00",
    "posted_by": {
      "id": 5,
      "name": "Juan Pérez"
    }
  }
}

​
Delete Cash Expense

Only DRAFT expenses can be deleted. Posted expenses are immutable.
DELETE /api/v1/cash-expenses/{id}

​
Path Parameters

​
id
integer
required
Cash expense ID

​
Response

​
message
string
Success message
curl -X DELETE https://api.sushigo.local/api/v1/cash-expenses/89 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "message": "Expense deleted successfully"
}

​
Common Expense Categories

SUPPLIES

Office supplies, cleaning products, consumables

MAINTENANCE

Equipment repairs, facility maintenance

UTILITIES

Electricity, water, gas, internet

MARKETING

Advertising, promotional materials

DELIVERY

Delivery service fees, fuel

OTHER

Miscellaneous operational expenses

​
Tender Type Rules

Each tender type has specific requirements:
  • CASH: Amount is deducted from cash drawer. No additional fields required.
  • CARD: Requires card_terminal_id to track which terminal processed the payment.
  • TRANSFER: Requires bank_account_id to track which bank account was used.

​
Workflow Example

1

Create Expense

Record expense with vendor, category, and payment method (DRAFT status)
2

Attach Receipt

Upload receipt/invoice to meta.receipt_url
3

Review

Manager reviews expense and verifies documentation
4

Post Expense

Post expense to finalize and include in session balance
5

Session Closing

When all expenses are posted, close the cash session

Build docs developers (and LLMs) love

Get started for freeTalk to us