Function: ApplyVendorCredit

The ApplyVendorCredit function applies vendor credit to bills in Tipalti. The vendor credit and bills must exist in Tipalti before this function can be applied.

  • If the vendor credit has not yet been applied to the bill in Tipalti (i.e., the vendor credit/ bill relation does not exist), then a new relation will be created and the bill will be credited.
  • If part of the vendor credit has already been applied to the bill in Tipalti (i.e., the vendor credit/ bill relation exists), then the existing applied amount will be updated.

In both cases, the bill and vendor credit statuses and the amounts due are updated accordingly.

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

<ApplyVendorCredit xmlns="http://Tipalti.org/">

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<vendorCreditRefCode>string</vendorCreditRefCode>

<relatedInvoices>

<RelatedInvoice>

<InvoiceRefCode>string</InvoiceRefCode>

<AppliedAmount>decimal</AppliedAmount>

</RelatedInvoice>

<RelatedInvoice>

<InvoiceRefCode>string</InvoiceRefCode>

<AppliedAmount>decimal</AppliedAmount>

</RelatedInvoice>

</relatedInvoices>

</ApplyVendorCredit>

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

<ApplyVendorCreditResponse xmlns="http://Tipalti.org/">

<ApplyVendorCreditResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<InvoiceResponses>

<TipaltiApplyVendorCreditItemResponse>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<InvoiceRefCode>string</InvoiceRefCode>

</TipaltiApplyVendorCreditItemResponse>

<TipaltiApplyVendorCreditItemResponse>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<InvoiceRefCode>string</InvoiceRefCode>

</TipaltiApplyVendorCreditItemResponse>

</InvoiceResponses>

<VendorCreditResponse>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<InvoiceRefCode>string</InvoiceRefCode>

</VendorCreditResponse>

</ApplyVendorCreditResult>

</ApplyVendorCreditResponse>

</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
vendorCreditRefCode
  • The reference code for the vendor credit
  • If the vendor credit is in a "Paid" status, the relation between the vendor credit and bill is removed
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
  • The vendor credit must already exist in Tipalti
  • Valid vendor credit status in Tipalti:
    • Pending payment
    • Partially paid
    • Paid
 Mandatory string
relatedInvoices
  • List of bills already related (or to be related) to the vendor credit
  • Each bill is of type RelatedInvoice.
  • Leave this array empty to remove the existing relations between the vendor credit and all related bills.
   Mandatory Array of Related
Invoice

RelatedInvoice

element

description

LIMITATION

Mandatory?

data type
InvoiceRefCode
  • The reference code of the bill to which the vendor credit is to be applied
  • If the bill is in a "Paid" status, the applied vendor credit can only be amended or deleted.
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
  • The bill must already exist in Tipalti
  • Valid bill status in Tipalti:
    • Pending payment
    • Partially paid
    • Paid
 Optional string
AppliedAmount The amount of vendor credit to apply to the bill
  • Value must be a positive decimal number (max. of 2 decimal places)
  • AppliedAmount ≤ amount due on the bill
  • Sum of all AppliedAmounts ≤ amount due on the vendor credit
 Optional decimal

Response parameters

element

description

data type
ApplyVendorCreditResult Contains the response parameters TipaltiApplyVendorCreditResponse (extension of TipaltiResponse)

TipaltiApplyVendorCreditResponse

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
InvoiceResponses
  • List of results for the bills to which vendor credit was applied
  • Each invoice response is of type TipaltiApplyVendorCredit
    ItemResponse.
   Array of TipaltiApplyVendor
CreditItemResponse
VendorCreditResponse Contains the results for the vendor credit that was applied to the bills   TipaltiApplyVendor
CreditItemResponse
TipaltiApplyVendorCreditItemResponse

element

description

Limitation

data type
ErrorMessage A description of the error related to the application of the vendor credit   string
Succeeded
  • Indicates whether or not the vendor credit was applied to the bills
  • If vendor credit failed to be applied to any bill, the entire request fails
   boolean
InvoiceRefCode The reference code for the bill or vendor credit
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string