expenses

Stable. Describes behaviour that is built and covered by tests in this repository.

GET `/v1/expenses` #

The expenses the tenant recorded, newest first

A recurring expense is one entry, listed at its first day. Voided expenses are left out unless include_voided is true.

Parameters

Name	In	Type	Description
`category`	query	ExpenseCategory
`app_id`	query	string · uuid
`currency`	query	string
`from`	query	string · date	Only entries whose (first) day is on or after this day
`to`	query	string · date	Only entries whose (first) day is on or before this day
`include_voided`	query	boolean
`page_size`	query	integer
`page_token`	query	string

Responses

Status	Meaning	Body
`200`	OK	ExpensePage
`400`	Error envelope	Error

Example response

{
  "expenses": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "app_id": "string",
      "vendor": "string",
      "category": "infrastructure",
      "amount_minor": "string",
      "currency": "string",
      "incurred_on": "string",
      "note": "string",
      "recurring": "none",
      "recurring_until": "string",
      "void_time": "2026-11-03T10:15:00Z",
      "void_reason": "string",
      "create_time": "2026-11-03T10:15:00Z",
      "update_time": "2026-11-03T10:15:00Z",
      "tax_minor": "string",
      "attachment_asset_id": "string"
    }
  ],
  "next_page_token": "string"
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/expenses \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/expenses` #

Record an expense

Money the tenant spent, in one currency. A monthly or yearly expense is one entry that falls on the same day of every month or year from incurred_on (on the last day of a shorter month) until recurring_until; its occurrences are worked out when a summary is asked for.

Request body

Field	Type	Description
`vendor` required	string
`category` required	ExpenseCategory
`amount_minor` required	string · int64	int64 minor units, above zero (a number is accepted too)
`currency` required	string
`incurred_on` required	string · date	The day, or the first day of a recurring expense (UTC)
`note`	string
`app_id`	string · uuid	The app of the account the cost belongs to; leave out for the whole tenant
`recurring`	`none` \| `monthly` \| `yearly`
`recurring_until`	string · date	Last day an occurrence may fall on; leave out for no end. Only for a recurring expense.
`tax_minor`	string · int64	The tax inside amount_minor, when the receipt shows it (informational; no summary reads it)
`attachment_asset_id`	string · uuid	The receipt or invoice kept with the expense: a READY general asset of the tenant

Example

{
  "vendor": "string",
  "category": "infrastructure",
  "amount_minor": "string",
  "currency": "string",
  "incurred_on": "string"
}

Responses

Status	Meaning	Body
`201`	Created	Expense
`400`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "app_id": "string",
  "vendor": "string",
  "category": "infrastructure",
  "amount_minor": "string",
  "currency": "string",
  "incurred_on": "string",
  "note": "string",
  "recurring": "none",
  "recurring_until": "string",
  "void_time": "2026-11-03T10:15:00Z",
  "void_reason": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "update_time": "2026-11-03T10:15:00Z",
  "tax_minor": "string",
  "attachment_asset_id": "string"
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/expenses \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendor":"string","category":"infrastructure","amount_minor":"string","currency":"string","incurred_on":"string"}'

PUT `/v1/expenses/{id}` #

Replace an expense

The body replaces the whole record; a recurring expense changes in all its occurrences. A voided expense is not edited (billing.accounting.expense_voided).

Parameters

Name	In	Type	Description
`id` required	path	string · uuid

Request body

Field	Type	Description
`vendor` required	string
`category` required	ExpenseCategory
`amount_minor` required	string · int64	int64 minor units, above zero (a number is accepted too)
`currency` required	string
`incurred_on` required	string · date	The day, or the first day of a recurring expense (UTC)
`note`	string
`app_id`	string · uuid	The app of the account the cost belongs to; leave out for the whole tenant
`recurring`	`none` \| `monthly` \| `yearly`
`recurring_until`	string · date	Last day an occurrence may fall on; leave out for no end. Only for a recurring expense.
`tax_minor`	string · int64	The tax inside amount_minor, when the receipt shows it (informational; no summary reads it)
`attachment_asset_id`	string · uuid	The receipt or invoice kept with the expense: a READY general asset of the tenant

Example

{
  "vendor": "string",
  "category": "infrastructure",
  "amount_minor": "string",
  "currency": "string",
  "incurred_on": "string"
}

Responses

Status	Meaning	Body
`200`	OK	Expense
`400`	Error envelope	Error
`404`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "app_id": "string",
  "vendor": "string",
  "category": "infrastructure",
  "amount_minor": "string",
  "currency": "string",
  "incurred_on": "string",
  "note": "string",
  "recurring": "none",
  "recurring_until": "string",
  "void_time": "2026-11-03T10:15:00Z",
  "void_reason": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "update_time": "2026-11-03T10:15:00Z",
  "tax_minor": "string",
  "attachment_asset_id": "string"
}

curl

curl -X PUT https://YOUR-API-ADDRESS/v1/expenses/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendor":"string","category":"infrastructure","amount_minor":"string","currency":"string","incurred_on":"string"}'

DELETE `/v1/expenses/{id}` #

Void an expense

The expense is not deleted: it leaves every summary and keeps its reason. The reason (1 to 200 characters) comes in the body {"reason": "..."} or in ?reason=.

Parameters

Name	In	Type	Description
`id` required	path	string · uuid
`reason`	query	string

Request body

Field	Type	Description
`reason` required	string

Example

{
  "reason": "string"
}

Responses

Status	Meaning	Body
`200`	OK	Expense
`400`	Error envelope	Error
`404`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "app_id": "string",
  "vendor": "string",
  "category": "infrastructure",
  "amount_minor": "string",
  "currency": "string",
  "incurred_on": "string",
  "note": "string",
  "recurring": "none",
  "recurring_until": "string",
  "void_time": "2026-11-03T10:15:00Z",
  "void_reason": "string",
  "create_time": "2026-11-03T10:15:00Z",
  "update_time": "2026-11-03T10:15:00Z",
  "tax_minor": "string",
  "attachment_asset_id": "string"
}

curl

curl -X DELETE https://YOUR-API-ADDRESS/v1/expenses/<id> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

Models

Error

Field	Type	Description
`error` required	object

Expense

Field	Type	Description
`id` required	string · uuid
`app_id` required	string
`vendor` required	string
`category` required	ExpenseCategory
`amount_minor` required	string · int64
`currency` required	string
`incurred_on` required	string · date
`note` required	string
`recurring` required	`none` \| `monthly` \| `yearly`
`recurring_until` required	string
`void_time` required	string · date-time
`void_reason` required	string
`create_time` required	string · date-time
`update_time` required	string · date-time
`tax_minor` required	string · int64
`attachment_asset_id` required	string

ExpenseCategory

ExpenseInput

Field	Type	Description
`vendor` required	string
`category` required	ExpenseCategory
`amount_minor` required	string · int64	int64 minor units, above zero (a number is accepted too)
`currency` required	string
`incurred_on` required	string · date	The day, or the first day of a recurring expense (UTC)
`note`	string
`app_id`	string · uuid	The app of the account the cost belongs to; leave out for the whole tenant
`recurring`	`none` \| `monthly` \| `yearly`
`recurring_until`	string · date	Last day an occurrence may fall on; leave out for no end. Only for a recurring expense.
`tax_minor`	string · int64	The tax inside amount_minor, when the receipt shows it (informational; no summary reads it)
`attachment_asset_id`	string · uuid	The receipt or invoice kept with the expense: a READY general asset of the tenant

ExpensePage

Field	Type	Description
`expenses` required	array of Expense
`next_page_token` required	string

VoidExpenseRequest

Field	Type	Description
`reason` required	string

expenses

GET /v1/expenses #

Parameters

Responses

POST /v1/expenses #

Request body

Responses

PUT /v1/expenses/{id} #

Parameters

Request body

Responses

DELETE /v1/expenses/{id} #

Parameters

Request body

Responses

Models

Error

Expense

ExpenseCategory

ExpenseInput

ExpensePage

VoidExpenseRequest

GET `/v1/expenses` #

POST `/v1/expenses` #

PUT `/v1/expenses/{id}` #

DELETE `/v1/expenses/{id}` #