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.

FieldTypeDescription
override_locksboolean or null

Edit a paid document past its locks. Send on the retry after a save asks.

override_reasonobject (2 nested)
override_reason_textstring or null

max length 1000.

override_deliverystring or null

One of: internal_only, send_updated.

confirmationboolean or null

Confirms the resend prompt a save on a sent document raises.

resend_deliverystring or null

One of: send_updated, internal_only, send_now, save_only.

overpayment_confirmationboolean or null

Accept a payment that exceeds the balance due.

billable_entities_billingarray of object or null (19 nested)
internalNotesstring or null

min length 2, max length 2000.

customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

Values for the external custom fields, keyed by field id.

idstring

Payable ID (include for update, omit for create)

Example PAY-ABC123.

source_document_idstring

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 PAY-ABC123.

full_copyboolean

When true, skip paid-source zeroing and keep full charges.

Example true.

provider_id requiredobject (2 nested)

Provider selection

billable_entitiesarray of object (2 nested)

Work items linked to this payable (assignment/shift ids only). Required when published.

billable_entities_pay_calcarray of object (8 nested)

Per-entity pay calculation inputs. Required when published. Override reasons required on save when hours/rate differ from derived.

line_itemsarray of object (6 nested)

Array of line items

summaryobject (9 nested)

Tax, discount and payments on a finance document. A type needs its amount alongside it.

statusobject (2 nested)

Payable status

payment_termsobject (2 nested)

Payment terms

issue_datestring (date)

Payable issue date

Example 2025-01-01.

notesstring

Payable notes

Example Payment due within 15 days..

documentsarray of object (10 nested)

Array of documents to attach

is_publishedboolean

Whether the payable is published

Example true.

Nested fields

override_reason 2 fields
FieldTypeDescription
override_reason.idinteger or string

Example 1.

override_reason.labelstring or null

Example Example.

billable_entities_billing 19 fields
FieldTypeDescription
billable_entities_billing[].id requiredstring

A work item listed in billable_entities.

Example ASG-YZXCIT.

billable_entities_billing[].billing_modestring or null

One of: bill, reference. Example bill.

billable_entities_billing[].bill_serviceboolean or null
billable_entities_billing[].bill_expensesboolean or null

Example true.

billable_entities_billing[].bill_admin_feeboolean or null

Example true.

billable_entities_billing[].adminFeeBreakdownobject or null
billable_entities_billing[].adminFeeBreakdown.feeSourcestring or null

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.clientsarray of object or null
billable_entities_billing[].adminFeeBreakdown.clients[].idstring or null

Client or provider user id.

Example CLT-N3B72G.

billable_entities_billing[].adminFeeBreakdown.clients[].feeSourcestring or null

Providers only.

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.clients[].methodstring or null

One of: flat, percentage.

billable_entities_billing[].adminFeeBreakdown.clients[].valuenumber or null

min 0. Example 5.

billable_entities_billing[].adminFeeBreakdown.clients[].sourcestring or null

Clients only: where the fee was resolved from.

One of: client, client_location, organization, organization_location, tenant, default, none, work_item_ssot, invoice_client_scope, stored_estimate.

billable_entities_billing[].adminFeeBreakdown.providersarray of object or null
billable_entities_billing[].adminFeeBreakdown.providers[].idstring or null

Client or provider user id.

Example CLT-N3B72G.

billable_entities_billing[].adminFeeBreakdown.providers[].feeSourcestring or null

Providers only.

One of: calculated, manual.

billable_entities_billing[].adminFeeBreakdown.providers[].methodstring or null

One of: flat, percentage.

billable_entities_billing[].adminFeeBreakdown.providers[].valuenumber or null

min 0. Example 5.

billable_entities_billing[].adminFeeBreakdown.providers[].sourcestring or null

Clients only: where the fee was resolved from.

One of: client, client_location, organization, organization_location, tenant, default, none, work_item_ssot, invoice_client_scope, stored_estimate.

provider_id 2 fields
FieldTypeDescription
provider_id.idstring

Provider ID

Example USR-12345.

provider_id.labelstring

Provider name

Example John Doe.

billable_entities 2 fields
FieldTypeDescription
billable_entities[].type requiredstring

One of: assignment, shift. Example assignment.

billable_entities[].id requiredstring

Example ASG-M3PCU1.

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.

line_items 6 fields
FieldTypeDescription
line_items[].namestring

Line item name (optional)

Example Shift Pay.

line_items[].descriptionstring

Line item description (optional)

Example Shift payment.

line_items[].amount requirednumber (float)

Line item amount

Example 100.

line_items[].type requiredobject

Line item type

line_items[].type.idstring

Line item type ID

Example shift_pay.

line_items[].type.labelstring

Line item type label

Example Shift Payment.

summary 9 fields
FieldTypeDescription
summary.tax_typeobject or null
summary.tax_type.idstring

One of: Fixed, Percentage. Example Percentage.

summary.tax_type.labelstring

Example Percentage.

summary.tax_amountnumber or null

min 0. Example 8.25.

summary.discount_typeobject or null
summary.discount_type.idstring

One of: Fixed, Percentage. Example Fixed.

summary.discount_type.labelstring

Example Fixed.

summary.discount_amountnumber or null

min 0. Example 10.

summary.payments_appliednumber or null

min 0.

status 2 fields
FieldTypeDescription
status.idinteger

Status ID

Example 1.

status.labelstring

Status label

Example Sent.

payment_terms 2 fields
FieldTypeDescription
payment_terms.idinteger

Payment terms ID

Example 1.

payment_terms.labelstring

Payment terms label

Example Net 15.

documents 10 fields
FieldTypeDescription
documents[].idinteger

Document ID (for updates)

Example 1.

documents[].filestring (binary)

File to upload

documents[].fileNamestring

Document file name

Example assignment2.png.

documents[].isPublicboolean

Whether document is public

Example true.

documents[].categoriesarray of object

Document categories

documents[].categories[].idinteger

Category ID

Example 1.

documents[].categories[].labelstring

Category name

Example Supporting Docs.

documents[].tagsarray of object

Document tags

documents[].tags[].idstring

Tag ID

Example tag-1.

documents[].tags[].labelstring

Tag name

Example Internal Use.

Example

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

Shell
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

JSON
{
  "success": true,
  "message": "Payable updated successfully.",
  "data": {
    "id": "PAY-ABC123"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Payable updated successfully..

dataobject
data.idstring

Example PAY-ABC123.

201 Payable created successfully

Payable created successfully

JSON
{
  "success": true,
  "message": "Payable created successfully.",
  "data": {
    "id": "PAY-ABC123"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Payable created successfully..

dataobject
data.idstring

Example PAY-ABC123.

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:write' 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:write' 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": {
    "provider_id": [
      "Provider 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": "Payable operation 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 Payable operation failed.

messagestring

Example An unexpected error occurred — please try again..