Articles in this section

See more

File format

CSV Bills file

A digital bills file is a CSV file that contains payee payment instructions to Tipalti. If multiple lines pertain to a single bill, then certain field values must be the same across those lines. See the "Limitation" column in the table below.

You can upload this file to Tipalti via the Tipalti Hub.

  • You may include multiple bills in the file.
  • If you submit a bill for a payee that does not exist in Tipalti, the payee will be created.

Click the image below to download a sample of the CSV file structure. You can clear all data in the file and enter your own data for upload.

If you have "Bill coding preferences" feature enabled and you are using the "Self-billing with internal approval only", or "Self-billing with internal and payee approval" bill flow, the custom fields of type "List" set as mandatory for bill processors must be included in the CSV file to avoid upload failure. If you have "Bill coding preferences" feature enabled and you are using the "Tipalti bills" or " Self-billing with payee approval", the expense accountThe general ledger (GL) account that is debited for the payment amount field and custom fields of type "List" set as mandatory for bill approvers must be included in the CSV file to avoid upload failure.

If you are applying discounts or delivery costs to bills, please populate these amounts as separate bill lines.

Digital Bills sample CSV file

File structure

The following table describes the fields in the digital bills file. Fields are not case sensitive.

Field

Description

Limitation

Mandatory?

Data type
Idap Unique payee identifier (the payee ID)

  • Max. length = 64

  • Valid characters:

    • Numbers

    • Letters

    • Commas

    • Periods

    • Underscores

    • Dashes

  • No spaces allowed

  • Must be common across all lines of the same bill

 Mandatory string

BillRefCode (or InvoiceRefCode)
  • The reference code for the bill, assigned by the payer, assigned by the payer
  • This code transfers to the associated payment and to the payment provider
  • The code is referenced in the Bill details report.

  • ASCII: max. length = 16 (Account Direction model: max. length = 15)

  • Valid special characters: hyphens, underscores

 Mandatory string
Action

The action you want to perform:

  • Create a new bill (BillRefCode must be unique)
  • Edit an existing bill
  • Delete an existing bill (indicating one or more deleted lines deletes the entire bill). If the bill is deleted in status "Pending approval", an email notification is sent to the relevant approvers.
  • Valid values:
    • NEW
    • EDIT
    • DELETE
  • Default = NEW
  • Must be common across all lines of the same bill
  • For self-billing, if the bill is in status "Pending approval", "Pending payee approval", "Pending payee invoice" or "Pending payment", EDIT changes the status to "Pending AP action" before updates are applied.
  • For EDIT/ DELETE, the bill cannot be in status:
    • "Submitted for payment"
    • "Paid"
    • "Deleted"
 Optional string
EntityName
  • The name of the payer entity linked to the bill
  • Overrides the default entity assigned to the payee

  • Max. length = 100

  • Alphanumeric characters only

 Optional string
InvoiceNumber
  • The number of the invoice
  • If a value is not provided, the system uses the BillRefCode.

Must be common across all lines of the same bill

 Optional string
InvoiceSubject

  • The text for the title of the invoice

  • Displays for the payee in the iFrame or Supplier Hub

 Max. length = 250

  • Mandatory for the Tipalti bills and self-billing flows

  • Optional for invoice processing flow

 string
InvoiceDescription (or InvoiceInternal
Notes)		 Notes that are not displayed to the payee

  • Max. length = 256

  • Default = null

  • Must be common across all lines of the same bill

 Optional string
InvoiceDate The date the invoice was created

  • MM/DD/YYYY

  • Must be common across all lines of the same bill

 Mandatory date
LineID

  • The bill line identifier

  • If there is no line ID, the system creates one automatically.

  • Must be unique per bill or invoice refcode

  • All bill lines must have an ID (or no ID—the system assigns IDs to all lines)

 Optional string
