Function: CreateOrUpdateGrns

The CreateOrUpdateGrns function creates or updates GRN A goods received note (GRN) is an internal document that acts as proof of goods received to match against invoices and purchase orders. GRN, receipt, and receiving report are synonymous.. 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 /v5/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>

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<grns>

<TipaltiGrnItem>

<ReceiptNumber>string</ReceiptNumber>

<Status>string</Status>

<ReceiptDate>dateTime<ReceiptDate>

<PayerEntity>string</PayerEntity>

<Supplier>string</Supplier>

<ShipmentDate>dateTime</ShipmentDate>

<Notes>string</Notes>

<ReceiptBy>string</ReceiptBy>

<PurchaseOrderNumber>string</PurchaseOrderNumber>

<GrnLines>

<GoodsReceivedNotificationLine>

<InvoiceNumber>string</InvoiceNumber>

<ItemCode>string</ItemCode>

<ItemDescription>string</ItemDescription>

<ItemUnits>string</ItemUnits>

<QuantityShipped>decimal</QuantityShipped>

<LineNotes>string</LineNotes>

<PoLineId>string</PoLineId>

<ItemUnitsExternalId>string</ItemUnitsExternalId>

</GoodsReceivedNotificationLine>

<GoodsReceivedNotificationLine>

<InvoiceNumber>string</InvoiceNumber>

<ItemCode>string</ItemCode>

<ItemDescription>string</ItemDescription>

<ItemUnits>string</ItemUnits>

<QuantityShipped>decimal</QuantityShipped>

<LineNotes>string</LineNotes>

<PoLineId>string</PoLineId>

<ItemUnitsExternalId>string</ItemUnitsExternalId>

</GoodsReceivedNotificationLine>

</GrnLines>

</TipaltiGrnItem>

</grns>

</CreateOrUpdateGrns>

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

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

<CreateOrUpdateGrnsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<GrnErrors>

<TipaltiGrnItemResult>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<ReceiptNumber>string</ReceiptNumber>

</TipaltiGrnItemResult>

<TipaltiGrnItemResult>

<ErrorMessage>string</ErrorMessage>

<Succeeded>boolean</Succeeded>

<ReceiptNumber>string</ReceiptNumber>

</TipaltiGrnItemResult>

</GrnErrors>

</CreateOrUpdateGrnsResult>

</CreateOrUpdateGrnsResponse>

</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
grns
  • List of GRNs
  • Each GRN is of type TipaltiGrnItem.
  Mandatory Array of TipaltiGrnItem

TipaltiGrnItem

element

description

limitation

Mandatory?

data type
ReceiptNumber Receipt identifier   Mandatory string
Status Status of the GRN
  • Valid values:
    • Active (default)
    • Closed
    • Deleted
    • Partially billed
  • Values are not case sensitive.
 Optional string
ReceiptDate Date and time the receipt 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
Supplier Unique payee identifier (the payee ID) (Idap)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
 Optional string
ShipmentDate Date and time the goods were shipped YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section Optional dateTime
Notes Notes about the GRN (provided by the receipt creator)   Optional string
ReceiptBy Name of the person who created the receipt   Optional string
PurchaseOrderNumber An identifier for the purchase order   Mandatory string
GrnLines
  • List of GRN lines
  • Each GRN line is of type GoodsReceived
    NotificationLine.
     Array of GoodsReceived
NotificationLine
GoodsReceivedNotificationLine

element

description

limitation

Mandatory?

data type
InvoiceNumber The number of the invoice Max. length = 256 Optional string
ItemCode Code of the line item received   Optional string
ItemDescription Description of the line item received   Optional string
ItemUnits Units of measurement for the line item received (e.g., kilograms, pounds, etc.)   Optional string
QuantityShipped Quantity of the line item received Max. of four decimal places Mandatory decimal
LineNotes Notes about the line item (provided by the receipt creator)   Optional string
PoLineId
  • An identifier for the purchase order line
  • Must be unique within a single purchase order
   Mandatory, if "verification of PO line IDs" has been enabled with Tipalti; otherwise, optional string
ItemUnitsExternalId The item's unit identifier in the payer's ERP   Optional string

Response parameters

element

description

data type
CreateOrUpdateGrnsResult Contains the response parameters CreateOrUpdateGrnResult (extension of type TipaltiResponse)

CreateOrUpdateGrnResult

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
GrnErrors
  • List of GRN line results
  • Each line result is of type TipaltiGrnItemResult
   Array of TipaltiGrnItemResult
TipaltiGrnItemResult

element

description

data type
ErrorMessage A description of the error string
Succeeded Indicates if the GRN line was created or updated successfully boolean
ReceiptNumber Receipt identifier string