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.

FieldTypeDescription
current_document_idstring or null

The document being edited, so its own lines are not counted twice against the work items it already bills.

Example INV-EWDM3W.

type requiredstring

Finance document type

One of: invoice, proforma, payable, payment_statement. Example invoice.

source_document_idstring

Optional source document ID for duplication context. When the source is paid, preview zeroes amounts the same way as save.

Example INV-ABC123.

full_copyboolean

When true (reverse-and-cancel reissue), skip paid-source zeroing so preview keeps full charges. Default false.

Example true.

line_itemsarray of object (6 nested)

Array of line items

tax_typeobject (2 nested)

Tax type

tax_amountnumber (float)

Tax amount

Example 15.

discount_typeobject (2 nested)

Discount type

discount_amountnumber (float)

Discount amount

Example 10.

billable_entitiesarray of object or object

Billable entities. For type=payable use linkage rows only; pay fields go in billable_entities_pay_calc.

billable_entities_pay_calcarray of object (8 nested)

Required for type=payable when billable_entities includes assignments/shifts.

billable_entities_billingarray 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_invoiceboolean

Optional. Explicit organization summary invoice preview. When all billable work items are organization-billed, client_id may be omitted even without this flag.

Example true.

client_idobject (2 nested)

Required when type=invoice and billable_entities contain client-billed assignments or shifts. Omit for organization-billed-only previews.

provider_idobject (2 nested)

Required when type=payable and billable_entities contain assignment or shift.

payable_idstring or null

Optional for type=payable when editing; loads the stored admin fee snapshots and excludes this payable from billing_conflicts.

Example PAYB-ABC123.

invoice_idstring or null

Optional for type=invoice when editing; alias for id. Excludes this invoice from billing_conflicts.

Example INV-ABC123.

idstring 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 INV-ABC123.

has_changesboolean

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 false.

payments_appliednumber (float)

Optional. Payments applied (used for pro-forma / payment statement).

Example 0.

Nested fields

line_items 6 fields
FieldTypeDescription
line_items[].amount requirednumber (float)

Line item amount

Example 150.

line_items[].name requiredstring

Line item name

Example Consultation Fee.

line_items[].description requiredstring

Line item description

Example Initial consultation service.

line_items[].type requiredobject

Line item type

line_items[].type.idstring

Line item type ID

Example charges.

line_items[].type.labelstring

Line item type label

Example Additional Charge.

tax_type 2 fields
FieldTypeDescription
tax_type.idstring

Tax type ID

Example Percentage.

tax_type.labelstring

Tax type label

Example Percentage.

discount_type 2 fields
FieldTypeDescription
discount_type.idstring

Discount type ID

Example Fixed.

discount_type.labelstring

Discount type label

Example Fixed.

billable_entities_pay_calc 8 fields
FieldTypeDescription
billable_entities_pay_calc[].type requiredstring

One of: assignment, shift. Example assignment.

billable_entities_pay_calc[].id requiredstring

Example ASG-M3PCU1.

billable_entities_pay_calc[].pay_time_basisstring or null

One of: scheduled_time, actual_worked_time, scheduled_actual_fallback.

billable_entities_pay_calc[].hours_used_for_paynumber (float) or null

Example 4.

billable_entities_pay_calc[].pay_ratenumber (float) or null

Example 65.

billable_entities_pay_calc[].services_chargenumber (float) or null

Example 260.

billable_entities_pay_calc[].hours_override_reasonstring or null

min length 3.

billable_entities_pay_calc[].pay_rate_override_reasonstring or null

min length 3.

billable_entities_billing 9 fields
FieldTypeDescription
billable_entities_billing[].id requiredstring

Example ASG-OYLEV4.

billable_entities_billing[].billing_modestring

One of: bill, reference. Example bill.

billable_entities_billing[].bill_serviceboolean

Example true.

billable_entities_billing[].bill_expensesboolean

Example true.

billable_entities_billing[].bill_admin_feeboolean

Example true.

billable_entities_billing[].adminFeeBreakdownobject 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.feeSourcestring

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.clientsarray of object
billable_entities_billing[].adminFeeBreakdown.providersarray of object
client_id 2 fields
FieldTypeDescription
client_id.idstring

