API reference › Finance › Payables
Create or update a payable
POST /v1/finance/payables
- Scope
finance:write- Roles
- admin, scheduler
Creates or updates a payable. Work items (assignments/shifts) already paid to this provider are excluded from services_charges. When duplicating (source_document_id), if the source is paid, amounts are zeroed.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
25 top-level fields; 10 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
override_locks | boolean or null | Edit a paid document past its locks. Send on the retry after a save asks. |
override_reason | object (2 nested) | |
override_reason_text | string or null | max length 1000. |
override_delivery | string or null | One of: |
confirmation | boolean or null | Confirms the resend prompt a save on a sent document raises. |
resend_delivery | string or null | One of: |
overpayment_confirmation | boolean or null | Accept a payment that exceeds the balance due. |
billable_entities_billing | array of object or null (19 nested) | |
internalNotes | string or null | min length 2, max length 2000. |
customFields | object or null | Custom field values keyed by field id. |
externalCustomFields | object or null | Values for the external custom fields, keyed by field id. |
id | string | Payable ID (include for update, omit for create) Example |
source_document_id | string | Optional. Source document ID for duplication. If provided and source is paid (status Paid or balance_due <= 0), amounts are zeroed unless full_copy=true. Example |
full_copy | boolean | When true, skip paid-source zeroing and keep full charges. Example |
provider_id required | object (2 nested) | Provider selection |
billable_entities | array of object (2 nested) | Work items linked to this payable (assignment/shift ids only). Required when published. |
billable_entities_pay_calc | array of object (8 nested) | Per-entity pay calculation inputs. Required when published. Override reasons required on save when hours/rate differ from derived. |
line_items | array of object (6 nested) | Array of line items |
summary | object (9 nested) | Tax, discount and payments on a finance document. A type needs its amount alongside it. |
status | object (2 nested) | Payable status |
payment_terms | object (2 nested) | Payment terms |
issue_date | string (date) | Payable issue date Example |
notes | string | Payable notes Example |
documents | array of object (10 nested) | Array of documents to attach |
is_published | boolean | Whether the payable is published Example |
Nested fields
override_reason 2 fields
| Field | Type | Description |
|---|---|---|
override_reason.id | integer or string | Example |
override_reason.label | string or null | Example |
billable_entities_billing 19 fields
| Field | Type | Description |
|---|---|---|
billable_entities_billing[].id required | string | A work item listed in billable_entities. Example |
billable_entities_billing[].billing_mode | string or null | One of: |
billable_entities_billing[].bill_service | boolean or null | |
billable_entities_billing[].bill_expenses | boolean or null | Example |
billable_entities_billing[].bill_admin_fee | boolean or null | Example |
billable_entities_billing[].adminFeeBreakdown | object or null | |
billable_entities_billing[].adminFeeBreakdown.feeSource | string or null | One of: |
billable_entities_billing[].adminFeeBreakdown.clients | array of object or null | |
billable_entities_billing[].adminFeeBreakdown.clients[].id | string or null | Client or provider user id. Example |
billable_entities_billing[].adminFeeBreakdown.clients[].feeSource | string or null | Providers only. One of: |
billable_entities_billing[].adminFeeBreakdown.clients[].method | string or null | One of: |
billable_entities_billing[].adminFeeBreakdown.clients[].value | number or null | min 0. Example |
billable_entities_billing[].adminFeeBreakdown.clients[].source | string or null | Clients only: where the fee was resolved from. One of: |
billable_entities_billing[].adminFeeBreakdown.providers | array of object or null | |
billable_entities_billing[].adminFeeBreakdown.providers[].id | string or null | Client or provider user id. Example |
billable_entities_billing[].adminFeeBreakdown.providers[].feeSource | string or null | Providers only. One of: |
billable_entities_billing[].adminFeeBreakdown.providers[].method | string or null | One of: |
billable_entities_billing[].adminFeeBreakdown.providers[].value | number or null | min 0. Example |
billable_entities_billing[].adminFeeBreakdown.providers[].source | string or null | Clients only: where the fee was resolved from. One of: |
provider_id 2 fields
| Field | Type | Description |
|---|---|---|
provider_id.id | string | Provider ID Example |
provider_id.label | string | Provider name Example |
billable_entities 2 fields
| Field | Type | Description |
|---|---|---|
billable_entities[].type required | string | One of: |
billable_entities[].id required | string | 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. |
line_items 6 fields
| Field | Type | Description |
|---|---|---|
line_items[].name | string | Line item name (optional) Example |
line_items[].description | string | Line item description (optional) Example |
line_items[].amount required | number (float) | Line item amount 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 |
summary 9 fields
| Field | Type | Description |
|---|---|---|
summary.tax_type | object or null | |
summary.tax_type.id | string | One of: |
summary.tax_type.label | string | Example |
summary.tax_amount | number or null | min 0. Example |
summary.discount_type | object or null | |
summary.discount_type.id | string | One of: |
summary.discount_type.label | string | Example |
summary.discount_amount | number or null | min 0. Example |
summary.payments_applied | number or null | min 0. |
status 2 fields
| Field | Type | Description |
|---|---|---|
status.id | integer | Status ID Example |
status.label | string | Status label Example |
payment_terms 2 fields
| Field | Type | Description |
|---|---|---|
payment_terms.id | integer | Payment terms ID Example |
payment_terms.label | string | Payment terms label Example |
documents 10 fields
| Field | Type | Description |
|---|---|---|
documents[].id | integer | Document ID (for updates) Example |
documents[].file | string (binary) | File to upload |
documents[].fileName | string | Document file name Example |
documents[].isPublic | boolean | Whether document is public Example |
documents[].categories | array of object | Document categories |
documents[].categories[].id | integer | Category ID Example |
documents[].categories[].label | string | Category name Example |
documents[].tags | array of object | Document tags |
documents[].tags[].id | string | Tag ID Example |
documents[].tags[].label | string | Tag name Example |
Example
{
"override_locks": true,
"override_reason": {
"id": 1,
"label": "Example"
},
"override_reason_text": "string",
"override_delivery": "internal_only",
"confirmation": true,
"resend_delivery": "send_updated",
"overpayment_confirmation": true,
"billable_entities_billing": [
{
"id": "ASG-YZXCIT",
"billing_mode": "bill",
"bill_service": true,
"bill_expenses": true,
"bill_admin_fee": true,
"adminFeeBreakdown": {
"feeSource": "calculated",
"clients": [
{
"id": "CLT-N3B72G",
"feeSource": null,
"method": null,
"value": 5,
"source": null
}
],
"providers": [
{
"id": "CLT-N3B72G",
"feeSource": null,
"method": null,
"value": 5,
"source": null
}
]
}
}
],
"internalNotes": "string",
"customFields": {},
"externalCustomFields": {},
"id": "PAY-ABC123",
"source_document_id": "PAY-ABC123",
"full_copy": true,
"provider_id": {
"id": "USR-12345",
"label": "John Doe"
},
"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"
}
],
"line_items": [
{
"name": "Shift Pay",
"description": "Shift payment",
"amount": 100,
"type": {
"id": "shift_pay",
"label": "Shift Payment"
}
}
],
"summary": {
"tax_type": {
"id": "Percentage",
"label": "Percentage"
},
"tax_amount": 8.25,
"discount_type": {
"id": "Fixed",
"label": "Fixed"
},
"discount_amount": 10,
"payments_applied": 0
},
"status": {
"id": 1,
"label": "Sent"
},
"payment_terms": {
"id": 1,
"label": "Net 15"
},
"issue_date": "2025-01-01",
"notes": "Payment due within 15 days.",
"documents": [
{
"id": 1,
"file": "string",
"fileName": "assignment2.png",
"isPublic": true,
"categories": [
{
"id": 1,
"label": "Supporting Docs"
}
],
"tags": [
{
"id": "tag-1",
"label": "Internal Use"
}
]
}
],
"is_published": true
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/payables" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"override_locks":true,"override_reason":{"id":1,"label":"Example"},"override_reason_text":"string","override_delivery":"internal_only","confirmation":true,"resend_delivery":"send_updated","overpayment_confirmation":true,"billable_entities_billing":[{"id":"ASG-YZXCIT","billing_mode":"bill","bill_service":true,"bill_expenses":true,"bill_admin_fee":true,"adminFeeBreakdown":{"feeSource":"calculated","clients":[{"id":"CLT-N3B72G","feeSource":null,"method":null,"value":5,"source":null}],"providers":[{"id":"CLT-N3B72G","feeSource":null,"method":null,"value":5,"source":null}]}}],"internalNotes":"string","customFields":{},"externalCustomFields":{},"id":"PAY-ABC123","source_document_id":"PAY-ABC123","full_copy":true,"provider_id":{"id":"USR-12345","label":"John Doe"},"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"}],"line_items":[{"name":"Shift Pay","description":"Shift payment","amount":100,"type":{"id":"shift_pay","label":"Shift Payment"}}],"summary":{"tax_type":{"id":"Percentage","label":"Percentage"},"tax_amount":8.25,"discount_type":{"id":"Fixed","label":"Fixed"},"discount_amount":10,"payments_applied":0},"status":{"id":1,"label":"Sent"},"payment_terms":{"id":1,"label":"Net 15"},"issue_date":"2025-01-01","notes":"Payment due within 15 days.","documents":[{"id":1,"file":"string","fileName":"assignment2.png","isPublic":true,"categories":[{"id":1,"label":"Supporting Docs"}],"tags":[{"id":"tag-1","label":"Internal Use"}]}],"is_published":true}'Try it
Responses
200 Payable updated successfully
Payable updated successfully
{
"success": true,
"message": "Payable updated successfully.",
"data": {
"id": "PAY-ABC123"
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | string | Example |
201 Payable created successfully
Payable created successfully
{
"success": true,
"message": "Payable created successfully.",
"data": {
"id": "PAY-ABC123"
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | string | 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:write' 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": {
"provider_id": [
"Provider 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": "Payable operation 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 |