API reference › Finance › Overview, clients and work items
Calculate finance preview
POST /v1/finance/calculate-preview
- Scope
finance:read- Roles
- admin, scheduler
Calculates and previews finance totals (invoices, pro-forma, payables, payment statements) including work item charges without creating the document. Applies the same paid-source zeroing as save (excludes billable entities already on a paid document for the same client/provider, or paid selected invoices/payables; duplicate-from-paid via source_document_id). Pass full_copy=true after reverse-and-cancel reissue to keep full charges (skips paid-source zeroing). When type is invoice and billable_entities include client-billed assignments or shifts, client_id is required; omit client_id for organization-billed-only previews (or set is_org_invoice=true). When type is payable and billable_entities include assignments or shifts, provider_id is required.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
20 top-level fields; 7 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
current_document_id | string or null | The document being edited, so its own lines are not counted twice against the work items it already bills. Example |
type required | string | Finance document type One of: |
source_document_id | string | Optional source document ID for duplication context. When the source is paid, preview zeroes amounts the same way as save. Example |
full_copy | boolean | When true (reverse-and-cancel reissue), skip paid-source zeroing so preview keeps full charges. Default false. Example |
line_items | array of object (6 nested) | Array of line items |
tax_type | object (2 nested) | Tax type |
tax_amount | number (float) | Tax amount Example |
discount_type | object (2 nested) | Discount type |
discount_amount | number (float) | Discount amount Example |
billable_entities | array of object or object | Billable entities. For type=payable use linkage rows only; pay fields go in billable_entities_pay_calc. |
billable_entities_pay_calc | array of object (8 nested) | Required for type=payable when billable_entities includes assignments/shifts. |
billable_entities_billing | array of object (9 nested) | Per work-item billing intent. billing_mode=bill enforces conflict checks on save; reference bypasses conflicts and zeros service charges on preview. |
is_org_invoice | boolean | Optional. Explicit organization summary invoice preview. When all billable work items are organization-billed, client_id may be omitted even without this flag. Example |
client_id | object (2 nested) | Required when type=invoice and billable_entities contain client-billed assignments or shifts. Omit for organization-billed-only previews. |
provider_id | object (2 nested) | Required when type=payable and billable_entities contain assignment or shift. |
payable_id | string or null | Optional for type=payable when editing; loads the stored admin fee snapshots and excludes this payable from billing_conflicts. Example |
invoice_id | string or null | Optional for type=invoice when editing; alias for id. Excludes this invoice from billing_conflicts. Example |
id | string or null | Optional document id when editing an existing invoice or payable. Excludes this document from billing_conflicts; when Canceled/Void, billing_conflicts is empty. Example |
has_changes | boolean | Edit only. false or omitted on the first preview of an existing document: updatedAt is its stored update time. true after the user changes the form: updatedAt is the current time. Ignored on add, where updatedAt is always the current time. Example |
payments_applied | number (float) | Optional. Payments applied (used for pro-forma / payment statement). Example |
Nested fields
line_items 6 fields
| Field | Type | Description |
|---|---|---|
line_items[].amount required | number (float) | Line item amount Example |
line_items[].name required | string | Line item name Example |
line_items[].description required | string | Line item description Example |
line_items[].type required | object | Line item type |
line_items[].type.id | string | Line item type ID Example |
line_items[].type.label | string | Line item type label Example |
tax_type 2 fields
| Field | Type | Description |
|---|---|---|
tax_type.id | string | Tax type ID Example |
tax_type.label | string | Tax type label Example |
discount_type 2 fields
| Field | Type | Description |
|---|---|---|
discount_type.id | string | Discount type ID Example |
discount_type.label | string | Discount type label Example |
billable_entities_pay_calc 8 fields
| Field | Type | Description |
|---|---|---|
billable_entities_pay_calc[].type required | string | One of: |
billable_entities_pay_calc[].id required | string | Example |
billable_entities_pay_calc[].pay_time_basis | string or null | One of: |
billable_entities_pay_calc[].hours_used_for_pay | number (float) or null | Example |
billable_entities_pay_calc[].pay_rate | number (float) or null | Example |
billable_entities_pay_calc[].services_charge | number (float) or null | Example |
billable_entities_pay_calc[].hours_override_reason | string or null | min length 3. |
billable_entities_pay_calc[].pay_rate_override_reason | string or null | min length 3. |
billable_entities_billing 9 fields
| Field | Type | Description |
|---|---|---|
billable_entities_billing[].id required | string | Example |
billable_entities_billing[].billing_mode | string | One of: |
billable_entities_billing[].bill_service | boolean | Example |
billable_entities_billing[].bill_expenses | boolean | Example |
billable_entities_billing[].bill_admin_fee | boolean | Example |
billable_entities_billing[].adminFeeBreakdown | object or null | Optional per-entity admin fee override. Omit or send feeSource=calculated with empty clients/providers to derive from live config. |
billable_entities_billing[].adminFeeBreakdown.feeSource | string | One of: |
billable_entities_billing[].adminFeeBreakdown.clients | array of object | |
billable_entities_billing[].adminFeeBreakdown.providers | array of object |
client_id 2 fields
| Field | Type | Description |
|---|---|---|
client_id.id | string | Client user ID Example |
client_id.label | string | Client display label Example |
provider_id 2 fields
| Field | Type | Description |
|---|---|---|
provider_id.id | string | Provider user ID Example |
provider_id.label | string | Provider display label Example |
Example
{
"current_document_id": "INV-EWDM3W",
"type": "invoice",
"source_document_id": "INV-ABC123",
"full_copy": true,
"line_items": [
{
"amount": 150,
"name": "Consultation Fee",
"description": "Initial consultation service",
"type": {
"id": "charges",
"label": "Additional Charge"
}
}
],
"tax_type": {
"id": "Percentage",
"label": "Percentage"
},
"tax_amount": 15,
"discount_type": {
"id": "Fixed",
"label": "Fixed"
},
"discount_amount": 10,
"billable_entities": [
{
"type": "assignment",
"id": "ASG-M3PCU1"
}
],
"billable_entities_pay_calc": [
{
"type": "assignment",
"id": "ASG-M3PCU1",
"pay_time_basis": "scheduled_time",
"hours_used_for_pay": 4,
"pay_rate": 65,
"services_charge": 260,
"hours_override_reason": "string",
"pay_rate_override_reason": "string"
}
],
"billable_entities_billing": [
{
"id": "ASG-OYLEV4",
"billing_mode": "bill",
"bill_service": true,
"bill_expenses": true,
"bill_admin_fee": true,
"adminFeeBreakdown": {
"feeSource": "calculated",
"clients": [
{}
],
"providers": [
{}
]
}
}
],
"is_org_invoice": true,
"client_id": {
"id": "USR-12345",
"label": "Acme Corp"
},
"provider_id": {
"id": "SPR-67890",
"label": "Jane Provider"
},
"payable_id": "PAYB-ABC123",
"invoice_id": "INV-ABC123",
"id": "INV-ABC123",
"has_changes": false,
"payments_applied": 0
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/calculate-preview" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"current_document_id":"INV-EWDM3W","type":"invoice","source_document_id":"INV-ABC123","full_copy":true,"line_items":[{"amount":150,"name":"Consultation Fee","description":"Initial consultation service","type":{"id":"charges","label":"Additional Charge"}}],"tax_type":{"id":"Percentage","label":"Percentage"},"tax_amount":15,"discount_type":{"id":"Fixed","label":"Fixed"},"discount_amount":10,"billable_entities":[{"type":"assignment","id":"ASG-M3PCU1"}],"billable_entities_pay_calc":[{"type":"assignment","id":"ASG-M3PCU1","pay_time_basis":"scheduled_time","hours_used_for_pay":4,"pay_rate":65,"services_charge":260,"hours_override_reason":"string","pay_rate_override_reason":"string"}],"billable_entities_billing":[{"id":"ASG-OYLEV4","billing_mode":"bill","bill_service":true,"bill_expenses":true,"bill_admin_fee":true,"adminFeeBreakdown":{"feeSource":"calculated","clients":[{}],"providers":[{}]}}],"is_org_invoice":true,"client_id":{"id":"USR-12345","label":"Acme Corp"},"provider_id":{"id":"SPR-67890","label":"Jane Provider"},"payable_id":"PAYB-ABC123","invoice_id":"INV-ABC123","id":"INV-ABC123","has_changes":false,"payments_applied":0}'Try it
Responses
200 Finance preview calculated successfully
Finance preview calculated successfully
{
"success": true,
"message": "Finance preview calculated successfully.",
"data": {
"subtotal": 250,
"services_charges": 200,
"original_services_charges": 220,
"cancellation_services_charges": 140,
"original_payable_services_charges": 160,
"cancellation_payable_services_charges": 100,
"expenses_total": 35,
"total_admin_fee": 20,
"organization_admin_fee": 12,
"provider_admin_fee": 8,
"billable_entities_billing": [
{}
],
"tax_amount": 25,
"discount_amount": 12.5,
"total": 287.5,
"balance_due": 257.5,
"total_entities_count": 2,
"total_after_cancellation": 182,
"balance_due_after_cancellation": 182,
"original_balance_due": 232,
"total_payable_after_cancellation": 120,
"payable_balance_due_after_cancellation": 120,
"original_payable_balance_due": 170,
"work_item_service_breakdown": [
{
"label": "Standard Rate",
"hours": 4,
"rate": 25,
"cost": 100,
"billable_amount": 25,
"cancellation_fee": 25,
"original_cost": 100,
"charge_source": "cancellation_fee",
"rate_source": "provider_rate",
"rate_source_label": "Provider Pay Rate"
}
],
"entity_pay_metrics": [
{
"type": "assignment",
"id": "ASG-M3PCU1",
"pay_time_basis": "scheduled_actual_fallback",
"derived_hours_used_for_pay": 8,
"hours_used_for_pay": 8,
"is_hours_overridden": false,
"derived_pay_rate": 45,
"pay_rate": 45,
"is_pay_rate_overridden": false,
"services_charge": 260,
"pay_rate_breakdown": {
"base_rate": 45,
"base_hours": 8,
"rules_applied": [
null
],
"rate_lines": [
null
],
"summary": {
"total_hours": 8,
"total_service_charge": 382.5,
"effective_pay_rate": 47.81,
"line_count": 2
},
"effective_pay_rate": 46.67,
"total_service_charge": 360,
"source": "check_in",
"rate_source": "provider_rate",
"rate_source_label": "Provider Pay Rate",
"rate_source_description": "Driven by this provider's own custom pay rate configuration.",
"rate_source_is_mixed": false,
"rate_configuration": {
"source": null,
"label": "Default Pay Rate",
"description": "Driven by the organization default provider pay rate configuration.",
"is_mixed": false,
"rows": null
}
},
"rate_rules_suppressed": false,
"warning_message": "string",
"hours_override_reason": "string",
"pay_rate_override_reason": "string"
}
],
"billing_conflicts": [
{
"work_item_id": "ASG-OYLEV4",
"document_id": "INV-TOHWMO",
"document_type": "invoice",
"message": "ASG-OYLEV4 is already billed on Invoice INV-TOHWMO. Remove it or mark it as reference only."
}
],
"updatedAt": "07/31/2026 06:22 PM"
}
}Response fields (71)
3 top-level fields; 1 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object (68 nested) |
Nested fields
data 68 fields
| Field | Type | Description |
|---|---|---|
data.subtotal | number (float) | Finance subtotal Example |
data.services_charges | number (float) | Service-only charges. For type=payable, sum of per-entity service amounts (breakdown cost or hours×rate override per billable_entities[] item). Example |
data.original_services_charges | number (float) or null | Invoice preview comparison field. Sum of non-cancellation service charges across selected entities. Example |
data.cancellation_services_charges | number (float) or null | Invoice preview comparison field. Sum of cancellation fees across selected entities. Example |
data.original_payable_services_charges | number (float) or null | Payable preview comparison field. Sum using estimated pay basis. Example |
data.cancellation_payable_services_charges | number (float) or null | Payable preview comparison field. Sum using cancellation pay basis. Example |
data.expenses_total | number (float) | Expense-only total (invoice/payable contexts) Example |
data.total_admin_fee | number (float) | Combined admin fee total (invoice/proforma context) Example |
data.organization_admin_fee | number (float) | Sum of organization/scheduler admin fee across selected billable entities (invoice/proforma preview). Example |
data.provider_admin_fee | number (float) | Sum of service provider admin fee across selected billable entities (invoice/proforma preview). Example |
data.billable_entities_billing | array of object | Invoice/payable only. Per work-item billing intent with resolved adminFeeBreakdown. |
data.tax_amount | number (float) | Tax amount Example |
data.discount_amount | number (float) | Adjustment amount Example |
data.total | number (float) | Total amount Example |
data.balance_due | number (float) | Balance due Example |
data.total_entities_count | integer | Number of billable entities in the request Example |
data.total_after_cancellation | number (float) or null | Invoice preview total when cancellation basis is applied. Example |
data.balance_due_after_cancellation | number (float) or null | Invoice preview balance due when cancellation basis is applied. Example |
data.original_balance_due | number (float) or null | Invoice preview balance due using original non-cancellation service basis. Example |
data.total_payable_after_cancellation | number (float) or null | Payable preview total when cancellation pay basis is applied. Example |
data.payable_balance_due_after_cancellation | number (float) or null | Payable preview balance due when cancellation pay basis is applied. Example |
data.original_payable_balance_due | number (float) or null | Payable preview balance due using estimated pay basis. Example |
data.work_item_service_breakdown | array of object or null | Flattened service breakdown rows for selected entities. Each row includes |
data.work_item_service_breakdown[].label | string | Example |
data.work_item_service_breakdown[].hours | number (float) | Example |
data.work_item_service_breakdown[].rate | number (float) | Example |
data.work_item_service_breakdown[].cost | number (float) | Scheduled service math (rate × billable duration). Unchanged by cancellation. Example |
data.work_item_service_breakdown[].billable_amount | number (float) | What this row actually bills. Equals Example |
data.work_item_service_breakdown[].cancellation_fee | number (float) | This row's share of the client cancellation fee. Example |
data.work_item_service_breakdown[].original_cost | number (float) | Example |
data.work_item_service_breakdown[].charge_source | string | Example |
data.work_item_service_breakdown[].rate_source | string or null | Payable rows only. Which rate configuration the row's pay rate came from. One of: |
data.work_item_service_breakdown[].rate_source_label | string or null | Example |
data.entity_pay_metrics | array of object or null | Payable only. Per-assignment/shift pay calculation metrics. |
data.entity_pay_metrics[].type | string | One of: |
data.entity_pay_metrics[].id | string | Example |
data.entity_pay_metrics[].pay_time_basis | string | Example |
data.entity_pay_metrics[].derived_hours_used_for_pay | number (float) | Example |
data.entity_pay_metrics[].hours_used_for_pay | number (float) | Example |
data.entity_pay_metrics[].is_hours_overridden | boolean | Example |
data.entity_pay_metrics[].derived_pay_rate | number (float) | Example |
data.entity_pay_metrics[].pay_rate | number (float) | Example |
data.entity_pay_metrics[].is_pay_rate_overridden | boolean | Example |
data.entity_pay_metrics[].services_charge | number (float) | Example |
data.entity_pay_metrics[].pay_rate_breakdown | object or null | |
data.entity_pay_metrics[].pay_rate_breakdown.base_rate | number (float) | Example |
data.entity_pay_metrics[].pay_rate_breakdown.base_hours | number (float) | Example |
data.entity_pay_metrics[].pay_rate_breakdown.rules_applied | array of object | |
data.entity_pay_metrics[].pay_rate_breakdown.rate_lines | array of object | |
data.entity_pay_metrics[].pay_rate_breakdown.summary | object | |
data.entity_pay_metrics[].pay_rate_breakdown.effective_pay_rate | number (float) | Example |
data.entity_pay_metrics[].pay_rate_breakdown.total_service_charge | number (float) | Example |
data.entity_pay_metrics[].pay_rate_breakdown.source | string | Which time basis priced the lines — not where the rate came from; see rate_source. One of: |
data.entity_pay_metrics[].pay_rate_breakdown.rate_source | string or null | Which rate configuration drove this pay calculation. Null when the lines disagree (see rate_source_is_mixed) or nothing is stamped. One of: |
data.entity_pay_metrics[].pay_rate_breakdown.rate_source_label | string or null | Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'. Example |
data.entity_pay_metrics[].pay_rate_breakdown.rate_source_description | string or null | Example |
data.entity_pay_metrics[].pay_rate_breakdown.rate_source_is_mixed | boolean | True when the lines were priced from more than one rate configuration. Example |
data.entity_pay_metrics[].pay_rate_breakdown.rate_configuration | object or null | Which rate configuration drove this calculation — backs the 'Rate rules applied' expansion, and expands rate_source with the per-combination rows behind it. Read-only, derived from the estimated-pay-rate rows stamped at pricing time. Absent when the pay rate was overridden, and on documents whose work items have no stamped rows. |
data.entity_pay_metrics[].rate_rules_suppressed | boolean | Example |
data.entity_pay_metrics[].warning_message | string or null | |
data.entity_pay_metrics[].hours_override_reason | string or null | |
data.entity_pay_metrics[].pay_rate_override_reason | string or null | |
data.billing_conflicts | array of object | Soft conflicts when billable_entities_billing marks an entity as bill but it is already on another active document. |
data.billing_conflicts[].work_item_id | string | Example |
data.billing_conflicts[].document_id | string | Example |
data.billing_conflicts[].document_type | string | Example |
data.billing_conflicts[].message | string | Example |
data.updatedAt | string | On add, the current time. On the first preview of an existing document (has_changes false or omitted), its stored update time. After the user changes the form (has_changes true), the current time. In the organization's date and time format. Example |
401 Not signed in
Missing, invalid or expired API key.
{
"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
{
"success": false,
"message": "Validation failed",
"errors": {
"type": [
"Type is required."
]
}
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | object |
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
Unexpected error
{
"success": false,
"errors": "Finance preview failed",
"message": "An unexpected error occurred — please try again."
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
errors | string or null | Null in production. The exception message only when the application runs with debug on. Example |
message | string | Example |