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.

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.

payment_termsobject (2 nested)

Required when published.

expiry_datestring (date) or null

On or after issue_date. expiryDate is accepted as an alias.

Example 2025-02-15.

customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

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

idstring

Pro forma ID (include for update, omit for create)

Example PF-1IU6BD.

source_document_idstring

Optional source document ID for duplication. If provided and source is accepted, amounts will be automatically zeroed.

Example PF-ABC123.

client_id requiredobject (2 nested)

Client selection

billable_entitiesarray of object (2 nested)

Invoices to include in the pro forma. Required when published.

issue_datestring (date)

Issue date

Example 2025-01-15.

due_datestring (date)

Due date

Example 2025-01-30.

line_itemsarray of object (6 nested)

Array of additional line items (optional)

summaryobject (9 nested)

Pro forma summary with tax and discount details

statusobject (2 nested)

Pro forma status

notesstring

Pro forma notes

Example Payment due within 15 days..

documentsarray of object (10 nested)

Array of documents to attach

is_publishedboolean

Whether the pro forma is published

Example true.

internalNotesstring

Internal notes

Example s23.

Nested fields

override_reason 2 fields
FieldTypeDescription
override_reason.idinteger or string

Example 1.

override_reason.labelstring or null

Example Example.

payment_terms 2 fields
FieldTypeDescription
payment_terms.idinteger or string

Example 1.

payment_terms.labelstring or null

Example Example.

client_id 2 fields
FieldTypeDescription
client_id.idstring

Client ID

Example CLT-N3B72G.

client_id.labelstring

Client name

Example Test Client Company.

billable_entities 2 fields
FieldTypeDescription
billable_entities[].typestring

Entity type

Example invoice.

billable_entities[].idstring

Entity ID

Example INV-QKPWQ9.

line_items 6 fields
FieldTypeDescription
line_items[].namestring

Line item name (optional)

Example Consultation Fee.

line_items[].descriptionstring

Line item description (optional)

Example Initial consultation service.

line_items[].amount requirednumber (float)

Line item amount

Example 150.

line_items[].type requiredobject

Line item type

line_items[].type.idstring

Line item type ID

One of: charges, credit, reimbursement. Example charges.

line_items[].type.labelstring

Line item type label (optional)

Example Charges.

summary 9 fields
FieldTypeDescription
summary.tax_typeobject

Tax type

summary.tax_type.idstring

Tax type ID

One of: Fixed, Percentage. Example Percentage.

summary.tax_type.labelstring

Tax type label

Example Percentage Tax.

summary.tax_amountnumber (float)

Tax amount/percentage

Example 15.

summary.discount_typeobject

Discount type

summary.discount_type.idstring

Discount type ID

One of: Fixed, Percentage. Example Fixed.

summary.discount_type.labelstring

Discount type label

Example Fixed Discount.

summary.discount_amountnumber (float)

Discount amount/percentage

Example 10.

summary.payments_appliednumber (float)

Payments already applied

Example 25.

status 2 fields
FieldTypeDescription
status.idinteger

Status ID

Example 1.

status.labelstring

Status label

Example Sent.

documents 10 fields
FieldTypeDescription
documents[].idinteger

Document ID (for updates)

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

documents[].categories[].labelstring

Category name

Example Supporting Docs.

documents[].tagsarray of object

Document tags

documents[].tags[].idstring

Tag ID

documents[].tags[].labelstring

Tag name

Example Internal Use23.

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,
  "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

Shell
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

JSON
{
  "success": true,
  "message": "Pro forma updated successfully.",
  "data": {
    "id": 1
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Pro forma updated successfully..

dataobject
data.idinteger

Example 1.

201 Pro forma created successfully

Pro forma created successfully

JSON
{
  "success": true,
  "message": "Pro forma created successfully.",
  "data": {
    "id": 1
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Pro forma created successfully..

dataobject
data.idinteger

Example 1.

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": {
    "client_id": [
      "Client 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": "Pro forma 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 Pro forma operation failed.

messagestring

Example An unexpected error occurred — please try again..