Expenses API

Name: Vantage PSA
Price: 49 USD
Author: Vantage

Expenses track costs incurred on behalf of clients—software subscriptions, travel, materials, and more. Expenses can be marked up and added to invoices.

The Expense Object

{
  "id": "exp_cuid123456",
  "client_id": "cli_xxxxx",
  "project_id": "prj_xxxxx",
  "user_id": "usr_xxxxx",
  "date": "2026-01-20",
  "description": "Adobe Creative Cloud - January",
  "category": "software",
  "vendor": "Adobe",
  "amount": 54.99,
  "currency": "USD",
  "billing": {
    "billable": true,
    "billed": false,
    "markup_percent": 15,
    "billable_amount": 63.24,
    "invoice_line_id": null
  },
  "receipt": {
    "url": "https://storage.govantage.co/receipts/...",
    "filename": "adobe-jan-2026.pdf"
  },
  "approval": {
    "status": "approved",
    "approved_by_id": "usr_yyyyy",
    "approved_at": "2026-01-21T10:00:00Z"
  },
  "notes": "Monthly subscription for design team",
  "created_at": "2026-01-20T14:30:00Z",
  "updated_at": "2026-01-21T10:00:00Z"
}

Expense Fields

Field	Type	Description
`id`	string	Unique identifier (prefix: `exp_`)
`client_id`	string	Associated client
`project_id`	string	Associated project
`user_id`	string	Who submitted the expense
`date`	date	Required. Expense date
`description`	string	Required. What the expense is for
`category`	string	Expense category
`vendor`	string	Vendor name
`amount`	decimal	Required. Expense amount
`currency`	string	Currency code (default: workspace currency)
`billing`	object	Billing configuration
`receipt`	object	Attached receipt
`approval`	object	Approval status
`notes`	string	Internal notes
`created_at`	datetime	When created
`updated_at`	datetime	When last updated

Expense Categories

Category	Description
`software`	Software and subscriptions
`hosting`	Hosting and infrastructure
`travel`	Travel expenses
`meals`	Meals and entertainment
`supplies`	Office supplies
`equipment`	Equipment purchases
`contractor`	Contractor/freelancer fees
`advertising`	Advertising spend
`other`	Other expenses

Approval Status

Status	Description
`pending`	Awaiting approval
`approved`	Approved for billing
`rejected`	Rejected

List Expenses

GET/v1/expensesList all expenses

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max: 100)
`client_id`	string		Filter by client
`project_id`	string		Filter by project
`user_id`	string		Filter by submitter
`category`	string		Filter by category
`from`	date		Expense date from
`to`	date		Expense date to
`billable`	boolean		Filter by billable status
`billed`	boolean		Filter by billed status
`approval_status`	string		`pending`, `approved`, `rejected`

Request

curl "https://api.govantage.co/v1/expenses?client_id=cli_xxxxx&billable=true&billed=false" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "exp_cuid123456",
      "client_id": "cli_xxxxx",
      "client_name": "Acme Corporation",
      "project_id": "prj_xxxxx",
      "project_title": "Website Redesign",
      "date": "2026-01-20",
      "description": "Adobe Creative Cloud - January",
      "category": "software",
      "amount": 54.99,
      "billing": {
        "billable": true,
        "billed": false,
        "billable_amount": 63.24
      },
      "approval": {
        "status": "approved"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 23
  },
  "summary": {
    "total_amount": 1250.00,
    "billable_amount": 1437.50,
    "pending_approval": 3
  }
}

Create an Expense

POST/v1/expensesCreate a new expense

Request Body

Field	Type	Required	Description
`date`	date	Yes	Expense date
`description`	string	Yes	Expense description
`amount`	decimal	Yes	Amount
`client_id`	string	No	Client ID
`project_id`	string	No	Project ID
`category`	string	No	Category
`vendor`	string	No	Vendor name
`billable`	boolean	No	Is billable (default: true)
`markup_percent`	decimal	No	Markup percentage
`notes`	string	No	Internal notes
`receipt_url`	string	No	URL to receipt file

Request

curl -X POST "https://api.govantage.co/v1/expenses" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-01-20",
    "description": "Adobe Creative Cloud - January",
    "amount": 54.99,
    "client_id": "cli_xxxxx",
    "project_id": "prj_xxxxx",
    "category": "software",
    "vendor": "Adobe",
    "billable": true,
    "markup_percent": 15
  }'

Upload Receipt

POST/v1/expenses/:id/receiptUpload a receipt

curl -X POST "https://api.govantage.co/v1/expenses/exp_cuid123456/receipt" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -F "file=@receipt.pdf"

Response

{
  "data": {
    "id": "exp_cuid123456",
    "receipt": {
      "url": "https://storage.govantage.co/receipts/...",
      "filename": "receipt.pdf",
      "uploaded_at": "2026-01-25T10:30:00Z"
    }
  }
}

Approve Expense

POST/v1/expenses/:id/approveApprove an expense

curl -X POST "https://api.govantage.co/v1/expenses/exp_cuid123456/approve" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Reject Expense

POST/v1/expenses/:id/rejectReject an expense

curl -X POST "https://api.govantage.co/v1/expenses/exp_cuid123456/reject" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Missing receipt - please resubmit with documentation"
  }'

Mark as Billed

POST/v1/expenses/mark-billedMark expenses as billed

Used when creating invoices outside Vantage.

curl -X POST "https://api.govantage.co/v1/expenses/mark-billed" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "expense_ids": ["exp_xxxxx", "exp_yyyyy"],
    "invoice_reference": "External Invoice #1234"
  }'

Expense Report

GET/v1/expenses/reportGet expense summary report

curl "https://api.govantage.co/v1/expenses/report?from=2026-01-01&to=2026-01-31&group_by=category" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "period": {
      "from": "2026-01-01",
      "to": "2026-01-31"
    },
    "totals": {
      "count": 45,
      "amount": 5250.00,
      "billable_amount": 6037.50,
      "markup_amount": 787.50
    },
    "by_category": [
      { "category": "software", "count": 12, "amount": 650.00 },
      { "category": "hosting", "count": 8, "amount": 2400.00 },
      { "category": "travel", "count": 5, "amount": 1200.00 }
    ]
  }
}

Webhooks

Event	Description
`expense.created`	Expense submitted
`expense.approved`	Expense approved
`expense.rejected`	Expense rejected
`expense.billed`	Expense added to invoice

Next Steps

Invoices API - Bill expenses to clients
Projects API - Track project expenses