Function: CreateOrUpdateInvoices

The CreateOrUpdateInvoices function creates or updates invoices, and allows marking bills as paid manually. 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, general bill information (e.g., invoice number, dates) and bill financials (e.g., currency, amount, account) can only be updated if the current bill status is a valid status:

For "Invoice Processing" and all "Self-billing" flows, the valid statuses are "PendingAPReview" or "PendingAPAction".
For "Tipalti bills" flow, the valid status is "PendingPayment".

If the status of the bill (before the update request) is not a valid status, general bill information and bill financials will not be updated. If other fields are included in the same request (such as Bill status), those will update successfully and a success result will be returned.

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.

Error code: 1015-InvoiceValidationError

In case of a failed call, the system will return 1015-InvoiceValidationError error code with one of the following error messages:

Error message	description
GL Account and Transaction Date are required to mark the bill as manually paid	Payer is required to send the "ManualPaymentDetails" parameter . This error occurs if the "ManualPaymentDetails" parameter is missing or not valid. The "ManualPaymentDetails" parameter is not valid, if the "GLAccountExternalId" or "TransactionDate" parameters are missing or not valid.
Your configuration doesn’t support providing GL Account or Transaction Date while marking a bill as manually paid. To mark the bill as manually paid, please send "IsPaidManually" = TRUE and don't send "InvoiceStatus"	When a payer shouldn’t send the "ManualPaymentDetails" parameter, and the request contains a value in the "ManualPaymentDetails" parameter, the request will fail.
You can't provide GL Account or Transaction Date while marking a vendor credit as manually paid. To mark the vendor credit as manually paid, please send "IsPaidManually" = TRUE and don't send "InvoiceStatus".	When setting a Vendor Credit as manually paid, the "ManualPaymentDetails" parameter is not required, and the request will fail if it is provided.

EAT Encryption Additional Terms parameter: None
API version: V4

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

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

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<GLAccountExternalId>string</GLAccountExternalId>

<TransactionDate>dateTime<TransactionDate>

</ManualPaymentDetails>

<IncomeType>string</IncomeType>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<PayerEntityName>string</PayerEntityName>

<InvoiceSubject>string</InvoiceSubject>

<ApAccountNumber>string</ApAccountNumber>

</TipaltiInvoiceItemRequest>

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

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

<Description>string</Description>

<CanApprove>boolean</CanApprove>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>boolean</IsPaidManually>

<GLAccountExternalId>string</GLAccountExternalId>

<TransactionDate>dateTime<TransactionDate>

</ManualPaymentDetails>

<IncomeType>string</IncomeType>

<InvoiceStatus>string</InvoiceStatus>

<Currency>string</Currency>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<InvoiceNumber>string</InvoiceNumber>

<PayerEntityName>string</PayerEntityName>

<InvoiceSubject>string</InvoiceSubject>

<ApAccountNumber>string</ApAccountNumber>

</TipaltiInvoiceItemRequest>

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

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<InvoiceRefCode>string</InvoiceRefCode>

</TipaltiInvoiceItemResult>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<InvoiceRefCode>string</InvoiceRefCode>

</TipaltiInvoiceItemResult>

</InvoiceErrors>

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

TipaltiInvoiceItemRequest

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
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
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	Payer needs to be using the "No Approval" flow. InvoiceStatus parameter must be null to set an invoice as manually paid.	Mandatory	boolean
ManualPaymentDetails	Details of the manual invoice/ bill payment		Mandatory when IsPaidManually = TRUE	Array of ManualPaymentDetails
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
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: PendingApReview (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
PayerEntityName	The name of the payer entity linked to the invoice	Max. length = 100 Alphanumeric characters only	Mandatory, if more than one income type is enabled	string
InvoiceSubject	The text for the title of the invoice Displays for the payee in the iFrame or Supplier Hub	Max. length = 250 Must be common across all lines of the same bill	Mandatory for the Tipalti bills and self-billing flows Optional for invoice processing flow	string
ApAccountNumber	The default GL account number (credited with invoice amounts) to link to the invoice	Max. length = 450	Mandatory, if multiple AP accounts have been defined in Tipalti	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
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 four decimal places	Mandatory	decimal
Amount	Amount of the purchase order line	Max. of four 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

ManualPaymentDetails

Element	description	Limitations	Mandatory?	data type
GLAccountExternalId	The external ID of the GL account linked to the invoice that you want to mark as manually paid	Max. length = 450	Mandatory when ManualPaymentDetails is required^*	string
TransactionDate	The date to mark the invoice as manually paid	YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section	Mandatory when ManualPaymentDetails is required^*	dateTime
^* This parameter is required when IsPaidManually = TRUE and the payer follows these conditions: Payer has active GL accounts of type "Bank" or "Credit card" in Tipalti. Payer entity of GL account is the same as the payer entity of the invoice. GL accounts have the same currency as the invoice.

Element

description

Limitations

Mandatory?

data type

GLAccountExternalId

The external ID of the GL account linked to the invoice that you want to mark as manually paid

Max. length = 450

Mandatory when ManualPaymentDetails is required^*

string

TransactionDate

The date to mark the invoice as manually paid

YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section

Mandatory when ManualPaymentDetails is required^*

dateTime

^* This parameter is required when IsPaidManually = TRUE and the payer follows these conditions:

Payer has active GL accounts of type "Bank" or "Credit card" in Tipalti.
Payer entity of GL account is the same as the payer entity of the invoice.
GL accounts have the same currency as the invoice.

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

Response parameters

element	description	data type
CreateOrUpdateInvoicesResult	Contains the response parameters	CreateOrUpdateInvoiceResult (extension of type TipaltiResponse)

CreateOrUpdateInvoiceResult

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
InvoiceErrors	List of invoice item results Each invoice item is of type TipaltiInvoiceItemResult.		Array of TipaltiInvoiceItemResult

TipaltiInvoiceItemResult

element	description	Limitation	data type
ErrorMessage	A description of the error		string
Succeeded	Indicates if the invoice was created or updated successfully		boolean
InvoiceRefCode	The reference code for the invoice	ASCII: max. length = 16 (Account Direction model: max. length = 15) Valid special characters: hyphens, underscores	string