Client user ID

Example USR-12345.

client_id.labelstring

Client display label

Example Acme Corp.

provider_id 2 fields
FieldTypeDescription
provider_id.idstring

Provider user ID

Example SPR-67890.

provider_id.labelstring

Provider display label

Example Jane Provider.

Example

JSON
{
  "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

Shell
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

JSON
{
  "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.

FieldTypeDescription
successboolean

Example true.

messagestring

Example Finance preview calculated successfully..

dataobject (68 nested)

Nested fields

data 68 fields
FieldTypeDescription
data.subtotalnumber (float)

Finance subtotal

Example 250.

data.services_chargesnumber (float)

Service-only charges. For type=payable, sum of per-entity service amounts (breakdown cost or hours×rate override per billable_entities[] item).

Example 200.

data.original_services_chargesnumber (float) or null

Invoice preview comparison field. Sum of non-cancellation service charges across selected entities.

Example 220.

data.cancellation_services_chargesnumber (float) or null

Invoice preview comparison field. Sum of cancellation fees across selected entities.

Example 140.

data.original_payable_services_chargesnumber (float) or null

Payable preview comparison field. Sum using estimated pay basis.

Example 160.

data.cancellation_payable_services_chargesnumber (float) or null

Payable preview comparison field. Sum using cancellation pay basis.

Example 100.

data.expenses_totalnumber (float)

Expense-only total (invoice/payable contexts)

Example 35.

data.total_admin_feenumber (float)

Combined admin fee total (invoice/proforma context)

Example 20.

data.organization_admin_feenumber (float)

Sum of organization/scheduler admin fee across selected billable entities (invoice/proforma preview).

Example 12.

data.provider_admin_feenumber (float)

Sum of service provider admin fee across selected billable entities (invoice/proforma preview).

Example 8.

data.billable_entities_billingarray of object

Invoice/payable only. Per work-item billing intent with resolved adminFeeBreakdown.

data.tax_amountnumber (float)

Tax amount

Example 25.

data.discount_amountnumber (float)

Adjustment amount

Example 12.5.

data.totalnumber (float)

Total amount

Example 287.5.

data.balance_duenumber (float)

Balance due

Example 257.5.

data.total_entities_countinteger

Number of billable entities in the request

Example 2.

data.total_after_cancellationnumber (float) or null

Invoice preview total when cancellation basis is applied.

Example 182.

data.balance_due_after_cancellationnumber (float) or null

Invoice preview balance due when cancellation basis is applied.

Example 182.

data.original_balance_duenumber (float) or null

Invoice preview balance due using original non-cancellation service basis.

Example 232.

data.total_payable_after_cancellationnumber (float) or null

Payable preview total when cancellation pay basis is applied.

Example 120.

data.payable_balance_due_after_cancellationnumber (float) or null

Payable preview balance due when cancellation pay basis is applied.

Example 120.

data.original_payable_balance_duenumber (float) or null

Payable preview balance due using estimated pay basis.

Example 170.

data.work_item_service_breakdownarray of object or null

Flattened service breakdown rows for selected entities. Each row includes charge_source (service_charge|cancellation_fee for invoice, estimated_pay|cancellation_pay for payable). Rows always describe the service as scheduled (cost = rate × billable duration), including for canceled work items; read billable_amount for the figure actually billed.

data.work_item_service_breakdown[].labelstring

Example Standard Rate.

data.work_item_service_breakdown[].hoursnumber (float)

Example 4.

data.work_item_service_breakdown[].ratenumber (float)

Example 25.

data.work_item_service_breakdown[].costnumber (float)

Scheduled service math (rate × billable duration). Unchanged by cancellation.

Example 100.

data.work_item_service_breakdown[].billable_amountnumber (float)

What this row actually bills. Equals cost normally; on a canceled row it is that row's share of the cancellation fee (0 when the client is not billed for cancellation). Sums to services_charges.

Example 25.

data.work_item_service_breakdown[].cancellation_feenumber (float)

This row's share of the client cancellation fee.

Example 25.

data.work_item_service_breakdown[].original_costnumber (float)

Example 100.

data.work_item_service_breakdown[].charge_sourcestring

Example cancellation_fee.

data.work_item_service_breakdown[].rate_sourcestring or null

Payable rows only. Which rate configuration the row's pay rate came from.

One of: provider_rate, default_rate, fallback_rate.

data.work_item_service_breakdown[].rate_source_labelstring or null

Example Provider Pay Rate.

data.entity_pay_metricsarray of object or null

Payable only. Per-assignment/shift pay calculation metrics.

data.entity_pay_metrics[].typestring

One of: assignment, shift. Example assignment.

data.entity_pay_metrics[].idstring

Example ASG-M3PCU1.

data.entity_pay_metrics[].pay_time_basisstring

Example scheduled_actual_fallback.

data.entity_pay_metrics[].derived_hours_used_for_paynumber (float)

Example 8.

data.entity_pay_metrics[].hours_used_for_paynumber (float)

Example 8.

data.entity_pay_metrics[].is_hours_overriddenboolean

Example false.

data.entity_pay_metrics[].derived_pay_ratenumber (float)

Example 45.

data.entity_pay_metrics[].pay_ratenumber (float)

Example 45.

data.entity_pay_metrics[].is_pay_rate_overriddenboolean

Example false.

data.entity_pay_metrics[].services_chargenumber (float)

Example 260.

data.entity_pay_metrics[].pay_rate_breakdownobject or null
data.entity_pay_metrics[].pay_rate_breakdown.base_ratenumber (float)

Example 45.

data.entity_pay_metrics[].pay_rate_breakdown.base_hoursnumber (float)

Example 8.

data.entity_pay_metrics[].pay_rate_breakdown.rules_appliedarray of object
data.entity_pay_metrics[].pay_rate_breakdown.rate_linesarray of object
data.entity_pay_metrics[].pay_rate_breakdown.summaryobject
data.entity_pay_metrics[].pay_rate_breakdown.effective_pay_ratenumber (float)

Example 46.67.

data.entity_pay_metrics[].pay_rate_breakdown.total_service_chargenumber (float)

Example 360.

data.entity_pay_metrics[].pay_rate_breakdown.sourcestring

Which time basis priced the lines — not where the rate came from; see rate_source.

One of: check_in, estimated_pay.

data.entity_pay_metrics[].pay_rate_breakdown.rate_sourcestring 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: provider_rate, default_rate, fallback_rate. Example provider_rate.

data.entity_pay_metrics[].pay_rate_breakdown.rate_source_labelstring or null

Display name — 'Provider Pay Rate', 'Default Pay Rate', 'Fallback Pay Rate', or 'Mixed Rate Configuration'.

Example Provider Pay Rate.

data.entity_pay_metrics[].pay_rate_breakdown.rate_source_descriptionstring or null

Example Driven by this provider's own custom pay rate configuration..

data.entity_pay_metrics[].pay_rate_breakdown.rate_source_is_mixedboolean

True when the lines were priced from more than one rate configuration.

Example false.

data.entity_pay_metrics[].pay_rate_breakdown.rate_configurationobject 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_suppressedboolean

Example false.

data.entity_pay_metrics[].warning_messagestring or null
data.entity_pay_metrics[].hours_override_reasonstring or null
data.entity_pay_metrics[].pay_rate_override_reasonstring or null
data.billing_conflictsarray 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_idstring

Example ASG-OYLEV4.

data.billing_conflicts[].document_idstring

Example INV-TOHWMO.

data.billing_conflicts[].document_typestring

Example invoice.

data.billing_conflicts[].messagestring

Example ASG-OYLEV4 is already billed on Invoice INV-TOHWMO. Remove it or mark it as reference only..

data.updatedAtstring

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 07/31/2026 06:22 PM.

401 Not signed in

Missing, invalid or expired API key.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

Scope, tenant, IP allow-list or RBAC check failed.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation error

JSON
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "type": [
      "Type is required."
    ]
  }
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Validation failed.

errorsobject
429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.

500 Server error

Unexpected error

JSON
{
  "success": false,
  "errors": "Finance preview failed",
  "message": "An unexpected error occurred — please try again."
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

errorsstring or null

Null in production. The exception message only when the application runs with debug on.

Example Finance preview failed.

messagestring

Example An unexpected error occurred — please try again..