Function: CreateOrUpdatePurchaseOrders

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

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

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<purchaseOrders>

<TipaltiPurchaseOrderItem>

<Idap>string</Idap>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<Status>string</Status>

<Memo>string</Memo>

<PurchaseOrderDate>dateTime</PurchaseOrderDate>

<PayerEntity>string</PayerEntity>

<Currency>string</Currency>

<Approvers>

<TipaltiInvoiceApprover>

<Name>string</Name>

<Email>string</Email>

<Order>integer</Order>

</TipaltiInvoiceApprover>

</Approvers>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<PurchaseOrderLines>

<PurchaseOrderLine>

<Item>string</Item>

<Quantity>decimal</Quantity>

<Units>string</Units>

<LineDescription>string</LineDescription>

<Rate>decimal</Rate>

<Amount>decimal</Amount>

<DiscountValue>decimal</DiscountValue>

<NetValue>decimal</NetValue>

<Account>string</Account>

<TaxAmount>decimal</TaxAmount>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<PoLineId>string</PoLineId>

<LineType>string</LineType>

<BilledQuantity>decimal</BilledQuantity>

<BilledAmount>decimal</BilledAmount>

<AccountExternalID>string</AccountExternalID>

<ItemExternalID>string</ItemExternalID>

<IsClosed>boolean</IsClosed>

<TaxCodeExternalId>string</TaxCodeExternalId>

<UnitsExternalId>string</UnitsExternalId>

</PurchaseOrderLine>

<PurchaseOrderLine>

<Item>string</Item>

<Quantity>decimal</Quantity>

<Units>string</Units>

<LineDescription>string</LineDescription>

<Rate>decimal</Rate>

<Amount>decimal</Amount>

<DiscountValue>decimal</DiscountValue>

<NetValue>decimal</NetValue>

<Account>string</Account>

<TaxAmount>decimal</TaxAmount>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<PoLineId>string</PoLineId>

<LineType>string</LineType>

<BilledQuantity>decimal</BilledQuantity>

<BilledAmount>decimal</BilledAmount>

<AccountExternalID>string</AccountExternalID>

<ItemExternalID>string</ItemExternalID>

<IsClosed>boolean</IsClosed>

<TaxCodeExternalId>string</TaxCodeExternalId>

<UnitsExternalId>string</UnitsExternalId>

</PurchaseOrderLine>

</PurchaseOrderLines>

</TipaltiPurchaseOrderItem>

</purchaseOrders>

</CreateOrUpdatePurchaseOrders>

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

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

<CreateOrUpdatePurchaseOrdersResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<PurchaseOrderErrors>

<TipaltiPurchaseOrderItemResult>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

</TipaltiPurchaseOrderItemResult>

<TipaltiPurchaseOrderItemResult>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

</TipaltiPurchaseOrderItemResult>

</PurchaseOrderErrors>

</CreateOrUpdatePurchaseOrdersResult>

</CreateOrUpdatePurchaseOrdersResponse>

</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
purchaseOrders
  • List of purchase orders
  • Each purchase order is of type TipaltiPurchaseOrderItem.
  Mandatory Array of Tipalti
Purchase
OrderItem

TipaltiPurchaseOrderItem

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
 Optional string
PurchaseOrderNumber An identifier for the purchase order   Mandatory string
Status Status of the purchase order
  • Valid values:
    • Active (default)
    • Closed
    • Deleted
    • Pending approval
    • Partially billed
  • Values are not case sensitive.
 Optional string
Memo Description of the purchase order   Mandatory string
PurchaseOrderDate Date and time the purchase order was created YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section Mandatory dateTime
PayerEntity Payer entity linked to this transaction
  • Max. length = 100
  • Alphanumeric characters only
 Mandatory, if more than one payer entity has been defined in Tipalti string
Currency Currency of the vendor Length = 3 (per ISO 4217) Mandatory string
Approvers List of bill approvers   Optional Array of TipaltiInvoice
Approver
CustomFields
  • If custom fields have been defined for the purchase order entity, the values of these fields can be set here.
  • The field name must match the defined custom field name.
  • Valid value types:
    • Free text (max. length = 140)
    • List - according to custom field setup (see Value type)
  • Default = null
  • Must be common across all lines of the same bill
 Optional Array of KeyValuePair
PurchaseOrderLines
  • List of purchase order lines
  • Each purchase order line is of type PurchaseOrderLine
     Array of PurchaseOrder
Line
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
KeyValuePair

Element

description

Mandatory?

data type
Key Name of field Optional string
Value Value of field Optional string
PurchaseOrderLine

Element

description

limitation

Mandatory?

Data type
Item Code for the purchase order line   Mandatory string
Quantity Quantity of the purchase order line Max. of four decimal places Mandatory decimal
Units Units of measurement for the purchase order line (e.g., kilograms, pounds, etc.)   Optional string
LineDescription Description of the purchase order line   Optional string
Rate Price of a single line item Max. of four decimal places Mandatory decimal
Amount Amount of the purchase order line (Rate × Quantity) Max. of four decimal places Mandatory decimal
DiscountValue Value of the discount received from the vendor
  • Max. of four decimal places
  • Absolute value, not a percentage
 Optional decimal
NetValue Net value of the purchase order line (i.e., the Amount including any discounts) Max. of four decimal places Optional decimal
Account GL account external reference identifier   Mandatory, if more than one GL account has been defined in Tipalti string
TaxAmount Amount of tax (or VAT) calculated for the purchase order line Max. of four decimal places Optional decimal
CustomFields If custom fields have been defined for the purchase order line entity, the values of these fields can be set here.

Valid value types:

  • Free text
  • List - according to custom field setup (see Value type)
 Optional Array of KeyValuePair
PoLineId
  • An identifier for the purchase order line
  • Must be unique within a single purchase order
   Optional string
LineType The type of purchase order line Valid values:
  • Item (default)
  • Expense
 Mandatory string
BilledQuantity Quantity billed for the purchase order line   Mandatory decimal
BilledAmount Amount billed for the purchase order line   Mandatory decimal
AccountExternalID An ID that uniquely identifies the GL account (e.g., in NetSuite, it is the "Internal ID")   Mandatory string
ItemExternalID An ID that uniquely identifies the purchase order line   Mandatory string
IsClosed If True, the PO line will not be used for matching   Mandatory boolean
TaxCodeExternalId The external ID of the relevant tax code for the PO line (refer to the CreateOrUpdateTaxCodes API where the external ID is used to create/ update tax codes)   Optional string
UnitsExternalId

The unit identifier in the payer's ERP

   Optional string

Response parameters

element

description

data type
CreateOrUpdatePurchaseOrdersResult Contains the response parameters CreateOrUpdatePurchaseOrderResult (extension of type TipaltiResponse)

CreateOrUpdatePurchaseOrderResult

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
PurchaseOrderErrors
  • List of purchase order line results
  • Each line result is of type TipaltiPurchaseOrderItemResult
   Array of TipaltiPurchase
OrderItemResult
TipaltiPurchaseOrderItemResult

element

description

data type
ErrorMessage A description of the error string
Succeeded Indicates if the purchase order line was created or updated successfully boolean
PurchaseOrderNumber An identifier for the purchase order string