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: V3

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 /v3/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>

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<IncomeType>string</IncomeType>

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

<Name>string</Name>

<Number>string</Number>

<ExternalId>string</ExternalId>

<Description>string</Description>

<MiscBox1099>string</MiscBox1099>

<Type>string</Type>

<Currency>string</Currency>

</GLAccount>

<LineType>string</LineType>

<LineExternalMetadata>string</LineExternalMetadata>

<Quantity>decimal</Quantity>

<BillLineID>string</BillLineID>

<TaxCodeExternalId>string</TaxCodeExternalId>

<TaxAmount>decimal</TaxAmount>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<ItemNumber>string</ItemNumber>

<Quantity>decimal</Quantity>

<Amount>decimal</Amount>

<ExternalLineId>string</ExternalLineId>

<ItemExternalId>string</ItemExternalId>

<PoLineGlAccountExternalId>string</PoLineGlAccountExternalId>

<PoLineUnitName>string</PoLineUnitName>

<PoLineUnitExternalId>string</PoLineUnitExternalId>

</TipaltiRelatedPurchaseOrder>

</RelatedPurchaseOrders>

</InvoiceLine>

</InvoiceLines>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<ApprovalDate>dateTime</ApprovalDate>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

</TipaltiInvoiceItem>

<Idap>string</Idap>

<InvoiceRefCode>string</InvoiceRefCode>

<InvoiceDate>dateTime</InvoiceDate>

<InvoiceDueDate>dateTime</InvoiceDueDate>

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<IncomeType>string</IncomeType>

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

<Name>string</Name>

<Number>string</Number>

<ExternalId>string</ExternalId>

<Description>string</Description>

<MiscBox1099>string</MiscBox1099>

<Type>string</Type>

<Currency>string</Currency>

</GLAccount>

<LineType>string</LineType>

<LineExternalMetadata>string</LineExternalMetadata>

<Quantity>decimal</Quantity>

<BillLineID>string</BillLineID>

<TaxCodeExternalId>string</TaxCodeExternalId>

<TaxAmount>decimal</TaxAmount>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<ItemNumber>string</ItemNumber>

<Quantity>decimal</Quantity>

<Amount>decimal</Amount>

<ExternalLineId>string</ExternalLineId>

<ItemExternalId>string</ItemExternalId>

<PoLineGlAccountExternalId>string</PoLineGlAccountExternalId>

<PoLineUnitName>string</PoLineUnitName>

<PoLineUnitExternalId>string</PoLineUnitExternalId>

</TipaltiRelatedPurchaseOrder>

</RelatedPurchaseOrders>

</InvoiceLine>

</InvoiceLines>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<ApprovalDate>dateTime</ApprovalDate>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

<RefCode>string</RefCode>

<AppliedAmount>double</AppliedAmount>

</TipaltiVendorCredit>

</VendorCredits>

</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

If you want to mark an invoice as manually paid, do not include the "InvoiceStatus" parameter in the request. Leaving the parameter with a null value will fail the request.
- Incorrect request
- Correct request

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
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
InvoiceLines	List of invoice lines Each invoice line is of type InvoiceLine. Note: To create an invoice with no lines, leave this parameter empty.		Optional	Array of InvoiceLine
InvoiceStatus	The status of the bill Only logical values are allowed (e.g., a bill status cannot change from "PendingPayment" to "PendingApproval"). If the value PendingApAction is used, the status reason "Set by an external system" is attached to the bill. For status descriptions, see Bill Statuses.	Valid values: PendingReview (default) PendingApproval PendingApAction PendingPayment SubmittedForPayment Disputed Deleted	Optional	string
Currency	The currency of the invoice	Length = 3 (per ISO 4217)	Optional	string
Approvers	List of bill approvers If the approver is new, then the bill are created without the approver assigned to it. Note: This field can be empty and the default approvers that was set up will be used.		Mandatory	Array of Tipalti Invoice Approver
InvoiceNumber	The number of the invoice	Max. length = 256	Optional	string
ApprovalDate	Date and time the invoice was approved for payment	YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section	Optional	dateTime
VendorCredits	List of vendor credits applied to the payment		Optional	Array of TipaltiVendorCredit

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
GLAccount	List of GL account details for the GL account linked to the invoice line	Can only be updated if bill status is currently: PendingApReview PendingApproval PendingApAction	Optional	GLAccount
LineType	The type of invoice line: AccountBased - the line is based on the GL account linked to the invoice line ItemBased - the line is based on an item in the invoice	Valid values: AccountBased ItemBased	Optional	string
LineExternalMetadata	The item ID for the item-based line Only applies if LineType = ItemBased		Optional	string
Quantity	The number of items for the item-based line Only applies if LineType = ItemBased		Optional	decimal
BillLineID	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
TaxCodeExternalId	The type of tax code and its rate—e.g., VAT-UK (20%)		Mandatory, if TaxAmount is included	string
TaxAmount	The amount of tax for the line A negative number (for vendor credit) is allowed		Optional	decimal
RelatedPurchaseOrders	List of purchase orders related to the invoice Each purchase order is of type TipaltiRelatedPurchaseOrder		Optional	Array of TipaltiRelated PurchaseOrder

GLAccount

If the ExternalId does not exist in Tipalti, a new GL A general ledger (GL) is used for recording transactions related to business assets, liabilities, equity, revenue and expenses. account is created.

element	Description	Limitation	Mandatory?	Data Type
Name	The name of the GL account	Max. length = 450	Mandatory	string
Number	The number of the GL account GL account numbers must be unique.	Max. length = 450	Optional	integer
ExternalId	An ID that uniquely identifies the GL account (e.g., in NetSuite, it is the "Internal ID")	Max. length = 100	Mandatory	string
Description	A description of the GL account	Max. length = 450	Optional	string
MiscBox1099	The number of the corresponding box on the 1099-MISC form If the field is left empty (NULL), the account will be considered "unmapped".	Valid values for expense accounts: Non applicable 1 2 3 5 6 7 8 9 10 11 12 13 14 nec1 nec2 Note: The values above apply to the "New IRS format (2020 and onwards)". Click here to see the "Old IRS format (pre-2020)".	Optional	string
Type	The type of GL account	Valid values: Expense (default) Accounts payable Bank Credit card	Optional	string
Currency	The currency of the GL account	Length = 3 (per ISO 4217)	Optional	string

TipaltiRelatedPurchaseOrder

Element	Description	Limitations	Mandatory?	Data type
PurchaseOrderNumber	An identifier for the purchase order		Mandatory	string
ItemNumber	Code for the purchase order line		Mandatory	string
Quantity	Quantity of the purchase order line	Max. of two decimal places	Mandatory	decimal
Amount	Amount of the purchase order line	Max. of two decimal places	Mandatory	decimal
ExternalLineId	The identifier of the purchase order line in your accounting system		Optional	string
ItemExternalId	The identifier of the item line		Optional	string
PoLineGlAccountExternalId	The identifier of the PO line linked to the GL account		Optional	string
PoLineUnitName	Name of the unit for the PO line		Optional	string
PoLineUnitExternalId	The identifier of the unit for the PO line		Optional	string

KeyValuePair

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

TipaltiInvoiceApprover

element	Description	Mandatory?	Data Type
Name	Name of bill approver	Optional	string
Email	Email address of bill approver	Optional	string
Order	The order of the approver in a sequence of approvers If no value is included, the system will use the order of appearance in the array.	Optional	integer

TipaltiVendorCredit

element	Description	Mandatory?	Data Type
RefCode	The reference code for the vendor credit	Mandatory	string
AppliedAmount	The amount of vendor credit applied to the bill	Mandatory	double

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