Invoicing Schemas
All fields applicable to the Invoicing product. Invoicing is the most field-rich product — it includes L2/L3 BPN payment fields, UDP custom fields, and optionally Thick Billing data elements for Billtrust-generated PDFs.
For shared schemas (Currency Models, Address, Line Items, etc.) see Shared Schemas & Currency Models.
Account
| Field |
Type |
Required |
Description |
| reference |
string |
Yes |
Caller-defined unique identifier. |
| display_reference |
string |
No |
Display account number shown in portals. |
| name |
string |
Yes |
Customer name. |
| billing_address |
Address object |
Conditional |
Required for Invoicing PDF rendering. See Shared Schemas. |
| billing_address.address1 |
string |
Yes |
Primary billing street address line. Required for Invoicing. |
| billing_address.address2 |
string |
No |
Secondary billing address line. |
| billing_address.city |
string |
Yes |
Billing city. Required for Invoicing. |
| billing_address.state |
string |
Yes |
Billing state / province. Required for Invoicing. |
| billing_address.zip |
string |
Yes |
Billing postal code. Required for Invoicing. |
| billing_address.country |
ISO 3166-1 alpha-2 |
No |
Billing country. |
Document
Core Fields
| Field |
Type |
Required |
Description |
| account_number |
string |
Yes |
Account this document belongs to. |
| invoice_num |
string |
Conditional |
Display invoice number shown in portals. If omitted, the URL path document_number is used. |
| applies_to_invoice |
string |
Conditional |
Required when document_type is credit_note. |
| invoice_date |
date (ISO 8601) |
Yes |
Document issue date. |
| due_date |
date (ISO 8601) |
Yes |
Payment due date. |
| pdf_name |
string |
Conditional |
Filename of the PDF to associate with this document. Required when sending PDFs via API Push. If absent and Thick Billing data elements are present, Billtrust generates the PDF. If absent with no Thick Billing data, no PDF is created and no invoice is sent. |
| branch_name |
string |
Conditional |
Branch / territory / division identifier. Required for multi-entity deployments or Virtual eInvoice Connect sites. Controls PDF branding and routing. |
| po_number |
string |
No |
Purchase order number. |
| ship_to_account_num |
string |
No |
Ship-to customer account number. |
| 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). |
| discount_date |
date |
No |
Early-payment discount expiry date. |
| discount_amount |
string |
No |
Early-payment discount amount. |
| routing |
string |
No |
Document routing code (E=Email, F=Fax, M=Mail, P/Q/R/T=Pull/Do Not Send). |
| dest_email_address |
string |
No |
Destination email address for document delivery. |
| dest_fax_number |
string |
No |
Destination fax number for document delivery. |
L2 / L3 BPN Payment Fields
These fields support Level 2 and Level 3 BPN (Billtrust Payment Network) data for enhanced payment processing and interchange optimization.
| Field |
Type |
Description |
| ship_from_zip |
string |
ZIP code from which the product was shipped. |
| duty_amt |
string |
Duty amount. |
| merchant_name |
string |
Merchant / supplier / seller business name or IRS EIN. |
| part_number |
string |
Part / product number. |
| commodity_code |
string |
Commodity / product code at document level. |
| tax_rate |
decimal |
Tax rate applied at document level. |
Custom Fields (UDP)
Up to 5 User Defined Properties, configurable to display as columns in Client Connect and eInvoice Connect portals.
| Field |
Type |
Description |
| udp1 |
string |
Invoicing custom field 1 |
| udp2 |
string |
Invoicing custom field 2 |
| udp3 |
string |
Invoicing custom field 3 |
| udp4 |
string |
Invoicing custom field 4 |
| udp5 |
string |
Invoicing custom field 5 |
Financial Fields — Basic Currency Model
Note
For Invoicing, only original_denomination applies from the Basic model. currency and denomination are not used by the Invoicing pipeline.
| Field |
Type |
Required |
Description |
| original_denomination |
denomination |
Conditional* |
Original gross amount in document currency. Does not change when partially paid. Must be negative for credit notes. *Required when using the Basic currency model. |
Financial Fields — Extended Currency Model
Note
For Invoicing, only original_denomination_in_original_currency applies from the Extended model.
| Field |
Type |
Required |
Description |
| original_denomination_in_original_currency |
denomination |
Conditional* |
Original gross amount in original_currency. Does not change when partially paid. *Required when using the Extended currency model. |
Thick Billing Data Elements
These fields supply rendering data for Billtrust-generated PDFs. When pdf_name is absent from Document Core and Thick Billing fields are present, Data Bridge generates the PDF. Fields already in Document Core (account_number, invoice_date, branch_name, routing, po_number, due_date, discount_amount, discount_date, udp1–udp5) can be omitted here.
Document Header — Mandatory
| Field |
Type |
Required |
Description |
| BRANCH_NUMBER |
string |
Yes |
Branch / territory number |
| BRANCH_NAME |
string |
Yes |
Branch name |
| BRANCH_PHONE |
string |
No |
Branch phone number |
| INVOICE_NUMBER |
string |
Yes |
Invoice number (max 50 chars) |
| INVOICE_DATE |
date |
Yes |
Invoice date (max 15 chars) |
| DOC_TYPE |
string |
No |
Invoice or Credit Memo |
| ACCOUNT_NUMBER |
string |
Yes |
Bill-to customer account number (max 30 chars) |
| TERMS |
string |
No |
Payment terms description |
| DUE_DATE |
date |
No |
Payment due date (max 15 chars) |
| DISCOUNT_AMOUNT |
decimal(2) |
No |
Early-payment discount amount |
| DISCOUNT_MESSAGE |
string |
No |
Human-readable discount message (max 200 chars) |
| DISCOUNT_DATE |
date |
No |
Early-payment discount expiry date |
| PO_NUMBER |
string |
No |
Customer purchase order number (max 50 chars) |
| ORDER_NUMBER |
string |
No |
Sales order number |
| ORDER_DATE |
date |
No |
Order date |
| SHIP_DATE |
date |
No |
Ship date |
| ORDER_BY |
string |
No |
Name of the person who placed the order |
| RELEASE_NUMBER |
string |
No |
Release / delivery number |
| SALESPERSON |
string |
No |
Salesperson name |
| SHIP_VIA |
string |
No |
Shipping carrier / method |
| WRITER |
string |
No |
Document author / writer |
| SHIPPING_INSTRUCTIONS |
string |
No |
Special shipping instructions |
| TRACKING_NUMBER |
string |
No |
Shipment tracking number |
| SUBTOTAL |
decimal(2) |
No |
Document subtotal amount |
| FREIGHT |
decimal(2) |
No |
Freight amount |
| HANDLING |
decimal(2) |
No |
Handling charge amount |
| SALES_TAX |
decimal(2) |
No |
Sales tax amount |
| MISC_TAX1 |
decimal(2) |
No |
Miscellaneous tax amount 1 |
| MISC_TAX2 |
decimal(2) |
No |
Miscellaneous tax amount 2 |
| PAYMENT_AMOUNT |
decimal(2) |
No |
Payment amount |
| TOTAL_DUE |
decimal(2) |
No |
Total amount due |
| CURRENCY |
string |
No |
Currency code |
| FLAG_DUPLICATE |
boolean |
No |
Duplicate indicator |
| CONTRACT_NUMBER |
string |
No |
Contract number |
| SUPPLIER_TAX_ID |
string |
No |
Supplier tax identification number |
| SERVICE_DATE |
date |
No |
Date services were rendered |
| SERVICE_CHARGE |
decimal(2) |
No |
Service charge amount |
| BPNI_EMAIL |
string |
No |
BPNi email address |
| UDP1–UDP5 |
string |
No |
BT System user defined properties 1–5 |
| USER_DEFINED_DATA1–7 |
string |
No |
User defined header data 1–7 |
| MISC_COST |
decimal(2) |
No |
Miscellaneous cost |
| TOTAL_PARTS |
decimal(2) |
No |
Total parts amount |
| TOTAL_LABOR |
decimal(2) |
No |
Total labor amount |
| GST_TAX |
decimal(2) |
No |
GST (Goods and Services Tax) |
| HST_TAX |
decimal(2) |
No |
HST (Harmonized Sales Tax) |
| PST_TAX |
decimal(2) |
No |
PST (Provincial Sales Tax) |
| QST_TAX |
decimal(2) |
No |
QST (Quebec Sales Tax) |
| VAT_TAX |
decimal(2) |
No |
VAT (Value Added Tax) |
| HEADER_MESSAGE |
string |
No |
Custom message displayed in the invoice header |
| FOOTER_MESSAGE |
string |
No |
Custom message displayed in the invoice footer |
| LINE_ITEM_COUNT |
numeric |
No |
Total number of line items on the document |
Routing — Mandatory
| Field |
Type |
Description |
| ROUTING |
string |
Routing code: E=Email, F=Fax, M=Mail, P/Q/R/T=Pull/Do Not Send |
| EMAIL_ADDRESS |
string |
Email address |
| EMAIL_REPLY_OVERRIDE |
string |
Reply-to address override |
| EMAIL_SUBJECT_BIZ_NAME |
string |
Email sender business name override |
| EMAIL_SUBJECT_OVERRIDE |
string |
Email subject line override |
| FAX_NUMBER |
numeric |
Fax number |
Addresses (Billing, Remit, Shipping, Return)
| Field |
Type |
Required |
Description |
| BILLING_ADDRESS1 |
string |
Yes |
Bill-to address line 1 / customer name (max 45 chars) |
| BILLING_ADDRESS2 |
string |
Yes |
Bill-to address line 2 (max 45 chars) |
| BILLING_ADDRESS3 |
string |
Yes |
Bill-to address line 3 (max 45 chars) |
| BILLING_CITY |
string |
Yes |
Bill-to city |
| BILLING_STATE |
string |
Yes |
Bill-to state |
| BILLING_PROVINCE |
string |
No |
Bill-to province |
| BILLING_ZIP |
string |
Yes |
Bill-to ZIP code |
| BILLING_COUNTRY |
string |
Yes |
Bill-to country (max 30 chars) |
| REMIT_ADDRESS_LINE1–3 |
string |
No |
Remit-to address lines 1–3 (max 100 chars each) |
| REMIT_ADDRESS_CITY |
string |
No |
Remit-to city |
| REMIT_ADDRESS_STATE |
string |
No |
Remit-to state |
| REMIT_ADDRESS_ZIP |
string |
No |
Remit-to ZIP code |
| REMIT_ADDRESS_COUNTRY |
string |
No |
Remit-to country |
| REMIT_PHONE / REMIT_FAX |
string |
No |
Remit-to phone / fax |
| SHIP_TO_ACCT_NUM |
string |
No |
Ship-to customer ID |
| SHIP_TO_NAME |
string |
No |
Ship-to name / address line 1 |
| SHIPPING_ADDRESS2–3 |
string |
No |
Ship-to address lines 2–3 |
| SHIPPING_ADDRESS_CITY |
string |
No |
Ship-to city |
| SHIPPING_ADDRESS_STATE |
string |
No |
Ship-to state |
| SHIP_TO_ZIP |
string |
No |
Ship-to ZIP code |
| SHIPPING_COUNTRY |
string |
No |
Ship-to country |
| RETURN_ADDRESS_LINE1–3 |
string |
No |
Return address lines 1–3 |
| RETURN_ADDRESS_CITY / STATE / ZIP / COUNTRY |
string |
No |
Return address fields |
Line Items (DETAIL)
| Field |
Type |
Description |
| LINE_NUM_COL |
string |
Line number |
| ITEM_NUMBER_COL |
string |
PO line item number |
| ITEM_CODE_COL |
string |
Product code / part number |
| DESC_COL |
string |
Item description |
| QTY_ORDER_COL |
decimal |
Quantity ordered |
| QTY_SHIP_COL |
decimal |
Quantity shipped |
| QTY_BO_COL |
decimal |
Quantity backordered |
| UOM_COL |
string |
Unit of measure |
| ITEM_UNIT_PRICE_COL |
decimal |
Unit price |
| NET_UNIT_PRICE_COL |
decimal |
Net unit price |
| DISC_AMT_COL |
decimal |
Discount amount |
| NET_AMOUNT_COL |
decimal |
Extended / net amount |
| TAX_COL |
string |
Tax flag |
| LINE_ITEM_TAX_COL |
decimal |
Line item tax amount |
| LINE_ITEM_TAX_CODE_COL |
string |
Line item tax code |
| ITM_USER_DEFINE1_COL–7_COL |
string |
User defined line item data 1–7 |
| COMMENT_COL |
string |
Comments |
| CMT_USER_DEFINE1_COL–7_COL |
string |
User defined comment data 1–7 |
Line Items (API)
Sent as a JSON array in the line_items field on the document object — separate from the Thick Billing fields above. See Line Item Object.
Closure
| Field |
Type |
Required |
Description |
| closure_reason |
string |
Yes |
One of: paid, write_off, contra, adjustment, other |
| closure_date |
date (ISO 8601) |
No |
Date of closure. Defaults to current date if absent. |
| notes |
string |
No |
Free-text notes on the closure. |