LineDescription (or Description) Description of the invoice line Max. length = 256 Mandatory string
AccountID The number of the GL account for the bill line for the bill line
  • Must be common across all lines of the same bill
  • Not supported for the Tipalti bills flow
  • Mandatory if the following is enabled:
    • Self-billing
    • GL account selection
    • Auto release; and
    • Internal approval is disabled.
 string
InvoiceDueDate The date the invoice is due to be paid

  • MM/DD/YYYY

  • The invoice due date must be a later date than the invoice date.

  • Must be common across all lines of the same bill

Optional, if payment terms have been defined in Tipalti (if a value is entered, Tipalti will not compute a bill due date)

 date
Currency The currency of the invoice
  • Length = 3 (per ISO 4217)
  • Must be common across all lines of the same bill
 Mandatory string
Quantity The number of units for the bill line description Only positive numbers are allowed Optional double
UnitPrice

  • The price for a single unit of the bill line description

  • A negative number (for vendor credit) is allowed

 Valid characters: digits and an optional decimal point for cents Optional double
LineAmount (or Amount)

  • Line net amount

  • A negative number (for vendor credit) is allowed

  • Valid characters: digits and an optional decimal point for cents

  • If "Quantity" and "Unit Price" are assigned a value, the LineAmount must equal: Quantity × Unit Price

 Mandatory double
LineTaxAmount
  • The amount of tax for the line
  • The tax code must be "Active" for the payer entity or else an error is returned.
 Valid characters: digits and an optional decimal point for cents Optional double
LineTaxCodeExternalId The internal ID (in NetSuite or Tipalti) for the tax code   Mandatory, if LineTaxAmount is included string
TotalNetAmount
  • Sum of all bill line net amounts
  • If a value is not provided, the system calculates the value

  • Valid characters: digits and an optional decimal point for cents; round values to two decimal places

  • Must be common across all lines of the same bill

 Optional double
TaxAmount

  • The total amount of tax charged by the supplier

  • Must equal the sum of all "LineTaxAmount" fields for the supplier

  • A negative number (for vendor credit) is allowed

  • Default = 0

  • Valid characters: digits and an optional decimal point for cents

  • Must be common across all lines of the same bill

 Optional double
TotalAmount

  • Total amount to be paid to the payee

  • If a value is not provided, the system calculates the value

  • A negative number (for vendor credit) is allowed

  • The total amount must equal: Net amount + Delivery costs + Tax amount – Discount

  • Must be common across all lines of the same bill

 Optional double
IncomeType If the Tax Withholding module is enabled and there are multiple income types that can be associated with the payment, then you must enter the income type per payment. Mandatory, if more than one income type is enabled string
ApproverName[x]

  • Name of bill approver

  • The [x] represents the number of the approver in a sequence of approvers (e.g., ApproverName[1]).

 Must be common across all lines of the same bill Optional string
ApproverEmail[x]

  • Email address of bill approver

  • The [x] represents the number of the approver in a sequence of approvers (e.g., ApproverEmail[1]).

  • If the approver is new, then the bill will be created without the approver assigned to it.

  • Valid email format (e.g., user@domain.com)

  • Must be common across all lines of the same bill

 Optional string
RequestPayee
Approval (or CanApprove)
  • If TRUE, the payee can approve invoices via the iFrame or Supplier Hub
  • If FALSE, the payee cannot approve invoices via the iFrame or Supplier Hub (i.e., the payee is asked to send you an invoice)
  • Only applicable for the self-billing flows
  • The default is according to payee setup. This field cannot be used to edit the existing default. To edit the default, see Request for payee approval).
  • Must be common across all lines of the same bill
 Optional boolean
Custom1, Custom2… Custom5 Use these fields to add text at the header or line level to your bill templates. First, you need to create a custom field (e.g., Location) at the header or line level in the Tipalti Hub (see Manage custom fields). Then, you can add Location as a custom field column in this CSV file so that a different location can be assigned to each bill or bill line.

  • Default = null

  • Max. length = 140 for "free text" entries

 Optional string