API reference › Rates and billing › Rate and billing settings
Create or update rate and billing settings
POST /v1/settings/rates-billing
- Scope
settings_rates_billing:edit finance:edit- Roles
- admin, scheduler
Creates or updates the rate and billing settings for an organization, including service type rates, provider rates, expense reimbursement settings, client billing cancellations, invoice and pro forma settings.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
20 top-level fields; 8 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
defaultCurrency | string | Example |
serviceTypeRateSettings | array of object (13 nested) | |
serviceTypeRates | array of object (23 nested) | |
singleRates | array of object (9 nested) | |
providerSingleRates | array of object (12 nested) | Organization default single PAY rates (provider pay side of singleRates). |
providerRates | array of object (26 nested) | |
expenseRepressibility | string | Example |
expensesEnabledForAssignment | boolean | Example |
expensesEnabledForShift | boolean | Example |
expensesEnabledForClient | boolean | Example |
expensesEnabledForClientLocation | boolean | Example |
expensesEnabledForOrganization | boolean | Example |
expensesEnabledForOrganizationLocation | boolean | Example |
expenseSubmissionDeadline | integer | Example |
expenseSubmissionDuration | string | Example |
expenseOverrideLateSubmissions | boolean | Example |
expenseApprovalWorkflow | string | Example |
billingCancellations | object (24 nested) | |
invoiceSettings | object (20 nested) | |
proFormaSettings | object (22 nested) |
Nested fields
serviceTypeRateSettings 13 fields
| Field | Type | Description |
|---|---|---|
serviceTypeRateSettings[].serviceType | object | |
serviceTypeRateSettings[].serviceType.id | string | Example |
serviceTypeRateSettings[].serviceType.label | string | Example |
serviceTypeRateSettings[].minimumProviderDurationRules | array of object | |
serviceTypeRateSettings[].minimumProviderDurationRules[].value | number | Example |
serviceTypeRateSettings[].minimumProviderDurationRules[].duration | string | Example |
serviceTypeRateSettings[].minimumProviderDurationRules[].minProviders | integer | Example |
serviceTypeRateSettings[].applyCancellationFee | boolean | Example |
serviceTypeRateSettings[].feeType | string | Example |
serviceTypeRateSettings[].feeValue | number | Example |
serviceTypeRateSettings[].cancellationWindow | object | |
serviceTypeRateSettings[].cancellationWindow.id | string | Example |
serviceTypeRateSettings[].cancellationWindow.label | string | Example |
serviceTypeRates 23 fields
| Field | Type | Description |
|---|---|---|
serviceTypeRates[].rateType | object | |
serviceTypeRates[].rateType.id | string | Example |
serviceTypeRates[].rateType.label | string | Example |
serviceTypeRates[].serviceType | object | |
serviceTypeRates[].serviceType.id | string | Example |
serviceTypeRates[].serviceType.label | string | Example |
serviceTypeRates[].serviceProviderType | object | |
serviceTypeRates[].serviceProviderType.id | string | Example |
serviceTypeRates[].serviceProviderType.label | string | Example |
serviceTypeRates[].certification | object | |
serviceTypeRates[].certification.id | string | Example |
serviceTypeRates[].certification.label | string | Example |
serviceTypeRates[].siteType | object | |
serviceTypeRates[].siteType.id | string | Example |
serviceTypeRates[].siteType.label | string | Example |
serviceTypeRates[].specialization | object | |
serviceTypeRates[].specialization.id | string | Example |
serviceTypeRates[].specialization.label | string | Example |
serviceTypeRates[].unit | string | Example |
serviceTypeRates[].rate | number | Example |
serviceTypeRates[].minimumDuration | integer | Example |
serviceTypeRates[].assignment | boolean | Example |
serviceTypeRates[].shift | boolean | Example |
singleRates 9 fields
| Field | Type | Description |
|---|---|---|
singleRates[].serviceType | object | |
singleRates[].serviceType.id | string | Example |
singleRates[].serviceType.label | string | Example |
singleRates[].assignmentEnabled | boolean | Example |
singleRates[].assignmentRate | number | Example |
singleRates[].assignmentRateUnit | string | Example |
singleRates[].shiftEnabled | boolean | Example |
singleRates[].shiftRate | number | Example |
singleRates[].shiftRateUnit | string | Example |
providerSingleRates 12 fields
| Field | Type | Description |
|---|---|---|
providerSingleRates[].serviceType | object | |
providerSingleRates[].serviceType.id | string | Example |
providerSingleRates[].serviceType.label | string | Example |
providerSingleRates[].serviceProviderType | object | |
providerSingleRates[].serviceProviderType.id | string | Example |
providerSingleRates[].serviceProviderType.label | string | Example |
providerSingleRates[].assignmentEnabled | boolean | Example |
providerSingleRates[].assignmentRate | number | Example |
providerSingleRates[].assignmentRateUnit | string | Example |
providerSingleRates[].shiftEnabled | boolean | Example |
providerSingleRates[].shiftRate | number | Example |
providerSingleRates[].shiftRateUnit | string | Example |
providerRates 26 fields
| Field | Type | Description |
|---|---|---|
providerRates[].rateType | object | |
providerRates[].rateType.id | string | Example |
providerRates[].rateType.label | string | Example |
providerRates[].certification | object | |
providerRates[].certification.id | string | Example |
providerRates[].certification.label | string | Example |
providerRates[].siteType | object | |
providerRates[].siteType.id | string | Example |
providerRates[].siteType.label | string | Example |
providerRates[].specialization | object | |
providerRates[].specialization.id | string | Example |
providerRates[].specialization.label | string | Example |
providerRates[].providerRole | object | |
providerRates[].providerRole.id | string | Example |
providerRates[].providerRole.label | string | Example |
providerRates[].serviceType | object | |
providerRates[].serviceType.id | string | Example |
providerRates[].serviceType.label | string | Example |
providerRates[].serviceProviderType | object | |
providerRates[].serviceProviderType.id | string | Example |
providerRates[].serviceProviderType.label | string | Example |
providerRates[].unit | string | Example |
providerRates[].rate | number | Example |
providerRates[].minimumDuration | integer | Example |
providerRates[].assignment | boolean | Example |
providerRates[].shift | boolean | Example |
billingCancellations 24 fields
| Field | Type | Description |
|---|---|---|
billingCancellations.expenseRepressibility | string | Example |
billingCancellations.paymentTerm | object | |
billingCancellations.paymentTerm.id | string | Example |
billingCancellations.paymentTerm.label | string | Example |
billingCancellations.billingFrequency | object | |
billingCancellations.billingFrequency.id | string | Example |
billingCancellations.billingFrequency.label | string | Example |
billingCancellations.invoiceFrequency | object | |
billingCancellations.invoiceFrequency.id | string | Example |
billingCancellations.invoiceFrequency.label | string | Example |
billingCancellations.invoicesPerCycle | integer | Example |
billingCancellations.beginBillingSchedule | string (date-time) | Example |
billingCancellations.billingDay | object | |
billingCancellations.billingDay.id | string | Example |
billingCancellations.billingDay.label | string | Example |
billingCancellations.billingResponsibility | string | Example |
billingCancellations.enableProFormaStatement | boolean | Example |
billingCancellations.proFormaCadence | string | Example |
billingCancellations.defaultBillingDocument | string | Example |
billingCancellations.cancellationWindow | object | |
billingCancellations.cancellationWindow.id | string | Example |
billingCancellations.cancellationWindow.label | string | Example |
billingCancellations.cancellationFeeType | string | Example |
billingCancellations.cancellationFeeNotes | string | Example |
invoiceSettings 20 fields
| Field | Type | Description |
|---|---|---|
invoiceSettings.taxPercentage | number | Example |
invoiceSettings.discount | number | Example |
invoiceSettings.autoGenerate | boolean | Example |
invoiceSettings.autoSend | boolean | Example |
invoiceSettings.paymentTerm | object | |
invoiceSettings.paymentTerm.id | string | Example |
invoiceSettings.paymentTerm.label | string | Example |
invoiceSettings.notes | string | Example |
invoiceSettings.deliveryMethod | string | Example |
invoiceSettings.enableEmailReminder | boolean | Example |
invoiceSettings.reminderBeforeDueDate | array of object | |
invoiceSettings.reminderBeforeDueDate[].id | string | Example |
invoiceSettings.reminderBeforeDueDate[].label | string | Example |
invoiceSettings.reminderAfterDueDate | array of object | |
invoiceSettings.reminderAfterDueDate[].id | string | Example |
invoiceSettings.reminderAfterDueDate[].label | string | Example |
invoiceSettings.internalApproval | boolean | Example |
invoiceSettings.approvedDeadline | integer | Example |
invoiceSettings.fallbackBehavior | string | Example |
invoiceSettings.approvalAboveAmount | number | Example |
proFormaSettings 22 fields
| Field | Type | Description |
|---|---|---|
proFormaSettings.enableProFormaStatement | boolean | Example |
proFormaSettings.autoGenerate | boolean | Example |
proFormaSettings.autoSend | boolean | Example |
proFormaSettings.approvalBeforeInvoice | boolean | Example |
proFormaSettings.notes | string | Example |
proFormaSettings.deliveryMethod | string | Example |
proFormaSettings.enableEmailReminder | boolean | Example |
proFormaSettings.reminderBeforeDueDate | array of object | |
proFormaSettings.reminderBeforeDueDate[].id | string | Example |
proFormaSettings.reminderBeforeDueDate[].label | string | Example |
proFormaSettings.reminderAfterDueDate | array of object | |
proFormaSettings.reminderAfterDueDate[].id | string | Example |
proFormaSettings.reminderAfterDueDate[].label | string | Example |
proFormaSettings.internalApprovalBeforeInvoice | boolean | Example |
proFormaSettings.approvedDeadline | integer | Example |
proFormaSettings.fallbackBehavior | string | Example |
proFormaSettings.approvalAboveAmount | number | Example |
proFormaSettings.clientApprovalBeforeInvoice | boolean | Example |
proFormaSettings.notifyClientOnProFormaGenerate | boolean | Example |
proFormaSettings.clientReminderSchedule | string | Example |
proFormaSettings.clientApprovalDeadline | integer | Example |
proFormaSettings.clientFallbackBehavior | string | Example |
Example
{
"defaultCurrency": "USD",
"serviceTypeRateSettings": [
{
"serviceType": {
"id": "1",
"label": "ASL"
},
"minimumProviderDurationRules": [
{
"value": "3",
"duration": "Hours",
"minProviders": "2"
}
],
"applyCancellationFee": true,
"feeType": "flat",
"feeValue": "5",
"cancellationWindow": {
"id": "1",
"label": "12 hours"
}
}
],
"serviceTypeRates": [
{
"rateType": {
"id": "1",
"label": "standard"
},
"serviceType": {
"id": "1",
"label": "ASL"
},
"serviceProviderType": {
"id": "2",
"label": "Hearing"
},
"certification": {
"id": "1",
"label": "RID"
},
"siteType": {
"id": "onsite",
"label": "Onsite"
},
"specialization": {
"id": "1",
"label": "Medical"
},
"unit": "per_hour",
"rate": "50.00",
"minimumDuration": "6",
"assignment": true,
"shift": true
}
],
"singleRates": [
{
"serviceType": {
"id": "1",
"label": "ASL"
},
"assignmentEnabled": true,
"assignmentRate": "50.00",
"assignmentRateUnit": "per_hour",
"shiftEnabled": true,
"shiftRate": "60.00",
"shiftRateUnit": "per_hour"
}
],
"providerSingleRates": [
{
"serviceType": {
"id": "1",
"label": "ASL"
},
"serviceProviderType": {
"id": "2",
"label": "Hearing"
},
"assignmentEnabled": true,
"assignmentRate": "40.00",
"assignmentRateUnit": "hr",
"shiftEnabled": true,
"shiftRate": "45.00",
"shiftRateUnit": "hr"
}
],
"providerRates": [
{
"rateType": {
"id": "1",
"label": "standard"
},
"certification": {
"id": "1",
"label": "RID"
},
"siteType": {
"id": "onsite",
"label": "Onsite"
},
"specialization": {
"id": "1",
"label": "Medical"
},
"providerRole": {
"id": "agency",
"label": "Agency"
},
"serviceType": {
"id": "1",
"label": "ASL"
},
"serviceProviderType": {
"id": "2",
"label": "Hearing"
},
"unit": "per_hour",
"rate": "50.00",
"minimumDuration": "6",
"assignment": true,
"shift": true
}
],
"expenseRepressibility": "bill_to_client",
"expensesEnabledForAssignment": true,
"expensesEnabledForShift": true,
"expensesEnabledForClient": true,
"expensesEnabledForClientLocation": true,
"expensesEnabledForOrganization": true,
"expensesEnabledForOrganizationLocation": true,
"expenseSubmissionDeadline": 7,
"expenseSubmissionDuration": "days",
"expenseOverrideLateSubmissions": true,
"expenseApprovalWorkflow": "organization",
"billingCancellations": {
"expenseRepressibility": "bill_to_client",
"paymentTerm": {
"id": "1",
"label": "Net 30"
},
"billingFrequency": {
"id": "1",
"label": "Monthly"
},
"invoiceFrequency": {
"id": "1",
"label": "Monthly"
},
"invoicesPerCycle": 1,
"beginBillingSchedule": "2023-10-01T00:00:00Z",
"billingDay": {
"id": "last",
"label": "Last Day"
},
"billingResponsibility": "client",
"enableProFormaStatement": true,
"proFormaCadence": "monthly",
"defaultBillingDocument": "invoice",
"cancellationWindow": {
"id": "1",
"label": "12 hours"
},
"cancellationFeeType": "flat",
"cancellationFeeNotes": "Cancellation fee applies if canceled within 12 hours."
},
"invoiceSettings": {
"taxPercentage": 18,
"discount": 10,
"autoGenerate": true,
"autoSend": true,
"paymentTerm": {
"id": "1",
"label": "Net 30"
},
"notes": "Thank you for your business!",
"deliveryMethod": "email",
"enableEmailReminder": true,
"reminderBeforeDueDate": [
{
"id": "1",
"label": "3 days before"
}
],
"reminderAfterDueDate": [
{
"id": "1",
"label": "1 day after"
}
],
"internalApproval": true,
"approvedDeadline": 7,
"fallbackBehavior": "auto_approve",
"approvalAboveAmount": 1000
},
"proFormaSettings": {
"enableProFormaStatement": true,
"autoGenerate": true,
"autoSend": true,
"approvalBeforeInvoice": true,
"notes": "Pro Forma invoice for your review.",
"deliveryMethod": "email",
"enableEmailReminder": true,
"reminderBeforeDueDate": [
{
"id": "1",
"label": "3 days before"
}
],
"reminderAfterDueDate": [
{
"id": "1",
"label": "1 day after"
}
],
"internalApprovalBeforeInvoice": true,
"approvedDeadline": 7,
"fallbackBehavior": "auto_approve",
"approvalAboveAmount": 1000,
"clientApprovalBeforeInvoice": true,
"notifyClientOnProFormaGenerate": true,
"clientReminderSchedule": "weekly",
"clientApprovalDeadline": 7,
"clientFallbackBehavior": "auto_approve"
}
}Example request
curl -X POST "https://api.fetchfido.ai/v1/settings/rates-billing" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"defaultCurrency":"USD","serviceTypeRateSettings":[{"serviceType":{"id":"1","label":"ASL"},"minimumProviderDurationRules":[{"value":"3","duration":"Hours","minProviders":"2"}],"applyCancellationFee":true,"feeType":"flat","feeValue":"5","cancellationWindow":{"id":"1","label":"12 hours"}}],"serviceTypeRates":[{"rateType":{"id":"1","label":"standard"},"serviceType":{"id":"1","label":"ASL"},"serviceProviderType":{"id":"2","label":"Hearing"},"certification":{"id":"1","label":"RID"},"siteType":{"id":"onsite","label":"Onsite"},"specialization":{"id":"1","label":"Medical"},"unit":"per_hour","rate":"50.00","minimumDuration":"6","assignment":true,"shift":true}],"singleRates":[{"serviceType":{"id":"1","label":"ASL"},"assignmentEnabled":true,"assignmentRate":"50.00","assignmentRateUnit":"per_hour","shiftEnabled":true,"shiftRate":"60.00","shiftRateUnit":"per_hour"}],"providerSingleRates":[{"serviceType":{"id":"1","label":"ASL"},"serviceProviderType":{"id":"2","label":"Hearing"},"assignmentEnabled":true,"assignmentRate":"40.00","assignmentRateUnit":"hr","shiftEnabled":true,"shiftRate":"45.00","shiftRateUnit":"hr"}],"providerRates":[{"rateType":{"id":"1","label":"standard"},"certification":{"id":"1","label":"RID"},"siteType":{"id":"onsite","label":"Onsite"},"specialization":{"id":"1","label":"Medical"},"providerRole":{"id":"agency","label":"Agency"},"serviceType":{"id":"1","label":"ASL"},"serviceProviderType":{"id":"2","label":"Hearing"},"unit":"per_hour","rate":"50.00","minimumDuration":"6","assignment":true,"shift":true}],"expenseRepressibility":"bill_to_client","expensesEnabledForAssignment":true,"expensesEnabledForShift":true,"expensesEnabledForClient":true,"expensesEnabledForClientLocation":true,"expensesEnabledForOrganization":true,"expensesEnabledForOrganizationLocation":true,"expenseSubmissionDeadline":7,"expenseSubmissionDuration":"days","expenseOverrideLateSubmissions":true,"expenseApprovalWorkflow":"organization","billingCancellations":{"expenseRepressibility":"bill_to_client","paymentTerm":{"id":"1","label":"Net 30"},"billingFrequency":{"id":"1","label":"Monthly"},"invoiceFrequency":{"id":"1","label":"Monthly"},"invoicesPerCycle":1,"beginBillingSchedule":"2023-10-01T00:00:00Z","billingDay":{"id":"last","label":"Last Day"},"billingResponsibility":"client","enableProFormaStatement":true,"proFormaCadence":"monthly","defaultBillingDocument":"invoice","cancellationWindow":{"id":"1","label":"12 hours"},"cancellationFeeType":"flat","cancellationFeeNotes":"Cancellation fee applies if canceled within 12 hours."},"invoiceSettings":{"taxPercentage":18,"discount":10,"autoGenerate":true,"autoSend":true,"paymentTerm":{"id":"1","label":"Net 30"},"notes":"Thank you for your business!","deliveryMethod":"email","enableEmailReminder":true,"reminderBeforeDueDate":[{"id":"1","label":"3 days before"}],"reminderAfterDueDate":[{"id":"1","label":"1 day after"}],"internalApproval":true,"approvedDeadline":7,"fallbackBehavior":"auto_approve","approvalAboveAmount":1000},"proFormaSettings":{"enableProFormaStatement":true,"autoGenerate":true,"autoSend":true,"approvalBeforeInvoice":true,"notes":"Pro Forma invoice for your review.","deliveryMethod":"email","enableEmailReminder":true,"reminderBeforeDueDate":[{"id":"1","label":"3 days before"}],"reminderAfterDueDate":[{"id":"1","label":"1 day after"}],"internalApprovalBeforeInvoice":true,"approvedDeadline":7,"fallbackBehavior":"auto_approve","approvalAboveAmount":1000,"clientApprovalBeforeInvoice":true,"notifyClientOnProFormaGenerate":true,"clientReminderSchedule":"weekly","clientApprovalDeadline":7,"clientFallbackBehavior":"auto_approve"}}'Try it
Responses
200 Settings have been updated
Settings have been updated.
{
"success": true,
"message": "Settings have been updated",
"data": null
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | string or null |
401 Not signed in
Unauthorized - Authentication required
{
"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
Forbidden. The payload carries a Service Type Rates, Provider Pay or Reimbursable Expenses field (serviceTypeRateSettings, singleRates, providerSingleRates, the expense settings) and the role has no Finance Read, or the role has no Rates & Billing Edit. Nothing is saved.
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'settings_rates_billing:edit' 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. A unit other than Per Hour or Per Minute (for example weekly) is refused and nothing is saved (a unit sent back exactly as stored is kept, even one saved before units were checked). The message is under the key of the field that carried the unit: serviceTypeRateSettings.N.billingUnit, serviceTypeRateSettings.N.providerPayUnit, singleRates.N.assignmentRateUnit, singleRates.N.shiftRateUnit, providerSingleRates.N.assignmentRateUnit or providerSingleRates.N.shiftRateUnit (N is the row index).
{
"status": "error",
"message": "Unable to save. Please check the highlighted fields.",
"errors": {
"singleRates.0.assignmentRateUnit": [
"The unit must be Per Hour or Per Minute (hr or min)."
]
}
}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": "An unexpected error occurred. Please try again later."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |