API reference › Finance › Provider expenses
Preview calculated provider expense amount
POST /v1/finance/provider-expenses/calculate-preview
- Scope
finance:read- Roles
- admin, service-provider, scheduler
Read-only. Computes the suggested expense amount from the work item's expense settings and optional quantity or submitted cost, using the same calculation as submit. Does not persist any record. serviceProviderId is optional for category-first preview; when quantity or provider cannot be resolved, returns partial metadata (rate, cap, basis) with calculatedAmount 0 and quantityReason indicating what is still needed. For per_day, quantity may be omitted and is derived as whole billable days from work-item scheduled hours (under 24h = 1 day; 24h+ = ceil(hours/24)); manual quantity must be a positive whole number. For per_unit with unit mile, quantity may be omitted when serviceProviderId is sent and is derived as round-trip mileage. For per_unit use/session, quantity is required for full calculation. For flat_amount, quantity defaults to 1 when omitted. For percentage, amount is required for full calculation; without amount returns partial preview with calculatedAmount 0.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
| Field | Type | Description |
|---|---|---|
workItemId | string or null | Assignment (ASG-...) or shift id. Omit in add mode to resolve category from reimbursable_expenses catalog only. Example |
reimbursableExpenseId | integer or null | Reimbursable expense category id from settings; required unless sourceReimbursableExpense is sent Example |
sourceReimbursableExpense | object | Custom-from-category path. |
sourceReimbursableExpense.id | integer or string | Example |
sourceReimbursableExpense.label | string or null | Example |
serviceProviderId | string or null | Service provider user id; optional for category-first partial preview, required for mileage auto-quantity Example |
quantity | number (float) or null | Miles, days, uses, etc. Optional when auto-derived or for partial preview Example |
amount | number (float) or null | Submitted receipt/cost; required for full percentage calculation Example |
Example
{
"workItemId": "ASG-12345",
"reimbursableExpenseId": 10,
"sourceReimbursableExpense": {
"id": 1,
"label": "Example"
},
"serviceProviderId": "USR-67890",
"quantity": 50,
"amount": 120
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/provider-expenses/calculate-preview" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"workItemId":"ASG-12345","reimbursableExpenseId":10,"sourceReimbursableExpense":{"id":1,"label":"Example"},"serviceProviderId":"USR-67890","quantity":50,"amount":120}'Try it
Responses
200 Calculation preview
Calculation preview.
{
"success": true,
"message": "Calculation preview.",
"data": {
"calculatedAmount": 33.5,
"suggestedExpense": 33.5,
"reimbursementBasis": "per_unit",
"unit": "mile",
"unitRate": 0.67,
"quantity": 50,
"amount": 10,
"quantityReason": "not_applicable",
"servicePayBase": 120,
"capped": false,
"maximumCap": 100,
"reimbursableExpenseId": 10,
"name": "Mileage",
"expenseType": "travel",
"billTo": "organization",
"isReceiptRequired": true
}
}Response fields (19)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.calculatedAmount | number (float) | Example |
data.suggestedExpense | number (float) | Same as calculatedAmount; suggested final amount if submit omits expense override Example |
data.reimbursementBasis | string | One of: |
data.unit | string or null | null for flat_amount and percentage; mile/day/use/session for other bases Example |
data.unitRate | number (float) | Example |
data.quantity | number (float) or null | Defaults to 1 for per_unit/per_day when omitted and not auto-resolved; null for flat_amount and percentage Example |
data.amount | number (float) or null | Percentage only: category rate (same as unitRate). Request amount is receipt/cost input. Example |
data.quantityReason | string or null | Set for percentage without receipt (not_applicable); null when quantity was resolved or defaulted Example |
data.servicePayBase | number (float) or null | For percentage basis: submitted receipt/cost used in formula (same column as persist service_pay_base_used) Example |
data.capped | boolean | True when maximum_reimbursement_cap clamped a calculated non-percentage line total; false for percentage (cap enforced on submit receipt only) Example |
data.maximumCap | number (float) or null | Example |
data.reimbursableExpenseId | integer | Category template id Example |
data.name | string | Category name from snapshot or catalog Example |
data.expenseType | string or null | Category expense type from snapshot or catalog Example |
data.billTo | string or null | Submit-style bill-to; from category snapshot One of: |
data.isReceiptRequired | boolean | Whether receipt is required for this category Example |
401 Not signed in
Unauthorized
{
"success": false,
"message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
"errors": null,
"code": "API_KEY_MISSING"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
403 Not allowed
Scope, tenant, IP allow-list or RBAC check failed.
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope.",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Always empty on this status. Example |
422 Validation failed
Validation error (request validation, category not found, category not attached to work item, invalid snapshot basis)
{
"success": false,
"message": "Expense category is not attached to this work item."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
429 Too many requests
Rate limit exceeded. See Retry-After.
{
"success": false,
"message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
"errors": null,
"code": "RATE_LIMITED"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
500 Server error
Internal Server Error
{
"success": false,
"message": "Unable to calculate expense preview."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |