Function: CreateOrUpdateInvoices

The CreateOrUpdateInvoices function creates or updates invoices. If you use a payee ID that does not exist in the system, a new payee will be created.

If you do not have a reference code, you can auto-generate one by excluding the InvoiceRefCode element in the request.

For bills management, bill financials (e.g., currency, amount, account) can only be updated if the current status of the bill is "PendingApReview" or "PendingApAction".

When using this API function, it is recommended that you don't send more than 200 bills in the request. If you need to create more than 200 bills, please create several requests.

EAT Encryption Additional Terms parameter: None
API version: V1

The following is a sample SOAP 1.2 request and response. In the request, you need to replace the data types in yellow with actual values.

SOAP 1.2: Request

POST /payerfunctions.asmx HTTP/1.1

Host: api.tipalti.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<Idap>string</Idap>

<InvoiceRefCode>string</InvoiceRefCode>

<InvoiceDate>dateTime</InvoiceDate>

<InvoiceDueDate>dateTime</InvoiceDueDate>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</InvoiceLine>

</InvoiceLines>

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<IncomeType>string</IncomeType>

</TipaltiInvoiceItem>

<Idap>string</Idap>

<InvoiceRefCode>string</InvoiceRefCode>

<InvoiceDate>dateTime</InvoiceDate>

<InvoiceDueDate>dateTime</InvoiceDueDate>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</InvoiceLine>

</InvoiceLines>

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<IncomeType>string</IncomeType>

</TipaltiInvoiceItem>

</invoices>

</CreateOrUpdateInvoices>

</soap12:Body>

</soap12:Envelope>

SOAP 1.2: Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

</CreateOrUpdateInvoicesResult>

</CreateOrUpdateInvoicesResponse>

</soap12:Body>

</soap12:Envelope>

Request parameters

element	description	limitation	Mandatory?	data type
payerName	The name of the payer, as assigned by Tipalti	Max. length = 50 Value is case sensitive	Mandatory	string
timestamp	Current time (UTC) when the request is sent	Unix time	Mandatory	double
key	Encryption key		Mandatory	string
invoices	List of invoice items Each invoice item is of type TipaltiInvoiceItemRequest.		Mandatory	Array of TipaltiInvoice ItemRequest

TipaltiInvoiceItem

Element	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	Mandatory	string
InvoiceRefCode	The reference code for the invoice To auto-generate a reference code, exclude the element in the request.	ASCII: max. length = 16 (Account Direction model: max. length = 15) Valid special characters: hyphens, underscores	Optional to include the element, but if tags are included, a value is mandatory. Otherwise, an error is returned.	string
InvoiceDate	Invoice value date (estimated date and time the payee receives the funds)	YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section	Mandatory	dateTime
InvoiceDueDate	The date and time the invoice is due to be paid	YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section	Optional, if payment terms have been defined in Tipalti (if a value is entered, Tipalti will not compute a bill due date) Mandatory, if the NetNow feature is enabled for the payee	dateTime
InvoiceLines	List of invoice lines Each invoice line is of type InvoiceLine.		Optional	Array of InvoiceLine
Description	A description of the invoice	Max. length = 256	Optional	string
CanApprove	Indicates whether or not the payee is able to approve the invoice		Mandatory	boolean
InvoiceInternalNotes	Notes that are not displayed to the payee	Max. length = 256 Default = null	Optional	string
CustomFields	If custom fields have been defined for the bill/ invoice entity, the values of these fields can be set here. The field name must match the defined custom field name.	Default = null Max. length = 140 for "free text" entries Must be common across all lines of the same bill/ invoice	Optional	Array of KeyValuePair
IsPaidManually	If TRUE, the invoice is marked as paid manually		Mandatory	boolean
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.	See Income types. Default = null	Mandatory, if more than one income type is enabled	string

InvoiceLine

element	description	limitation	Mandatory?	data type
Currency	The currency of the invoice	Length = 3 (per ISO 4217)	Optional	string
Amount	Invoice line amount		Mandatory	double
Description	Description of the invoice line	Max. length = 256	Optional	string
InvoiceInternalNotes	Notes that are not displayed to the payee	Max. length = 256 Default = null	Optional	string
EWalletMessage	A message to attach to the payment This message is sent to providers and appears on payee bank statements. If no value is provided, the InvoiceRefCode is used.	Max. length = 160 Default = null	Optional	string
BankingMessage	A message to attach to the payment This message is sent to providers and appears on payee bank statements. If a value is not provided, the EWalletMessage is used.	Max. length = 160 Default = null Supported for: ACH Check Global ACH/Local bank transfer Wire transfer	Optional	string
CustomFields	If custom fields have been defined for the bill/ invoice line entity, the values of these fields can be set here. The field name must match the defined custom field name.	Default = null Max. length = 140 for "free text" entries	Optional	Array of KeyValue Pair

KeyValuePair

Element	description	Mandatory?	data type
Key	Name of field	Optional	string
Value	Value of field	Optional	string

Response parameters

element	description	data type
CreateOrUpdateInvoicesResult	Contains the response parameters	TipaltiResponse

TipaltiResponse

element	description	Limitation	data type
errorMessage	A description of the error	See API error codes.	string
errorCode	The status of the error	See API error codes.	string
b	If the return code is Boolean, this parameter will carry the value.		boolean
i	If the return code is integer, this parameter will carry the value.		integer
d	If the return code is double, this parameter will carry the value.		double
s	If the return code is string, this parameter will carry the value.		string