API reference › Finance › Payables
Get per-entity payable pay calculation metrics
POST /v1/finance/payable/calculation-method
- Scope
finance:read- Roles
- admin, scheduler
Returns pay calculation metrics for each billable assignment/shift in one batch: pay_time_basis, hours_used_for_pay, pay_rate, services_charge, and optional warning_message per entity.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
| Field | Type | Description |
|---|---|---|
provider_id required | string | Provider user id Example |
billable_entities required | array of object | Assignments/shifts with optional per-entity pay_time_basis and override fields for preview (override reasons not required). |
billable_entities[].type required | string | One of: |
billable_entities[].id required | string | Example |
billable_entities[].pay_time_basis | string | One of: |
billable_entities[].hours_used_for_pay | number (float) or null | Example |
billable_entities[].pay_rate | number (float) or null | Example |
pay_time_basis | string or null | Optional document-level default when per-entity basis is omitted. One of: |
payable_id | string or null | When editing an existing payable, uses the stored pay metrics for work items the request does not override. Example |
Example
{
"provider_id": "USR-PROVIDER-123",
"billable_entities": [
{
"type": "assignment",
"id": "ASG-M3PCU1",
"pay_time_basis": "scheduled_time",
"hours_used_for_pay": 4,
"pay_rate": 65
}
],
"pay_time_basis": "scheduled_time",
"payable_id": "PAY-1001"
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/payable/calculation-method" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"provider_id":"USR-PROVIDER-123","billable_entities":[{"type":"assignment","id":"ASG-M3PCU1","pay_time_basis":"scheduled_time","hours_used_for_pay":4,"pay_rate":65}],"pay_time_basis":"scheduled_time","payable_id":"PAY-1001"}'Try it
Responses
200 Payable calculation method metrics fetched successfully
Payable calculation method metrics fetched successfully
{
"success": true,
"message": "Payable calculation method metrics fetched successfully.",
"data": {
"entities": [
{
"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"
}
]
}
}Response fields (32)
3 top-level fields; 1 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object (29 nested) |
Nested fields
data 29 fields
| Field | Type | Description |
|---|---|---|
data.entities | array of object | |
data.entities[].type | string | One of: |
data.entities[].id | string | Example |
data.entities[].pay_time_basis | string | Example |
data.entities[].derived_hours_used_for_pay | number (float) | Example |
data.entities[].hours_used_for_pay | number (float) | Example |
data.entities[].is_hours_overridden | boolean | Example |
data.entities[].derived_pay_rate | number (float) | Example |
data.entities[].pay_rate | number (float) | Example |
data.entities[].is_pay_rate_overridden | boolean | Example |
data.entities[].services_charge | number (float) | Example |
data.entities[].pay_rate_breakdown | object or null | |
data.entities[].pay_rate_breakdown.base_rate | number (float) | Example |
data.entities[].pay_rate_breakdown.base_hours | number (float) | Example |
data.entities[].pay_rate_breakdown.rules_applied | array of object | |
data.entities[].pay_rate_breakdown.rate_lines | array of object | |
data.entities[].pay_rate_breakdown.summary | object | |
data.entities[].pay_rate_breakdown.effective_pay_rate | number (float) | Example |
data.entities[].pay_rate_breakdown.total_service_charge | number (float) | Example |
data.entities[].pay_rate_breakdown.source | string | Which time basis priced the lines — not where the rate came from; see rate_source. One of: |
data.entities[].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.entities[].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.entities[].pay_rate_breakdown.rate_source_description | string or null | Example |
data.entities[].pay_rate_breakdown.rate_source_is_mixed | boolean | True when the lines were priced from more than one rate configuration. Example |
data.entities[].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.entities[].rate_rules_suppressed | boolean | Example |
data.entities[].warning_message | string or null | |
data.entities[].hours_override_reason | string or null | |
data.entities[].pay_rate_override_reason | string or null |
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": {}
}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": "Failed to calculate payable metrics",
"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 |