Documents¶

Documents represent invoices, credit notes, and other financial records. They drive Collections workflows, CashApp payment matching, and PDF delivery.

Document Status¶

Document status is always server-controlled — any status field in a request body is silently stripped.

Trigger	Transition
POST/PUT with `denomination: 0` or `denomination_in_base_currency: 0`	open → closed (auto-close)
PATCH that results in `denomination = 0`	open → closed (auto-close)
PUT/PATCH with non-zero denomination on a closed document	closed → open (reopen)
POST `/closure`	open → closed (explicit close with reason)

Document Types¶

Integer	String	Name	Notes
1	`other`	Other
2	`invoice`	Invoice	Most common type
3	`credit_note`	Credit note	Requires `applies_to_invoice`

POST /documents/{document_number}¶

Creates a new document. Returns 409 if the document number already exists for this tenant. Use PUT for an idempotent upsert.

Request Body¶

Field	Type	Required	Description
account_number	string	Yes	Account this document belongs to.
invoice_date	string (ISO 8601)	Yes	Document issue date.
due_date	string (ISO 8601)	Yes	Payment due date.
document_type	string \| integer	No	`invoice`, `credit_note`, or `other` (integers ½/3 also accepted).
applies_to_invoice	string	Conditional	Required when `document_type` is `credit_note`. The invoice number being credited.
invoice_num	string	No	Display invoice number shown in portals. Required for CashApp AR payment matching.
po_number	string	No	Purchase order number.
pdf_name	string	No	Filename for the PDF in the thin-billing delivery bundle. Must match the filename uploaded via the PDF API. Defaults to `{document_number}.pdf` if omitted.
ship_to_account_num	string	No
ship_to_address_street	string	No	Ship-to street address.
ship_to_address_suite	string	No	Ship-to suite / unit.
ship_to_address_city	string	No	Ship-to city.
ship_to_address_state	string	No	Ship-to state / province.
ship_to_address_zip	string	No	Ship-to postal / ZIP code.
ship_to_address_country	string	No	Ship-to country (ISO 3166-1 alpha-2).

For product-specific fields (currency, denomination, custom fields, etc.) see the Schemas section.

Status Codes¶

Status	Description
201	Document created.
409	Document already exists. Use PUT to replace or PATCH to update.
422	Validation failure.

Example Request¶

curl -X POST https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "ACCT-001",
    "document_type": "invoice",
    "invoice_num": "INV-001",
    "invoice_date": "2026-05-12",
    "due_date": "2026-06-11",
    "currency": "USD",
    "original_denomination": 1500.00,
    "denomination": 1500.00,
    "description": "Services rendered May 2026"
  }'

Example Response — 201¶

{
  "csrId": 12345,
  "documentNumber": "INV-001",
  "account_number": "ACCT-001",
  "document_type": "invoice",
  "invoice_num": "INV-001",
  "invoice_date": "2026-05-12",
  "due_date": "2026-06-11",
  "currency": "USD",
  "original_denomination": 1500.00,
  "denomination": 1500.00,
  "status": "open",
  "createdAt": "2026-05-12T14:00:00.000Z",
  "updatedAt": "2026-05-12T14:00:00.000Z"
}

PUT /documents/{document_number}¶

Creates or replaces a document. Returns 201 on create and 200 on replace. Safe to retry.

If a previously-closed document is replaced with a non-zero denomination, it transitions back to open. If replaced with denomination: 0, it remains or transitions to closed.

Status Codes¶

Status	Description
201	Document created.
200	Document replaced.
422	Validation failure.

GET /documents/{document_number}¶

Retrieves a document including its current status.

Status Codes¶

Status	Description
200	Document found.
404	Document not found.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001 \
  -H "X-API-Key: <your-api-key>"

PATCH /documents/{document_number}¶

Partially updates a document. Only fields present in the request body are modified.

Note

Array fields (e.g. line_items) are replaced wholesale — send the complete desired array, not a delta.

Note

If the PATCH results in denomination = 0, the document is automatically closed. If a closed document is PATCHed with a non-zero denomination, it is automatically reopened.

Status Codes¶

Status	Description
200	Document updated. Returns the updated document.
404	Document not found.
422	Validation failure.

Example Request¶

curl -X PATCH https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 1200.00,
    "comment": "Adjusted after partial payment"
  }'

POST /documents/{document_number}/closure¶

Explicitly closes an open document with a specified reason. Returns 409 if the document is already closed.

Note

You can also auto-close a document by sending a PUT or PATCH with denomination: 0. Use this endpoint when you need to record a specific closure reason.

Request Body¶

Field	Type	Required	Description
closure_reason	string	Yes	One of: `paid`, `write_off`, `contra`, `adjustment`, `other`
closure_date	string (ISO 8601)	No	Override closure timestamp. Defaults to current time.
notes	string	No	Free-text note stored alongside the closure record.

Status Codes¶

Status	Description
200	Document closed. Returns the updated document.
404	Document not found.
409	Document is already closed.

Example Request¶

curl -X POST https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001/closure \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "closure_reason": "paid",
    "closure_date": "2026-05-12T14:00:00Z",
    "notes": "Full payment received via wire transfer"
  }'

Example Response — 200¶

{
  "csrId": 12345,
  "documentNumber": "INV-001",
  "status": "closed",
  "closure_reason": "paid",
  "closedAt": "2026-05-12T14:00:00.000Z",
  "updatedAt": "2026-05-12T14:00:00.000Z"
}

PDF Attachments¶

PDF attachments are uploaded via the Data Bridge PDF API, not this endpoint. Ingest connections are automatically configured in api-push mode. See PDF Push for full setup instructions.

GET /documents/{document_number}/attachments¶

Lists all PDF attachments for a document. Returns metadata only — binary content is never included.

Status Codes¶

Status	Description
200	Success. Returns attachment list (may be empty).
404	Parent document not found.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001/attachments \
  -H "X-API-Key: <your-api-key>"

Example Response — 200¶

{
  "document_number": "INV-001",
  "attachments": [
    {
      "id": "6648a1f2e4b0c3d5f7a9b012",
      "csrId": 12345,
      "documentNumber": "INV-001",
      "fileSize": 204800,
      "uploadedAt": "2026-05-12T14:00:00.000Z"
    }
  ]
}

GET /documents/{document_number}/attachments/{id}¶

Downloads the binary content of a single PDF attachment.

Status Codes¶

Status	Description
200	File binary returned with `Content-Disposition`, `Content-Type`, and `Content-Length` headers.
404	Attachment not found.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/documents/INV-001/attachments/6648a1f2e4b0c3d5f7a9b012 \
  -H "X-API-Key: <your-api-key>" \
  --output invoice.pdf