API reference › Finance › Pro formas
Create or update a pro forma invoice
POST /v1/finance/pro-formas
- Scope
finance:write- Roles
- admin, scheduler
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
24 top-level fields; 8 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. |
payment_terms | object (2 nested) | Required when published. |
expiry_date | string (date) or null | On or after issue_date. expiryDate is accepted as an alias. Example |
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 | Pro forma ID (include for update, omit for create) Example |
source_document_id | string | Optional source document ID for duplication. If provided and source is accepted, amounts will be automatically zeroed. Example |
client_id required | object (2 nested) | Client selection |
billable_entities | array of object (2 nested) | Invoices to include in the pro forma. Required when published. |
issue_date | string (date) | Issue date Example |
due_date | string (date) | Due date Example |
line_items | array of object (6 nested) | Array of additional line items (optional) |
summary | object (9 nested) | Pro forma summary with tax and discount details |
status | object (2 nested) | Pro forma status |
notes | string | Pro forma notes Example |
documents | array of object (10 nested) | Array of documents to attach |
is_published | boolean | Whether the pro forma is published Example |
internalNotes | string | Internal notes Example |
Nested fields
override_reason 2 fields
| Field | Type | Description |
|---|---|---|
override_reason.id | integer or string | Example |
override_reason.label | string or null | Example |
payment_terms 2 fields
| Field | Type | Description |
|---|---|---|
payment_terms.id | integer or string | Example |
payment_terms.label | string or null | Example |
client_id 2 fields
| Field | Type | Description |
|---|---|---|
client_id.id | string | Client ID Example |
client_id.label | string | Client name Example |
billable_entities 2 fields
| Field | Type | Description |
|---|---|---|
billable_entities[].type | string | Entity type Example |
billable_entities[].id | string | Entity ID Example |
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 One of: |
line_items[].type.label | string | Line item type label (optional) Example |
summary 9 fields
| Field | Type | Description |
|---|---|---|
summary.tax_type | object | Tax type |
summary.tax_type.id | string | Tax type ID One of: |
summary.tax_type.label | string | Tax type label Example |
summary.tax_amount | number (float) | Tax amount/percentage Example |
summary.discount_type | object | Discount type |
summary.discount_type.id | string | Discount type ID One of: |
summary.discount_type.label | string | Discount type label Example |
summary.discount_amount | number (float) | Discount amount/percentage Example |
summary.payments_applied | number (float) | Payments already applied Example |
status 2 fields
| Field | Type | Description |
|---|---|---|
status.id | integer | Status ID Example |
status.label | string | Status label Example |
documents 10 fields
| Field | Type | Description |
|---|---|---|
documents[].id | integer | Document ID (for updates) |
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 |
documents[].categories[].label | string | Category name Example |
documents[].tags | array of object | Document tags |
documents[].tags[].id | string | Tag ID |
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,
"payment_terms": {
"id": 1,
"label": "Example"
},
"expiry_date": "2025-02-15",
"customFields": {},
"externalCustomFields": {},
"id": "PF-1IU6BD",
"source_document_id": "PF-ABC123",
"client_id": {
"id": "CLT-N3B72G",
"label": "Test Client Company"
},
"billable_entities": [
{
"type": "invoice",
"id": "INV-QKPWQ9"
}
],
"issue_date": "2025-01-15",
"due_date": "2025-01-30",
"line_items": [
{
"name": "Consultation Fee",
"description": "Initial consultation service",
"amount": 150,
"type": {
"id": "charges",
"label": "Charges"
}
}
],
"summary": {
"tax_type": {
"id": "Percentage",
"label": "Percentage Tax"
},
"tax_amount": 15,
"discount_type": {
"id": "Fixed",
"label": "Fixed Discount"
},
"discount_amount": 10,
"payments_applied": 25
},
"status": {
"id": 1,
"label": "Sent"
},
"notes": "Payment due within 15 days.",
"documents": [
{
"id": null,
"file": "string",
"fileName": "assignment2.png",
"isPublic": true,
"categories": [
{
"id": null,
"label": "Supporting Docs"
}
],
"tags": [
{
"id": null,
"label": "Internal Use23"
}
]
}
],
"is_published": true,
"internalNotes": "s23"
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/pro-formas" \
-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,"payment_terms":{"id":1,"label":"Example"},"expiry_date":"2025-02-15","customFields":{},"externalCustomFields":{},"id":"PF-1IU6BD","source_document_id":"PF-ABC123","client_id":{"id":"CLT-N3B72G","label":"Test Client Company"},"billable_entities":[{"type":"invoice","id":"INV-QKPWQ9"}],"issue_date":"2025-01-15","due_date":"2025-01-30","line_items":[{"name":"Consultation Fee","description":"Initial consultation service","amount":150,"type":{"id":"charges","label":"Charges"}}],"summary":{"tax_type":{"id":"Percentage","label":"Percentage Tax"},"tax_amount":15,"discount_type":{"id":"Fixed","label":"Fixed Discount"},"discount_amount":10,"payments_applied":25},"status":{"id":1,"label":"Sent"},"notes":"Payment due within 15 days.","documents":[{"id":null,"file":"string","fileName":"assignment2.png","isPublic":true,"categories":[{"id":null,"label":"Supporting Docs"}],"tags":[{"id":null,"label":"Internal Use23"}]}],"is_published":true,"internalNotes":"s23"}'Try it
Responses
200 Pro forma updated successfully
Pro forma updated successfully
{
"success": true,
"message": "Pro forma updated successfully.",
"data": {
"id": 1
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | integer | Example |
201 Pro forma created successfully
Pro forma created successfully
{
"success": true,
"message": "Pro forma created successfully.",
"data": {
"id": 1
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | integer | 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": {
"client_id": [
"Client 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": "Pro forma 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 |