PeopleVox

Warehouse Management System API Guide


Peoplevox WMS API Guide v1.10b (for PVX v5.8.3.x and above)



Table of Contents

  1. Peoplevox Integration

    1.1 Introduction

    1.2 Quick-Start Guide

  2. Warehouse Management System API

    2.1 API Calls

    2.2 API Data Types

  3. Integration Templates

  4. Change log

1. Peoplevox Integration

1.1 Introduction

The Peoplevox Warehouse Management System (WMS) provides an API to allow clients and partners to write integrations into the WMS. This document will describe the features offered by the API, how an integrator is expected to talk to the API, and what the expected results & responses are.

Broadly speaking, the API is used by integrators to push data to the WMS, and the WMS would typically send data back to another system via a webhook process.

The API also provides the ability for integrators to search for data within the system and run reports, the results of which are returned on the API response.

1

The primary goal of the API is to allow the exchange of data between PVX and third-party systems; in a very basic textbook integration example, a third- party system would send order data from an ecommerce platform to the WMS, the orders would be picked, packed, and despatched, and the WMS would notify the third-party system of the despatch and any resulting changes in inventory.

1.2 Quick-Start Guide

Scoping out an integration into a new system can be challenging, so we have compiled some quick-start guides for some of the most common scenarios that we encounter day-to-day.

These are just guidelines, and are not comprehensive outlines for every integration.

1.2.1 Writing an integration between Peoplevox and an ecommerce platform

Ecommerce platforms are one of the most common systems integrated into Peoplevox. A typical ecommerce integration would support the following features:

  1. Sync product data from the ecommerce system to Peoplevox
  2. Sync sales order and customer data from the ecommerce system to Peoplevox
  3. Sync inventory changes from Peoplevox to the ecommerce system
  4. Sync order fulfilments and tracking data from Peoplevox to the ecommerce platform

Some ecommerce platforms also integrate with the Peoplevox returns process, but the scope of this integration tends to vary. Generally, an ecommerce integration will only care about the quantity of each product available for sale; it typically does not need to know about each individual transaction that led to that figure. Similarly, most ecommerce systems are not designed to support purchasing, so a typical integration would not sync this data.

Feature Detail Purpose
SaveData API call Item types template Used to push product data into Peoplevox
SaveData API call Customers template Used to push customer data into Peoplevox
SaveData API call Sales orders template Used to push sales order header data into Peoplevox
SaveData API call Sales order items template Used to push sales order item line data into Peoplevox
AvailabilityChanges event subscription   Used to notify the ecommerce platform of changes in availability for each item in the warehouse
DespatchPackageDespatched event subscription   Used to notify the ecommerce platform of the goods that have been shipped from the warehouse
DespatchPackageTrackingNumberReceived event subscription   Used to notify the ecommerce platform when a tracking number is received from the carrier for a given package

A common variation on this pattern is often to include the use of the Returns event subscription (to notify the ecommerce platform when goods are returned against sales orders). Some platforms may use this to help automate the process for raising credit notes to customers.

1.2.2 Writing an integration between Peoplevox and an ERP system

ERP integrations are typically more complex than ecommerce platform integrations, as an ERP often manages a larger proportion of data within the business. A typical ERP integration would support the following features:

  1. Sync product data from the ERP to Peoplevox
  2. Sync sales order and customer data from the ERP to Peoplevox
  3. Sync purchase order and supplier data from the ERP to Peoplevox
  4. Sync ad-hoc inventory transactions (e.g. stock take, removal due to shrinkage, etc.) from Peoplevox to the ERP
  5. Sync sales order fulfilments and tracking data from Peoplevox to the ERP
  6. Sync purchase order receipts from Peoplevox to the ERP

One of the key differences between an ERP and an ecommerce integration is the level of detail that those systems typically require when it comes to inventory updates. Generally an ecommerce integration will want to obtain the total available figure for sale, whereas an ERP will instead care about the individual changes in inventory, and the reasons for those changes.

Similarly, a typical ERP integration will synchronise both sales orders and purchase orders (as well as the fulfilment of each), which means that the ERP often already knows about the majority of inventory changes. ERP integrations will often synchronise returns data from Peoplevox as well. This is why an ERP integration would typically synchronise only the unplanned inventory changes, i.e. those that the ERP was not already expecting to occur.

The following tools may be useful to an integrator building a basic ERP integration:

Feature Detail Purpose
SaveData API call Item types template Used to push product data into Peoplevox
SaveData API call Customers template Used to push customer data into Peoplevox
SaveData API call Sales orders template Used to push sales order header data into Peoplevox
SaveData API call Sales order items template Used to push sales order item line data into Peoplevox
SaveData API call Suppliers template Used to push supplier data into Peoplevox
SaveData API call Purchase orders template Used to push purchase order header data into Peoplevox
SaveData API call Purchase order items template Used to push purchase order item line data into Peoplevox
IncrementalChanges event subscription Note - this event provides the changes rather than the absolute figures, and can be filtered to exclude changes of a particular type Used to notify the ERP of the changes in availability for each item in the warehouse
DespatchPackageDespatched event subscription   Used to notify the ERP of the goods that have been shipped from the warehouse against an order
DespatchPackageTrackingNumberReceived event subscription   Used to notify the ERP when a tracking number is received from the carrier for a given package
GoodsReceived event subscription Includes items receipt data whether or not they are received against a PO Used to notify the ERP of goods that are received into the warehouse
Returns event subscription   Used to notify the ERP of goods that are returned by customers to the warehouse against a sales order

The variations between ERP integrations tend to emphasize the differing workflows between businesses. This generally manifests as a change in the trigger for synchronisation (for example, many ERPs have approval mechanisms that prevent purchase orders being submitted to the warehouse until they have been authorised).

1.2.3 Writing an integration between Peoplevox and an IPaaS system / integration platform

Integrations into dedicated integration platforms are often hard to define, since the scope of required functionality depends on either the other connectors available on the platform, or the specific purpose of the integration. Often, a connector into an integration platform is a scalable means to achieving one of the two scenarios described above, so those are good places to start.

The added complexity of an integration platform is that the connector with Peoplevox may need to be capable of supporting both types of integration (and potentially others). The decision point for integration partners here is around how the platform needs to obtain inventory updates from Peoplevox.

Some platforms may choose to support both the AvailabilityChanges and the IncrementalChanges, and subscribe to the most appropriate one for each Client. Others may subscribe to IncrementalChanges in every case, and use that to construct a totaled inventory figure if required.

1.2.4 Writing an integration between Peoplevox and a carrier system

These integrations are a little different to ERP and ecommerce platform integrations. Integrations with carriers rely upon real-time communication to obtain labels and other documentation, so Peoplevox provides a different set of tools for these.

We’re working on a new set of cloud-based tools for writing integrations between Peoplevox and carrier systems. These tools are currently undergoing beta testing - check back here soon for updates.

2. Warehouse Management System API

The API is a SOAP service, and the description (WSDL) file can be found at the following address:

http://{your-WMS-Web-Address}/resources/integrationservicev4.asmx?wsdl

The definitions can also be viewed in a web browser at the following address:

http://{your-WMS-Web-Address}/integrationservicev4.asmx

The {your-WMS-Web-Address} placeholder refers to the URL provided by Peoplevox to access the Peoplevox web application. For a typical production environment, the URL is “wms.peoplevox.net/ClientId”, where the ClientId refers to the unique identifier assigned by Peoplevox to the client. Testing environments may use different URL formats.

An example URL for a production environment of a client “MyClientId” would be:

http://wms.peoplevox.net/myclientid/integrationservicev4.asmx

The API uses the SOAP protocol for framing the request and response, but when sending and requesting data to and from the system, that data is sent in CSV format, wrapped by the SOAP envelope. See the relevant sections below for examples of this.

PLEASE NOTE: We may make changes to the API from time to time when we release new features. If we’re releasing a backwards-compatible change then we’ll update the existing API version. Your integration should be prepared to handle these changes without warning. Backwards-compatible changes include:

If we need to release a potentially breaking change, such as a change to an existing API response type, we’ll publish this against a new version of the API to ensure that your integrations aren’t affected until you’re ready.

2.1 API Calls

Calls to the API take the form of an HTTP POST request followed by the relevant HTTP Headers (content type and content length), and the SOAP envelope in the body of the message.

The API supports requests for both SOAP 1.1 and SOAP 1.2.

An example of a call to the Authenticate API method using SOAP 1.1 is described below.

Authenticate

Parameters:

Return value:

IntegrationResponse:

Placeholders string and int need to be replaced by actual values:


POST /clientid/Resources/IntegrationServicev4.asmx HTTP/1.1          
Host: string                                                         
Content-Type: text/xml; charset=utf-8                                
SOAPAction: "http://www.peoplevox.net/Authenticate"                  

<?xml version="1.0" encoding="utf-8"?>                              
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   
	<soap:Body>                                                     
		<Authenticate xmlns="http://www.peoplevox.net/">            
			<clientId>string</clientId>                             
			<username>string</username>                             
			<password>string</password>                             
		</Authenticate>                                             
	</soap:Body>                                                    
</soap:Envelope>   

The WMS will send back a response as follows:


HTTP/1.1 200 OK                                                        
Content-Type: text/xml; charset=utf-8                                  

<?xml version="1.0" encoding="utf-8"?>                                 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   
	<soap:Body>                                                        
		<AuthenticateResponse xmlns="http://www.peoplevox.net/">       
			<AuthenticateResult>                                       
				<ResponseId>int</ResponseId>                           
				<TotalCount>int</TotalCount>                           
				<Detail>string</Detail>                                
			</AuthenticateResult>                                      
		</AuthenticateResponse>                                        
	</soap:Body>                                                       
</soap:Envelope>                                                       

The Authenticate call is used to start a session with the WMS. If a valid clientid, username, and password combination are provided, then the WMS will return a session id on the response. The response to the Authenticate request includes a Detail field, which contains the client id, followed by a comma, followed by the session id. This session id must be provided on subsequent calls to the API.

The username and password are created in the PVX web application under Users tab of the Setup module. API sessions remain valid for up to 30 minutes after the most recent activity. After 30 minutes of inactivity, the caller will need to re-authenticate to obtain a new session id.

When populating the UserSessionCredentials object, callers must also provide a value for the “UserId” parameter – this is mandatory, but it does not currently influence the result of the call. It is recommended that callers pass a value of 0 in all cases for this parameter.

Each API response includes a ResponseId parameter, which indicates the success or failure of the call.

The IntegrationResponse object contains the following parameters:

C# Example


var service = newIntegrationServiceV4();

// Authenticate to WMS
// The password needs to be in base 64
var response = service.Authenticate("ClientId", "username", 
	Convert.ToBase64String(ASCIIEncoding.ASCII.GetBytes("password")));
var authentication = response.Detail.Split(',');

// Store the client id and the session id in the SOAP Header
service.UserSessionCredentialsValue = newUserSessionCredentials();
service.UserSessionCredentialsValue.ClientId = authentication[0];
service.UserSessionCredentialsValue.SessionId = authentication[1];

2.1.1 Exporting Data

2.1.1.1 GetData

The GetData method is used to export data from the Warehouse Management System (WMS). The page number and number of items per page parameters are used to repeat the same method to return pages of information. If you wish to receive all data in one call set ItemsPerPage value to 0.

Parameters:

GetRequest object

Return value:

IntegrationResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/Resources/IntegrationServicev4.asmx HTTP/1.1
Host: string  
Content-Type: text/xml; charset=utf-8 
SOAPAction: "http://www.peoplevox.net/GetData"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<clientId>string</clientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<GetData xmlns="http://www.peoplevox.net/"> 
			<getRequest>
				<TemplateName>string</TemplateName>
				<PageNo>int</PageNo>
				<ItemsPerPage>int</ItemsPerPage>
				<SearchClause>string</SearchClause>
			</getRequest>
		</GetData>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


     HTTP/1.1 200 OK
     Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<GetDataResponse xmlns="http://www.peoplevox.net/">
			<GetDataResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</GetDataResult>
		</GetDataResponse>
	</soap:Body>
</soap:Envelope>

C# Example


var response = service.GetData(new GetRequest
{
    ItemsPerPage = 0,
    PageNo = 1,
    SearchClause = "Barcode.StartsWith("1")",
    TemplateName = "Item types"
});

2.1.1.2 GetReportData

The GetReportData method can be used to export data from the Warehouse Management System (WMS) using a system report template. The page number and number of items per page parameters are used to repeat the same method to return pages of information. The benefits are that you can export information over many database tables whereas the GetData method will only export information in one table.

If you wish to receive all data in one call set ItemsPerPage value to 0.

Parameters:

Return value:

IntegrationResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1 Host: peoplevox.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/GetReportData"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<ClientId>string</ClientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<GetReportData xmlns="http://www.peoplevox.net/">
			<getReportRequest>
				<TemplateName>string</TemplateName>
				<SearchClause>string</SearchClause>
				<ItemsPerPage>int</ItemsPerPage>
				<FilterClause>string</FilterClause>
				<OrderBy>string</OrderBy>
				<Columns>string</Columns>
			</getReportRequest>
		</GetReportData>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<GetReportDataResponse xmlns="http://www.peoplevox.net/">
			<GetReportDataResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
				<Statuses>
					<IntegrationStatusResponse>
						<Reference>string</Reference>
						<Status>Error or Success</Status>
					</IntegrationStatusResponse>
					<IntegrationStatusResponse>
						<Reference>string</Reference>
						<Status>Error or Success</Status>
					</IntegrationStatusResponse>
				</Statuses>
			</GetReportDataResult>
		</GetReportDataResponse>
	</soap:Body>
</soap:Envelope>

C# Example


var response = service.GetReportData(new GetReportRequest
{
    TemplateName = "Item movement history",
    PageNo = 1,
    ItemsPerPage = 0,
    OrderBy = "[Date timestamp]",
    Columns = "[Item code],[Date timestamp],[From],[To],[Quantity],[Comments]",
    SearchClause = "([Date timestamp] > DateTime(" +
    searchStockTime.ToString("yyyy,MM,dd,HH,mm,ss") + "))"
};);

// Where searchStockTime is a Datetime variable storing the last Datetime that you
// accessed the Item movement history report 
// Please note the use of square brackets to define the field as a report column name

2.1.2 Importing Data

The following section provides information on the two methods used together to import data into the WMS:

API Call Description
GetSaveTemplate This API method allows a caller to request the integration template associated with a particular data type, which defines the available columns and their mapped names
SaveData This API method allows a caller to push CSV data into the WMS

2.1.2.1 GetSaveTemplate

The GetSaveTemplate method will return the CSV template to be used with the SaveData function.

Parameters

Please refer to the Templates section to see what Template names can be used.

Return value

IntegrationResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/Resources/IntegrationServicev4.asmx HTTP/1.1
Host: string
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/GetSaveTemplate"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<clientId>string</clientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<GetSaveTemplate xmlns="http://www.peoplevox.net/">
			<templateName>string</templateName>
		</GetSaveTemplate>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<GetSaveTemplateResponse xmlns="http://www.peoplevox.net/">
			<GetSaveTemplateResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</GetSaveTemplateResult>
		</GetSaveTemplateResponse>
	</soap:Body>
</soap:Envelope>

C# Example


var result = service.GetSaveTemplate("Item types");

2.1.2.2 SaveData

The SaveData method is used to import data into the Warehouse Management System.

Parameters

Return value

IntegrationResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/Resources/IntegrationServicev4.asmx HTTP/1.1
Host: string
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/SaveData"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<clientId>string</clientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<SaveData xmlns="http://www.peoplevox.net/">
			<saveRequest>
				<TemplateName>string</TemplateName>
				<CsvData>string</CsvData>
				<Action>int</Action>
			</saveRequest>
		</SaveData>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<SaveDataResponse xmlns="http://www.peoplevox.net/">
			<SaveDataResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</SaveDataResult>
		</SaveDataResponse>
	</soap:Body>
</soap:Envelope>

C# Example


// Get carriers template
var csvHeader = service.GetSaveTemplate("Carriers");
var result = service.SaveData(newSaveRequest()

{
    TemplateName = "Carriers",
    /*
    “Name”, “Reference”
    “DHL”, “D0001”
    “FedEx”, “F0002”
    */
    CsvData = csvHeader.Detail + "\nDHL,D0001\nFedEx, F0002",
    Action = 0
});

2.1.3 Subscription Methods

The subscription methods on the API allow third-party systems to subscribe to receive notifications from the WMS as events occur in the warehouse. These events are raised as webhooks from the WMS to an endpoint of the subscriber’s choice.

There are seven different events to which a third-party can subscribe:

At a high level, the subscriber chooses the event to which they wish to subscribe, the URL to which they wish PVX to send the data when the event occurs, and the data that they want to be included on that message.

The events are pushed from PVX to subscribers on a regular basis (typically, once every three minutes).

For example, a subscriber may want to be notified whenever the inventory for a product changes in the warehouse. They would set up a public-facing endpoint on their system to act as a listener, then subscribe to the relevant event from the warehouse, and specify their endpoint as the callback URL.

It is important for subscribers to understand that some events purposefully overlap. There are multiple events related to inventory changes, and other activities (such as goods receipt) have their own dedicated events, although those activities may also result in a change in inventory. Not all integrations are expected to use every event.

The subscription methods and the available events are described in more detail below.

AvailabilityChanges Event

Certain activities can change the availability of items in the warehouse. See the figure below.

When the availability of an item changes, the AvailabilityChanges event is raised. The AvailabilityChanges event will notify subscribers of the current inventory for the item. It does not include details of the transaction that caused the inventory change.

This event is useful for subscribers that simply need an up to date inventory feed from the warehouse, but do not need to reconcile every change, or maintain an audit trail of positive and negative adjustments in the third-party system.

It is not possible for subscribers to obtain information on the cause for an availability change via this event. This is because the event may automatically combine multiple inventory changes into a single updated inventory figure.

Subscribers can request the fields listed here to be included on the event callback. To use these in a filter, the caller must prefix them with “ItemType.” (for example, {ItemCode} for a parameter on a callback, {ItemType.ItemCode} for a filter).

SalesOrderStatusChanges Event

The SalesOrderStatusChanges event is raised whenever the status of an order in PVX changes. The diagram below describes the lifecycle of an order. In general, the status is controlled and automatically set by the WMS, for example the process of allocating inventory to the order will automatically set it to the “Allocated” status. The exception is the “Cancelled” status, which can be set from an external system.

This event is useful for subscribers that wish to track the progress of an order through the pick, pack, & despatch process. A common use case is to automate the creation of an email to the customer as soon as their order is picked. This event is capable of notifying subscribers that an order has been despatched or partially despatched, but subscribers will find other events more suitable if they wish to know exactly which items from the order were included in the despatch.

The subscriber can request the fields here to be included on the callback. To use these in a filter, the caller must prefix them with “SalesOrder.” (for example, {SalesOrderNumber} for a parameter on a callback, {SalesOrder.SalesOrderNumber} for a filter).

GoodsReceived Event

The GoodsReceived event is raised when items are received and reconciled into the warehouse.

This event is specifically triggered by the receive activity; it is not raised for items that are manually registered to a location, or adjusted via a stocktake process.

There are several receipt processes in PVX, some of which involve receiving goods against a particular purchase order, others simply allow the user to receive against a reference.

The event itself is rooted in the goods in record, which is a record of the receipt activity. The goods in can be considered a collection of items that are physically received together, but within that there may be more than one logical grouping (for example, if goods are received for two purchase orders in the same activity). The logical groupings are referred to as consignments.

Each consignment belongs to exactly one goods in, but a single goods in may contain multiple consignments. When a goods in is reconciled, the event is raised, and subscribers should examine the contents of each consignment to ensure that they identify all received items.

This is particularly important if the warehouse permits over-receipt against purchase orders. When this occurs, the goods in will contain one consignment for the items that were received as expected (which is linked to a purchase order), and one consignment for the additional goods that were received but not expected (this consignment has no purchase order reference).

The following fields are available on the callback:

* - Items that are marked by the asterisk return Comma Separated Values (CSV)

TrackingNumberReceived Event

The TrackingNumberReceived event is raised when PVX receives a tracking number from a third party system. The tracking number itself is typically provided by a carrier integration.

In a typical workflow, a sales order is despatched from PVX, and this is the trigger for the carrier integration to obtain details of that despatch from PVX.

The carrier software processes this despatch information, and pushes a tracking number back into PVX.

Some despatch workflows within PVX also permit the user to manually assign the tracking number during the despatch process. The sales orders integration template also provides the ability for a user to manually import a tracking number against a despatch.

Regardless of the process used, the event is triggered whenever the tracking number is assigned to the despatch. Other processes may assign a tracking number to an individual package. For those scenarios, the DespatchPackageTrackingNumberReceived event is more suitable, but subscribers should be aware that assigning a tracking number to a package will also assign that tracking number to the despatch. The result is that the despatch holds the most recently received package tracking number, and this event is raised for those scenarios as well.

Subscribers should also be aware that this event is only raised if and when a tracking number is actually received by PVX. It therefore may not be a reliable process for subscribers to identify goods being despatched, as any delays or issues with the carrier will impact this process. The DespatchPackageDespatched event is more suitable for subscribers that wish to be notified when goods are despatched.

This event is rooted in the despatch object.

The following fields are available on the event:

* - Items that are marked by the asterisk return Comma Separated Values (CSV)

The relationships between the sales order, despatch, package, and package tracking numbers are displayed on the figure below.

IncrementalChanges Event

The IncrementalChanges event is raised when the available quantity of a product has been changed. This event describes changes in availability, which does not always correspond with a change in the on hand inventory. For example, this event is raised when the availability changes as a result of order allocation, but not when the order is despatched.

Unlike the AvailabilityChanges event (which notifies subscribers of the new available figure), this event notifies subscribers of the individual changes that lead to that new availability. This is particularly useful for subscribers that wish to maintain a history of the changes in availability, or where the subscriber manages their own allocation and therefore wishes to ignore those availability changes from PVX.

Typically, subscribers would request the item code (to identify the product) and the quantity changed as a minimum. Subscribers are also able to include details of the transaction that caused the availability change, and the user responsible for that transaction.

The following fields are available on the event:

There are two fields on this event that subscribers can use if they wish to identify the cause for a particular change.

The “AvailabilityEventType.Description” will contain one of the following values, which can be used to broadly classify the change:

The “Reason” field contains a short description of the activity that triggered the change in availability. This will contain one of the following text values (the ItemCode, SalesOrderNumber, and Removal Barcode placeholders would contain the relevant data for the activity):

Returns Event

The Returns event is raised when a return is performed in PVX. The event is rooted in the return object, and is intended as a means for subscribers to receive a notification of goods being returned by customers.

Note that PVX does not maintain any pre-advice record for returns, and as with all of the subscription events, it is a one-way notification only. Integrators who wish to connect PVX to a system that supports returns authorisation (or similar) functionality should assume that PVX will permit the return and raise the event, even if no matching RMA exists. The reconciliation of that return against a matching RMA or similar should occur in connected system.

Subscribers can use this event to obtain information on the item that has been returned, the quantity returned, and the location into which the item was placed during the returns process.

The event can also be configured to provide detail on the condition of the returned goods. This can be useful for subscribers that need to record the return in another system, but do not want to assume that all returns can be immediately re-sold.

The following fields are available on the event:

* - Items that are marked by the asterisk return Comma Separated Values (CSV)

DespatchPackageTrackingNumberReceived Event

The DespatchPackageTrackingNumberReceived event is raised when a tracking number is received against an individual package. There may be more than one package for a given despatch.

Not all carrier integrations will provide a tracking number against a specific package. MetaPack does, but carrier integrations that utilise OpenDespatch will provide their tracking data at the despatch level.

When a tracking number is received against a package, PVX will also stamp the same tracking number against the despatch record. The reverse is not true; assigning a tracking number to the despatch record will not affect any of the package tracking numbers.

Whereas the TrackingNumberReceived event is rooted in the despatch record, the DespatchPackageTrackingNumberReceived event is rooted in the despatch package record. Note that it is possible to include data from the despatch record on this event as well (including the tracking number from the despatch). The “TrackingNumber” field should be used to reference the tracking number of the package, and the “Despatch.TrackingNumber” field if the subscriber wishes to reference the despatch.

The following fields are available on the event:

* - Items that are marked by the asterisk return Comma Separated Values (CSV)

DespatchPackageDespatched Event

The DespatchPackageDespatched event is raised when a new package is despatched against an order. It can be raised before PVX has received a tracking number from a carrier integration, so it may not contain the tracking number at this stage. The tracking numbers are available on this event for completeness, but subscribers should use the DespatchPackageTrackingNumberReceived or TrackingNumberReceived events to receive tracking number information.

The purpose of this event is to allow subscribers to receive a notification when an order is fulfilled. The event is rooted in the despatch package record, and subscribers can use this to identify the quantity of each product that was packed in the package.

PVX supports partial fulfillment of orders; this event will expose the products and quantities that have actually been despatched within the specific package that triggered the event. If a single order is despatched across multiple packages, then one event will be raised for each, and the subscriber is expected to examine the contents of each to build a complete picture of the total collection of despatched goods.

Subscribers should use the DespatchItems collection to identify the items in the package. The SalesOrderItems collection is a reference to the items ordered on the sales order.

The following fields are available on the event:

* - Items that are marked by the asterisk return Comma Separated Values (CSV)

Callback URL

The callback URL specifies the location to which PVX will send the events when they are raised by the warehouse. Typically this URL would be an endpoint hosted by the subscriber, and the subscriber would write some logic to listen for calls made to that endpoint.

The callback URL can contain a combination of fixed text and dynamic parameter placeholders. When PVX raises the event, it will replace the placeholders with the relevant data.

The placeholders are indicated using {curly brackets} - see the relevant sections above for full lists of available parameters for each event type.

URL examples:

AvailabilityChange

http://my-website.com/sku={ItemCode}&newQty={Available}

SalesOrderStatusChanges

http://my-website.com/so={SalesOrderNumber}&status={SalesOrderStatu.Name}

GoodsReceived

http://my-website.com/sku={Consignments.ConsignmentItemTypes.ItemType.ItemCode}&qty={Consignments.ConsignmentItemTypes.Quantity}

TrackingNumberReceived

http://my-website.com/so={Picks.SalesOrder.SalesOrderNumber}&trackingNum={TrackingNumber}

IncrementalChanges

http://my-website.com/sku={ItemType.ItemCode}&qtyChanged={QuantityChanged}&reason={Reason}

Returns

http://my-website.com/sku={ReturnItems.ItemType.ItemCode}&qtyReturned={ReturnItems.QuantityReturned}&isResellable={ReturnItems.ReturnsCondition.IsReusable}

DespatchPackageTrackingNumberReceived

http://my-website.com/so={Despatch.Picks.SalesOrder.SalesOrderNumber}&package={PackageNumber}&trackingNum={TrackingNumber}

DespatchPackageDespatched

http://my-website.com/so={Despatch.Picks.SalesOrder.SalesOrderNumber}&package={PackageNumber}&items={DespatchItems.ItemType.ItemCode}&qty={DespatchItems.Quantity}

If you are using SubscribePostEvent method, parameters are provided in the same format, but PVX will include these in the body of the POST message. For example, sku={ItemCode}&newQty={Available}

Retry Policy

PVX expects the subscriber to respond with a confirmation when the event is raised. Subscribers must respond with an HTTP200 OK code in order to confirm receipt of the data.

Note that this is a confirmation of receipt, not successful processing on the part of the subscriber. To ensure a robust integration, subscribers should consider separating the responsibility of capturing the event from the business logic that acts upon the data.

If the subscriber fails to respond when PVX raises the event, PVX will retry the event several times over the course of 61 minutes:

If the subscriber has not confirmed receipt after 61 minutes, PVX will stop sending that event. Note that this will not deactivate the subscription, so further events will still be raised, each of which will be retried for 61 mins as above.

2.1.3.1 SubscribeEvent

The SubscribeEvent method allows callers to subscribe to receive event data from PVX. Subscribers should use this method if they want the event payload to be raised on an HTTP GET request. Subscribers should be careful to ensure that the maximum length of URL (after placeholder replacement) does not exceed 2047 characters. If the total length of the URL is likely to exceed this limit, then subscribers should request that PVX notifies them via HTTP POST instead - SubscribePostEvent.

Subscribers may wish to secure their callback URL, to ensure that it only accepts data from authorised sources. For example, a subscriber may design their receiving code to process only payloads that contain a valid authorisation key. The subscriber could then ensure that this key was included in the callback URL. For example:

http://my-website.com/key=MyAuthKey&sku={ItemCode}&newQty={Available}

The caller may optionally provide a filter on the subscription if they do not wish to receive all events of a given type. For example, a subscriber may only wish to receive sales order status changes if the status is relevant to them, for example Picked or Despatched. The filter can be used to ignore the other statuses.

The API will respond with a confirmation that the subscription has been created succesfully. The response will also contain the ID of the subscription. The caller must store this ID, as they will need to provide it on subsequent calls to unsubscribe from the event in the future.

Parameters

SubscribeEvent object

Return value

SubscribeEventResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Host: peoplevox.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/SubscribeEvent"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<ClientId>string</ClientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<SubscribeEvent xmlns="http://www.peoplevox.net/">
			<eventType>AvailabilityChanges or SalesOrderStatusChanges or GoodsReceived 
			or TrackingNumberReceived or IncrementalChanges or Returns 
			or DespatchPackageTrackingNumberReceived 
			or DespatchPackageDespatched</eventType>
			<filter>string</filter>
			<callbackUrl>string</callbackUrl>
			<encodeParameterData>boolean</encodeParameterData>
		</SubscribeEvent>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<SubscribeEventResponse xmlns="http://www.peoplevox.net/">
			<SubscribeEventResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</SubscribeEventResult>
		</SubscribeEventResponse>
	</soap:Body>
</soap:Envelope>

Sample Request

The following is an example request and response for a subscriber that wishes to be notified about AvailabilityChanges related to a single item, with code “YourItemCode”.


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.peoplevox.net/SubscribeEvent"
Host: peoplevox.net

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:peop="http://www.peoplevox.net/">
   <soap:Header>
      <peop:UserSessionCredentials>
         <peop:UserId>1</peop:UserId>
         <peop:ClientId>clientid</peop:ClientId>
         <peop:SessionId>sessionid</peop:SessionId>
      </peop:UserSessionCredentials>
   </soap:Header>
   <soap:Body>
      <peop:SubscribeEvent>
         <peop:eventType>AvailabilityChanges</peop:eventType>
         <peop:filter>ItemType.ItemCode="YourItemCode"</peop:filter>
         <peop:callbackUrl>http://my-website.com/item={ItemCode}&amp;available={Available}</peop:callbackUrl>
		 <peop:encodeParameterData>false</peop:encodeParameterData>
      </peop:SubscribeEvent>
   </soap:Body>
</soap:Envelope>

Sample Response


HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <SubscribeEventResponse xmlns="http://www.peoplevox.net/">
         <SubscribeEventResult>
            <ResponseId>0</ResponseId>
            <TotalCount>0</TotalCount>
            <Detail>1</Detail>
            <Statuses />
            <ImportingQueueId>0</ImportingQueueId>
            <SalesOrdersToDespatchIds />
         </SubscribeEventResult>
      </SubscribeEventResponse>
   </soap:Body>
</soap:Envelope>

2.1.3.2 SubscribePostEvent

As with the SubscribeEvent method, the SubscribePostEvent method allows callers to subscribe to receive event data from PVX. Subscribers should use this method if they want the event payload to be raised on an HTTP POST request. The caller may specify the parameters that they wish to receive when the event is raised. These parameters will be provided in the body of the POST.

Parameters

SubscribePostEvent object

Return value

SubscribeEventResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/SubscribePostEvent"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<ClientId>string</ClientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<SubscribePostEvent xmlns="http://www.peoplevox.net/">
			<eventType>AvailabilityChanges or SalesOrderStatusChanges or GoodsReceived 
			or TrackingNumberReceived or IncrementalChanges or Returns 
			or DespatchPackageTrackingNumberReceived 
			or DespatchPackageDespatched</eventType>
			<filter>string</filter>
			<postUrl>string</postUrl>
			<postParams>string</postParams>
			<encodeParameterData>boolean</encodeParameterData>
		</SubscribePostEvent>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<SubscribePostEventResponse xmlns="http://www.peoplevox.net/">
			<SubscribePostEventResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</SubscribePostEventResult>
		</SubscribePostEventResponse>
	</soap:Body>
</soap:Envelope>

Sample Request

The following is an example request and response for a subscriber that wishes to be notified (via HTTP POST) about AvailabilityChanges related to a single item, with code “YourItemCode”.


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.peoplevox.net/SubscribePostEvent"
Host: peoplevox.net

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:peop="http://www.peoplevox.net/">
   <soap:Header>
      <peop:UserSessionCredentials>
         <peop:UserId>1</peop:UserId>
         <peop:ClientId>clientid</peop:ClientId>
         <peop:SessionId>sessionid</peop:SessionId>
      </peop:UserSessionCredentials>
   </soap:Header>
   <soap:Body>
      <peop:SubscribePostEvent>
         <peop:eventType>AvailabilityChanges</peop:eventType>
         <peop:filter>ItemType.ItemCode="YourItemCode"</peop:filter>
         <peop:postUrl>http://my-website.com/ProcessAvailabilityChanges</peop:postUrl>
         <peop:postParams>item={ItemCode}&amp;available={Available}</peop:postParams>
		 <peop:encodeParameterData>false</peop:encodeParameterData>
      </peop:SubscribePostEvent>
   </soap:Body>
</soap:Envelope>

Sample Response


HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <SubscribePostEventResponse xmlns="http://www.peoplevox.net/">
         <SubscribePostEventResult>
            <ResponseId>0</ResponseId>
            <TotalCount>0</TotalCount>
            <Detail>2</Detail>
            <Statuses />
            <ImportingQueueId>0</ImportingQueueId>
            <SalesOrdersToDespatchIds />
         </SubscribePostEventResult>
      </SubscribePostEventResponse>
   </soap:Body>
</soap:Envelope>

2.1.3.3 SubscribeEventWithSitesFilters

The SubscribeEventWithSitesFilters is designed to serve a specific scenario, in which a subscriber wishes to receive a single inventory figure from PVX when the inventory for the item changes, but they want that figure to be the total aggregrated available figure for the item across multiple warehouses.

For example, a scenario in which PVX is managing 3 warehouses, and two of those contribute to the inventory figure on a particular web store. This method can be used to allow that webstore to subscribe to changes in inventory for those 2 warehouses, and ignore changes & availability in the third.

This method creates a subscription that will be raised on an HTTP GET request. There is currently no equivalent for an HTTP POST message.

Parameters

SubscribeEventWithSitesFilters object

Return value

SubscribeEventWithSitesFiltersResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Host: peoplevox.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/SubscribeEventWithSitesFilters"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<ClientId>string</ClientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<SubscribeEventWithSitesFilters xmlns="http://www.peoplevox.net/">
			<eventType>AvailabilityChanges or SalesOrderStatusChanges or GoodsReceived 
			or TrackingNumberReceived or IncrementalChanges or Returns 
			or DespatchPackageTrackingNumberReceived 
			or DespatchPackageDespatched</eventType>
			<filter>string</filter>
			<sitesFilter>string</filter>
			<callbackUrl>string</callbackUrl>
			<encodeParameterData>boolean</encodeParameterData>
		</SubscribeEventWithSitesFilters>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<SubscribeEventWithSitesFiltersResponse xmlns="http://www.peoplevox.net/">
			<SubscribeEventWithSitesFiltersResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</SubscribeEventWithSitesFiltersResult>
		</SubscribeEventWithSitesFiltersResponse>
	</soap:Body>
</soap:Envelope>

Sample Request

The following is an example request and response for a subscriber that wishes to be notified about AvailabilityChanges related to a single item in two sites, with code “YourItemCode”.


POST https://qac.peoplevox.net/PVXQAC0804/Resources/IntegrationServiceV4.asmx HTTP/1.1
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.peoplevox.net/SubscribeEventWithSitesFilters"
Host: peoplevox.net

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:peop="http://www.peoplevox.net/">
   <soap:Header>
      <peop:UserSessionCredentials>
         <peop:UserId>1</peop:UserId>
         <peop:ClientId>clientid</peop:ClientId>
         <peop:SessionId>sessionid</peop:SessionId>
      </peop:UserSessionCredentials>
   </soap:Header>
   <soap:Body>
      <peop:SubscribeEventWithSitesFilters>
         <peop:eventType>AvailabilityChanges</peop:eventType>
         <peop:filter>ItemType.ItemCode="MyItemCode"</peop:filter>
         <peop:sitesFilter>Site.Reference="SiteA" OR Site.Reference="SiteB"</peop:sitesFilter>
         <peop:callbackUrl>http://my-website.com/item={ItemCode}&amp;available={Available}</peop:callbackUrl>
		 <peop:encodeParameterData>false</peop:encodeParameterData>
      </peop:SubscribeEventWithSitesFilters>
   </soap:Body>
</soap:Envelope>

Sample Response


HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <SubscribeEventWithSitesFiltersResponse xmlns="http://www.peoplevox.net/">
         <SubscribeEventWithSitesFiltersResult>
            <ResponseId>0</ResponseId>
            <TotalCount>0</TotalCount>
            <Detail>3</Detail>
            <Statuses />
            <ImportingQueueId>0</ImportingQueueId>
            <SalesOrdersToDespatchIds />
         </SubscribeEventWithSitesFiltersResult>
      </SubscribeEventWithSitesFiltersResponse>
   </soap:Body>
</soap:Envelope>

2.1.3.4 Event subscription data types

This section contains a reference for some common data types that appear on multiple subscriptions. For example, you can access sales order data from the Sales Order Status Change subscription, as well as the DespatchPackageDespatched event.

These are the common fields that are accessible across all events that expose the object, but individual event types may expose more context-specific data.

2.1.3.4.1 Sales order / SalesOrder
2.1.3.4.2 Item type / ItemType
2.1.3.4.3 Despatch
2.1.3.4.4 Despatch package / DespatchPackage

2.1.3.5 UnsubscribeEvent

The UnsubscribeEvent method allows subscribers to unsubscribe from existing subscriptions. To do so, a subscriber will need the ID of the subscription, which they will have received during the initial subscribe call.

The UnsubscribeEvent can be used to unsubscribe from both GET and POST subscriptions. The method only permits a single subscription to be unsubscribed per-call. To unsubscribe from multiple subscriptions, callers should call this method multiple times, once for each subscription from which they wish to unsubscribe.

Parameters

UnsubscribeEvent object

Return value

UnsubscribeEventResponse object.

Placeholders string and int need to be replaced by actual values:


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Host: peoplevox.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.peoplevox.net/UnsubscribeEvent"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Header>
		<UserSessionCredentials xmlns="http://www.peoplevox.net/">
			<UserId>int</UserId>
			<ClientId>string</ClientId>
			<SessionId>string</SessionId>
		</UserSessionCredentials>
	</soap:Header>
	<soap:Body>
		<UnsubscribeEvent xmlns="http://www.peoplevox.net/">
			<subscriptionId>int</subscriptionId>
		</UnsubscribeEvent>
	</soap:Body>
</soap:Envelope>

The WMS will send back a response as follows:


HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<UnsubscribeEventResponse xmlns="http://www.peoplevox.net/">
			<UnsubscribeEventResult>
				<ResponseId>int</ResponseId>
				<TotalCount>int</TotalCount>
				<Detail>string</Detail>
			</UnsubscribeEventResult>
		</UnsubscribeEventResponse>
	</soap:Body>
</soap:Envelope>

Sample Request


POST /clientid/resources/integrationservicev4.asmx HTTP/1.1
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.peoplevox.net/UnsubscribeEvent"
Host: peoplevox.net

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:peop="http://www.peoplevox.net/">
   <soap:Header>
      <peop:UserSessionCredentials>
         <peop:UserId>1</peop:UserId>
         <peop:ClientId>clientid</peop:ClientId>
         <peop:SessionId>sessionid</peop:SessionId>
      </peop:UserSessionCredentials>
   </soap:Header>
   <soap:Body>
      <peop:UnsubscribeEvent>
         <peop:subscriptionId>1</peop:subscriptionId>
      </peop:UnsubscribeEvent>
   </soap:Body>
</soap:Envelope>

Sample Response


HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <UnsubscribeEventResponse xmlns="http://www.peoplevox.net/">
         <UnsubscribeEventResult>
            <ResponseId>0</ResponseId>
            <TotalCount>0</TotalCount>
            <Detail>True</Detail>
            <Statuses />
            <ImportingQueueId>0</ImportingQueueId>
            <SalesOrdersToDespatchIds />
         </UnsubscribeEventResult>
      </UnsubscribeEventResponse>
   </soap:Body>
</soap:Envelope>

2.2 API Data Types

This chapter provides information on the data types used by the various API methods:

Type(s) Description
Common Types Description of common types used by multiple API methods
Search Values Description of search & filter behaviour used by multiple methods
IntegrationResponse The type from which all API responses inherit
GetRequest The GetRequest type used by the GetData method
GetReportRequest The GetReportRequest type used by the GetReportData method
SaveRequest The SaveRequest type used by the SaveData method
Templates The list of available templates, for reference on the TemplateName field of the SaveData method

2.2.1 Common Types

Boolean

Booleans can represent one of two values: true or false.

int

Integers represent whole numbers that can be either positive or negative (e.g. 23191, -39013). They do not hold numbers with a decimal or fraction.

decimal

Decimals provide an additional precision beyond that of an integer, to express decimal numbers. (e.g. 3.14, 3.00001).

string

Strings represent any collection of characters that cannot be expressed by the types above. It is possible for numerical value to be expressed as a string value. Examples include “Hello”, “SO1234”, or even “21”.

Date and time

Dates and times are expressed by a standard template of characters, in which the different parts of the template represent different parts of the date & time.

The API expects all dates and times to be sent in UTC format. Similarly, any dates and times returned by the API will be represented in UTC unless specified otherwise.

DateTime fields are represented by the following character sequence:

“YYYY-MM-DD<space>HH:MM”

where

2.2.2 Search Values

In scenarios where a caller is requesting data from PVX (either on an immediate API response, or via a subscription), that caller can apply a filter expression to limit the scope of the data returned. It is advisable to apply filters on the request rather than requesting large volumes of data and filtering on the response, as PVX will be able to use the filter to optimise the speed of the request.

Filters are defined as predicates to be evaluated for each member of a specified collection. For example, to filter a list of sales orders, the caller would provide a predicate that expresses the conditions that must be met in order for a sales order to be included in the response. The operators available on the predicate depend upon the data type of the field being examined.

String comparisons

String comparison is not case sensitive and requires the parameter to be enclosed in either double quote marks (for GetData filters) or single quote marks (for GetReportData filters). The list of available operators and examples below use double quotes; callers should replace these with single quotes for a GetReportData call:

Operator Description
.Equals(“”) Equals the enclosed string value, similar to SQL (={text})
.StartsWith(“”) Starts with the enclosed string value, similar to SQL (LIKE ‘{text}%’)
.EndsWith(“”) Ends with the enclosed string value, similar to SQL (LIKE ‘%{text}’)
.Contains(“”) Contains the enclosed string value, similar to SQL (LIKE ‘%{text}%’)
= or == “” Equals the enclosed string value, similar to SQL (={text})
!= “” Not equal to the enclosed string value, similar to SQL (!={text})

Examples

For example, to search for string values in a field called name:

Name.Contains(“abc”)

would return prabcfg, abcpr, tAbcy

!Name.Contains(“abc”)

would not return prabcfg, abcpr, tAbcy

Name.StartsWith(“abc”)

would return abcpr, abcrana, Abct

Name.EndsWith(“abc”)

would return prabc, ranaabc, urAbc

Name.EndsWith(“abc”)

would return only abc, Abc, ABC

Name = “abc”

would return only abc, Abc, ABC

Name == “abc”

would return only abc, Abc, ABC

Name = Description

would return items which have the same name and description.

Numeric comparisons

The following operators can be used to compare integer, decimals and date values. Integers can be compared to other integers and decimals. DateTimes can only be compared to other DateTimes:

Operator Description
> Greater than
< Less than
>= Greater than or equal
<= Less than or equal
== Equal
!= Not equal

Examples

For example to search for an item by reorder point in the GetData Method, a caller would pass filter values using the operators as follows:

ReorderPoint > 0

This returns all item types with a reorder point greater than zero.

ReorderPoint < 1000

This returns all item types with a reorder point less than 1000.

ReorderPoint >= 1000

This returns all item types with a reorder point greater than 1000.

ReorderPoint <= 100

This returns all item types with a reorder point less than or equal to 100.

ReorderPoint == 1234

This returns all item types with a reorder point equal to 1234

ReorderPoint != 1234

This returns all item types that do not have an reorder point equal to 1234

Date and time comparison

Numerical operators (<,>,<=,>=,==,!= ) are also applicable to DateTime fields. Callers may describe a DateTime value using the DateTime function:

DateTime(YYYY,MM,DD,HH,MM,SS)

Where YYYY = year, MM = month, DD =Day, HH = hour, MM = minute, SS = second

Example

RequestedDeliveryDate < DateTime(2011,10,26,12,00,00)

Search for records with RequestedDeliveryDate less than the 26th October 2011, 12:00am

Combination of Expressions

Callers may combine multiple expressions together using the Boolean operators OR and AND. Callers may use parentheses to explicitly group filter criteria.

Examples

ReorderPoint >= 1000 AND Name.EndsWith(“abc”)

This will return a list of records with a reorder point greater than or equal to 1000, where the name of the record also ends with the sequence “abc”.

Name.EndsWith(“abc”) AND (ReorderPoint > OnHand OR (ReorderPoint == 0 AND OnHand < 100))

This expression only returns items with names ending with “abc”. Of those, the filter will return only items for which the OnHand quantity is less than the reorder point, or both reorder point is 0 AND the OnHand less than 100.

2.2.3 IntegrationResponse

All API responses inherit from a common type, the IntegrationResponse. All responses will share this common schema, but the behaviour of each individual method will influence how the data is populated on that response.

Attribute Description Values expected
ResponseId Response code to indicate success or failure 0 - successful, -1 failed
Detail The requested data (if querying PVX), or a more detailed success indicator if instructing PVX to do something String
TotalCount The number of records afffected or returned by a call integer
Statuses A detailed list of statuses providing more granular success indicators for operations in which multiple records are updated at once A collection of IntegrationStatusResponses
ImportingQueueId Deprecated - no longer used NULL
SalesOrdersToDespatchIds Deprecated - no longer used NULL

2.2.4 GetRequest

The GetRequest type is used on the GetData API method to specify the data that the caller wishes to obtain.

Attribute Description Values expected
TemplateName Refer to Templates String
SearchClause A filter expression, refer to Search Values String
PageNo Page number (default is 1 and starting from 1) int
ItemsPerPage Number of items to retrieve per page (Max.1000, anything more than 1000 is reset to 1000) int

2.2.5 GetReportRequest

The GetReportRequest type is used on the GetReportData API method to specify the data that the caller wishes to obtain.

Attribute Description Values expected
TemplateName The name of the report that the caller wishes to run, as displayed in the reporting module of the web application String
PageNo Page number (default is 1 and starting from 1) int
ItemsPerPage Number of items to retrieve per page (Max.1000, anything more than 1000 is reset to 1000) int
OrderBy The fields by which to sort the data on the response. Use [square brackets] to reference the column as it is expressed in the web app reporting module. Callers may specify the sort direction by adding ‘desc’ or ‘asc’ after the column name and a space. String
Columns The list of columns on the report to return on the response. Use [square brackets] to reference the column as it is expressed in the web app reporting module. Leaving blank will result in all columns being returned. String
SearchClause A filter expression, refer to Search Values. Use [square brackets] to reference the column as it is expressed in the web app reporting module. String

2.2.6 SaveRequest

The SaveRequest type is used on the SaveData API method.

Attribute Description Values expected
TemplateName Refer to Templates String
CSVData A string value that represents the data to be saved, in CSV format. See below for an example String
Actions Action code int

Actions

Value Description
0 No Action
1 Do not allocate (only available for “Sales order items” template)
2 Delete (not available for “Sites” template)

Example SaveRequest The following example represents a SOAP request to the SaveData method, utilising the SaveRequest type to create a new item type. Note that this example assumes that the target PVX instance has an “Item types” template configured with the default mappings.


POST /clientid/Resources/IntegrationServicev4.asmx HTTP/1.1  
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.peoplevox.net/SaveData"
Host: peoplevox.net

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:peop="http://www.peoplevox.net/">
   <soap:Header>
      <peop:UserSessionCredentials>
         <peop:UserId>1</peop:UserId>
         <peop:ClientId>clientid</peop:ClientId>
         <peop:SessionId>sessionid</peop:SessionId>
      </peop:UserSessionCredentials>
   </soap:Header>
   <soap:Body>
      <peop:SaveData>
         <peop:saveRequest>
            <peop:TemplateName>Item types</peop:TemplateName>
            <peop:CsvData>ItemCode,Name,Barcode
MyExampleItemCode,An example item,MEI00001</peop:CsvData>
            <peop:Action>0</peop:Action>
         </peop:saveRequest>
      </peop:SaveData>
   </soap:Body>
</soap:Envelope>

For completeness, this is an example of the response to that call:


HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <SaveDataResponse xmlns="http://www.peoplevox.net/">
         <SaveDataResult>
            <ResponseId>0</ResponseId>
            <TotalCount>1</TotalCount>
            <Detail />
            <Statuses>
               <IntegrationStatusResponse>
                  <Reference>MyExampleItemCode</Reference>
                  <Status>Success</Status>
                  <LineNo>1</LineNo>
               </IntegrationStatusResponse>
            </Statuses>
            <ImportingQueueId>0</ImportingQueueId>
            <SalesOrdersToDespatchIds />
         </SaveDataResult>
      </SaveDataResponse>
   </soap:Body>
</soap:Envelope>

2.2.7 Templates

Data is imported to PVX against an integration template. The template defines the type of record being imported, as well as defining a mapping between the user’s column names and the standard PVX names for the fields on that record.

Examples of integration templates include carriers, sales orders, and items. Some records are represented by more than one template, for example the sales orders is defined by a header record and a collection of sales order item records. The header uses one template, and the item lines use another.

In those scenarios, the header record must be imported first, so that it can be referenced on the lines. In the sales order example, the header defines the SalesOrderNumber which uniquely identifies the order. The subsequent lines then reference that SalesOrderNumber.

Each template is further divided into an “Import” and an “Export” template. The import template is used to map incoming CSV files onto the standard PVX record, and the export template is used to define the format of the CSV file produced by PVX when exporting data on the GetData API method. In some cases the import & export templates may be identical, but in others, some data may only be available on an export (for example, inventory levels on the “Item types” template).

Note that the integration templates do not affect the PVX event subscription functionality in any way.

The templates must be configured before they can be referenced. This configuration process occurs in the PVX web app. To configure a template, the user defines their desired field mappings for that record type.

Carriers

• Unique identifier: Name

Import & export:

Reference Type Description
Name String(1000) The (unique) name of the carrier as it will appear within the app. Used as a handle on the carrier to assign services to it
Reference String(1000) External reference (optional)

Customers

• Unique identifier: Reference

Import & export:

Reference Type Description
Name String(1000) Name
Reference String(1000) A unique reference to the customer, used as a handle to update it after creation, and to link related records to it
FirstName String(1000) First name (optional)
LastName String(1000) Last name (optional)
Phone String(1000) Phone number (optional)
Mobile String(1000) Mobile number (optional)
Email String(1000) Email address (optional)
CreditLimit Decimal Credit limit (optional)
CreditStatus Boolean Credit status (optional, false by default)
Wholesaler Boolean Wholesaler flag (optional, false by default)

Customer addresses

• Unique identifier: AddressReference

Import:

• Requires: Customers

Reference Type Description
CustomerName String(1000) This refers to the customer external reference on the template above
AddressLine1 String(1000) Line 1 (optional)
AddressLine2 String(1000) Line 2 (optional)
AddressCity String(1000) City (optional)
AddressRegion String(1000) Region (optional)
AddressPostcode String(1000) Post code (optional)
AddressCountry String(1000) Country (optional)
AddressReference String(1000) Reference (optional)

Export:

Reference Type Description
CustomerName String(1000) Customer name
CustomerReference String(1000) Customer external reference
AddressLine1 String(1000) Line 1 (optional)
AddressLine2 String(1000) Line 2 (optional)
AddressCity String(1000) City (optional)
AddressRegion String(1000) Region (optional)
AddressPostcode String(1000) Post code (optional)
AddressCountry String(1000) Country (optional)
AddressReference String(1000) Reference (optional)

Item types

• Unique identifier: ItemCode

Import:

• References, but does not require: Item type groups

Reference Type Description
ItemCode String(1000) Item code, a unique identifier for the item
Name String(1000) The name that will be displayed to users, typically this is the name of the product as it would appear to customers (optional)
Barcode String(1000) Barcode
MinimumPickLocationQuantity Int The minimum desired quantity of the item across all pick locations in a warehouse. Used by the replenishment function to determine the point at which a replenishment action should be created.
DefaultReplenishmentQuantity Int The default quantity to be replenished (moved from bulk to pick) when the replenishment is triggered.
Attribute1 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute2 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute3 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute4 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute5 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute6 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute7 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute8 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute9 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute10 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute11 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute12 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute13 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute14 String(1000) A generic attribute that can be used to hold string data (optional)
Attribute15 String(1000) A generic attribute that can be used to hold string data (optional)
DefaultSuppliersPartNumber String(1000) Suppliers part number (optional)
Description String(1000) A longer description of the item, displayed where there is space for additional information beyond the name and item code (optional)
ItemGroup String(50) The name of the item group to which the item should belong. If a name is provided that does not exist, a new group will be created with the specified name (optional)
Weight Decimal Weight (optional)
TaxCode String(1000) The name of the tax code to assign to the item. This is a lookup on the list of defined tax codes, so the tax code will need to be defined before it can be referenced here (optional)
UnitOfMeasure String(10) Unit of measure (optional, EA by default) (see Unit of measures)
DefaultEconomicOrderQuantity Int The best value purchase quantity. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
DefaultLeadTime Int The delivery time (in calendar days). This is not used internally by the WMS, but can be displayed on reports if provided (optional)
HasSerialNumbers Boolean Indicates whether the item has serial numbers associated with it (optional, false by default)
UseManufacturersSerialNumber Boolean (optional, false by default)
ReorderPoint Int The inventory level at which the item needs reordering. This is not used internally by the WMS, but can be displayed on reports if provided(optional)
Traceability Boolean Traceability (optional, false by default)
ShelfLife Date Date in “yyyy-MM-dd HH:mm:ss” format (optional)
DefaultNumberItemsPerContainer Int The default quantity of this item that forms a container. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
DefaultContainerType String(50) Default container type name. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
DefaultNumberItemsPerOuterCase Int The default quantity of this item that forms an outer case. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
DefaultNumberItemsPerInnerCase Int The default quantity of this item that forms an inner case. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
BuyPrice Decimal The price at which the item is bought. Referenced by some reports in order to calculate cost prices where more detailed information is not available (optional)
WholesalePrice Decimal Wholesale price. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
RetailPrice Decimal Retail price. This is not used internally by the WMS, but can be displayed on reports if provided (optional)
WeightMeasure String(10) Weight measure symbol (optional) (see Unit of measures)
Height Decimal Height (optional)
Width Decimal Width (optional)
Depth Decimal Depth (optional)
DimensionMeasure String(10) Dimension measure symbol (optional) (see Unit of measures)
Tags String(8000) A generic string field that can be used for searching within the web application (optional)

Export:

Reference Type Description
ItemCode String(1000) Item code, a unique identifier for the item
Name String(1000) The name that will be displayed to users, typically this is the name of the product as it would appear to customers
Barcode String(1000) Barcode
MinimumPickLocationQuantity Int The minimum desired quantity of the item across all pick locations in a warehouse. Used by the replenishment function to determine the point at which a replenishment action should be created.
DefaultReplenishmentQuantity Int The default quantity to be replenished (moved from bulk to pick) when the replenishment is triggered.
Attribute1 String(1000) A generic attribute that can be used to hold string data
Attribute2 String(1000) A generic attribute that can be used to hold string data
Attribute3 String(1000) A generic attribute that can be used to hold string data
Attribute4 String(1000) A generic attribute that can be used to hold string data
Attribute5 String(1000) A generic attribute that can be used to hold string data
Attribute6 String(1000) A generic attribute that can be used to hold string data
Attribute7 String(1000) A generic attribute that can be used to hold string data
Attribute8 String(1000) A generic attribute that can be used to hold string data
Attribute9 String(1000) A generic attribute that can be used to hold string data
Attribute10 String(1000) A generic attribute that can be used to hold string data
Attribute11 String(1000) A generic attribute that can be used to hold string data
Attribute12 String(1000) A generic attribute that can be used to hold string data
Attribute13 String(1000) A generic attribute that can be used to hold string data
Attribute14 String(1000) A generic attribute that can be used to hold string data
Attribute15 String(1000) A generic attribute that can be used to hold string data
DefaultSuppliersPartNumber String(1000) Suppliers part number
Description String(1000) A longer description of the item, displayed where there is space for additional information beyond the name and item code
ItemGroup String(50) The name of the item group to which the item belongs
Weight Decimal Weight
TaxCode String(1000) The name of the tax code to which the item is assigned
UnitOfMeasure String(10) Unit of measure (EA by default) (see Unit of measures)
DefaultEconomicOrderQuantity Int The best value purchase quantity
DefaultLeadTime Int The delivery time (in calendar days)
HasSerialNumbers Boolean Indicates whether the item has serial numbers associated with it (false by default)
UseManufacturersSerialNumber Boolean (false by default)
ReorderPoint Int The inventory level at which the item needs reordering
Traceability Boolean Traceability (false by default)
ShelfLife Date Date in “yyyy-MM-dd HH:mm:ss” format
DefaultNumberItemsPerContainer Int The default quantity of this item that forms a container
DefaultContainerType String(50) Default container type name
DefaultNumberItemsPerOuterCase Int The default quantity of this item that forms an outer case
DefaultNumberItemsPerInnerCase Int The default quantity of this item that forms an inner case
BuyPrice Decimal The price at which the item is bought. Referenced by some reports in order to calculate cost prices where more detailed information is not available
WholesalePrice Decimal Wholesale price
RetailPrice Decimal Retail price
WeightMeasure String(10) Weight measure symbol (see Unit of measures)
Height Decimal Height
Width Decimal Width
Depth Decimal Depth
DimensionMeasure String(10) Dimension measure symbol (see Unit of measures)
Tags String(8000) A generic string field that can be used for searching within the web application
On hand Int On hand stock level (read only)
Allocated Int Allocated stock (read only)
Available Int Available stock level (read only)
POQuantityOutstanding Int The quantity of the item currently outstanding on purchase orders (read only)

Item type groups

• Unique identifier: Name

Import & export:

Reference Type Description
Name String(1000) Item type group name - this is used to link items and additional item type groups
ParentGroup String(1000) The name of the immediate parent item group. Leave blank on import to assign to the highest level group (optional)

Item type kittings

• Unique identifier: The combination of ParentItemCode and ChildItemCode

Each item type kitting defines a relationship between exactly two items. Multiple kitting records work together to define the collection of components that make up a kit parent. The quantity represents the number of times a particular component appears in a given kit.

One item can have multiple children, and one item can belong to multiple kits, but the parent/child combination is unique. Submitting a second kitting with the same parent and child but a different quantity will update the quanity of the existing record.

Import & export:

• Requires: Item types.

Reference Type Description
ParentItemCode String(1000) The item code of the item to be the parent of the kit
ChildItemCode String(1000) The item code of the item to be the child of the kit
Quantity Int The quantity of the child item that belongs to the parent item in the kit

Item type suppliers

• Unique identifier: The combination of ItemCode and Supplier

Import & export:

• Requires: Item types, Suppliers.

Reference Type Description
ItemCode String(1000) Item code
Supplier String(1000) Supplier reference
DefaultEconomicOrderQuantity Int The best value purchase quantity of the item from this supplier. Not used internally by the WMS (optional)
DefaultLeadTime Int The delivery time (in calendar days) of this item from this supplier. Not used internally by the WMS (optional)
DefaultSuppliersPartNumber String(1000) The supplier’s unique identifier or barcode for the item. Must be unique amongst all barcodes if provided, but can be scanned to identify the item (optional)
IsPrimary Boolean Defines whether this is the primary supplier for the item (optional)

Locations

• Unique identifier: Barcode

Import: • Requires: Location groups.

Reference Type Description
Barcode String(1000) The barcode of the location - this must be unique across all barcode fields, and will be used to scan the location in the warehouse
Name String(1000) A name for the location, to help users identify it
Sequence Int The numerical sequence of the location within its local group. This is combined with the sequence of each parent to generate a unique sequence within the warehouse
LocationGroup String(1000) Name of the location group under which to create this location
LocationUseType String(1000) The use type of the location (Bulk, Despatch, Pick, Quarantine). This will influence the activities that can be performed upon the inventory in the location, and may affect whether the inventory contributes towards the available inventory of the warehouse

Export:

Reference Type Description
Barcode String(1000) The barcode of the location - unique across all barcode fields
Name String(1000) The name for the location, to help users identify it
Sequence Int The numerical sequence of the location within its local group. This is combined with the sequence of each parent to generate a unique sequence within the warehouse
LocationGroup String(1000) Name of the location group that is the immediate parent of the location
LocationUseType String(1000) The use type of the location (Bulk, Despatch, Pick, Quarantine). This influences the activities that can be performed upon the inventory in the location, and may affect whether the inventory contributes towards the available inventory of the warehouse
IPSequence String(1000) The combined sequence, derived from the location group hierarchy plus the sequence on the location (read only)

Location groups

• Unique identifier: Name

• Requires: Location group types.

Reference Type Description
Name String(1000) Name
BarcodePrefix String(1000) The barcode prefix of the location group. Used to help users automatically generate new locations with unique barcodes using the web application
ParentLocationGroup String(1000) The name of the location group to be the immediate parent of this one. Leave blank to assign to the highest level of the location group hierarchy (optional)
LocationGroupType String(1000) The name of the type of this location group (e.g. bay, shelf, racking). This is a lookup to the location group types table, so the location group type must be created before it can be referenced here. Some default values are pre-defined by the system
Sequence Int The numerical sequence of the location group within the warehouse. It is combined with the sequence of other location groups in the hierarchy to generate the IP sequence for locations (optional)
Site String(1000) The reference of the site to which the location group belongs.

Location group types

• Unique identifier: Name

Reference Type Description
Name String(1000) Name

Package types

• Unique identifier: Name

Import & export:

Reference Type Description
Name String(1000) Name
Weight Decimal Weight (optional)
Height Decimal Height (optional)
Width Decimal Width (optional)
Depth Decimal Depth (optional)
ImageUrl String(1000) The URL of an image that represents this type of package. This will be displayed during the web app despatch process to help the user identify the package type (optional)

Payment methods

• Unique identifier: PaymentType

Import & export:

Reference Type Description
PaymentType String(1000) The name of the payment type

Purchase orders

Import:

• Unique identifier: PurchaseOrderNumber

• Requires: Suppliers

• Optional: Supplier addresses

Note - if you provide a supplier on the PO creation request, then the PO will be automatically submitted, and available to receive. If you do not, then a user will need to manually submit the PO via the web app before it can be received.

Reference Type Description
PurchaseOrderNumber String(1000) Purchase order number. This is the unique identifier for the purchase order
Status String(1000) Purchase order status name. For imports, only cancelled is accepted - all other statuses are read-only (optional) (see Purchase order statuses)
Reference String(1000) A string reference that can be applied to the order to help users identify and search for it. (optional)
Supplier String(1000) The reference of the supplier record to be linked to the purchase order (optional)
AddressLine1 String(1000) Line 1 (optional)
AddressLine2 String(1000) Line 2 (optional)
AddressCity String(1000) City (optional)
AddressRegion String(1000) Region (optional)
AddressPostcode String(1000) Post code (optional)
AddressCountry String(1000) Country (optional)
AddressReference String(1000) Address reference (optional - if a reference is provided alongside address data, the reference will be prioritised and the provided address data will be ignored)
RequestedDeliveryDate Date Requested date in “yyyy-MM-dd HH:mm:ss” format (optional)
SubmittedDate Date Submitted date in “yyyy-MM-dd HH:mm:ss” format (optional)
EndDate Date End date in “yyyy-MM-dd HH:mm:ss” format (optional)
ExpectedDeliveryDate Date Expected delivery date in “yyyy-MM-dd HH:mm:ss” format (optional)
Site String(1000) The reference of the site to which the purchase order will be assigned

Export:

Reference Type Description
PurchaseOrderNumber String(1000) Purchase order number. This is the unique identifier for the purchase order
Status String(1000) Purchase order status name (see Purchase order statuses)
Reference String(1000) A string reference that can be applied to the order to help users identify and search for it.
Supplier String(1000) The name of the supplier record linked to the purchase order
AddressLine1 String(1000) Line 1
AddressLine2 String(1000) Line 2
AddressCity String(1000) City
AddressRegion String(1000) Region
AddressPostcode String(1000) Post code
AddressCountry String(1000) Country
AddressReference String(1000) Address reference
RequestedDeliveryDate Date Requested date in “yyyy-MM-dd HH:mm:ss” format
SubmittedDate Date Submitted date in “yyyy-MM-dd HH:mm:ss” format
EndDate Date End date in “yyyy-MM-dd HH:mm:ss” format
ExpectedDeliveryDate Date Expected delivery date in “yyyy-MM-dd HH:mm:ss” format
Site String(1000) The reference of the site to which the purchase order is assigned
User String(20) The name of the user that created the purchase order

Purchase order items

• Unique identifier: Combination of PurchaseOrderNumber, ItemCode, and Line

• Requires: Purchase orders, Item types

Import & export:

Reference Type Description
PurchaseOrderNumber String(1000) The purchase order number of the purchase order to which the items should be attached
ItemCode String(1000) The item code of the items to be received
Status String(1000) Purchase order item type status name (optional) (see Purchase order items statuses)
Quantity Int The quantity of the item to be received
Line String(1000) A unique identifier for the item line. No two lines on a purchase order can share both an item code and a line number. Providing different line numbers allows the same item to appear more than once on a purchase order (optional)
Sequence Int Sequence (optional)
CostPrice Decimal The price at which the goods were purchased (optional)
ExpectededDeliveryDate Date Expected delivery date in “yyyy-MM-dd HH:mm:ss” format (optional)

Removals

• Unique identifier: Barcode

Reference Type Description
Name String(1000) The name of the removal reason
Description String(1000) The description of the removal reason (optional)
Barcode String(1000) The barcode of the removal reason
Site String(1000) The reference of the site to which the removal reason belongs

Return reasons

• Unique identifier: Code

Reference Type Description
Code String(1000) The code of the return reason - typically a short two or three letter code for quick identification
Description String(1000) A longer description of the return reason (optional)

Roles

• Unique identifier: Name

Reference Type Description
Name String(1000) The name of the role

Sales orders

• Unique identifier: SalesOrderNumber

• Optional: Customers, Customer addresses, Service types, Payment methods

Import:

Reference Type Description
SalesOrderNumber String(1000) The unique order number of the sales order
Customer String(1000) The Reference of the customer to link to the order (optional)
CustomerPurchaseOrderReferenceNumber String(1000) A free-text reference field to help identify and search for the order (optional)
ShippingAddressLine1 String(1000) Line 1 (optional)
ShippingAddressLine2 String(1000) Line 2 (optional)
ShippingAddressCity String(1000) City (optional)
ShippingAddressRegion String(1000) Region (optional)
ShippingAddressPostcode String(1000) Post code (optional)
ShippingAddressCountry String(1000) Country (optional)
ShippingAddressReference String(1000) Reference (optional - if a reference is provided alongside address data, the reference will be prioritised and the provided address data will be ignored)
InvoiceAddressLine 1 String(1000) Line 1 (optional)
InvoiceAddressLine 2 String(1000) Line 2 (optional)
InvoiceAddressCity String(1000) City (optional)
InvoiceAddressRegion String(1000) Region (optional)
InvoiceAddressPostcode String(1000) Post code (optional)
InvoiceAddressCountry String(1000) Country (optional)
InvoiceAddressReference String(1000) Reference (optional - if a reference is provided alongside address data, the reference will be prioritised and the provided address data will be ignored)
IsPartialShipment Boolean A flag that controls whether the order can be released for picking while partially allocated. If true, then the order can be released as soon as any item becomes available. If false, then the entire order must be allocated before it can be released (optional, false by default)
Status String(1000) The name of the status. Only the “cancelled” status is permitted on imports; all other statuses are read-only (optional) (see Sales order statuses)
RequestedDeliveryDate Date Requested date in “yyyy-MM-dd HH:mm:ss” format
ShippingCost Decimal Shipping cost (optional)
Email String(1000) Email (optional)
ContactName String(1000) Contact name (optional)
TotalSale Decimal Total sale (optional)
Discount Decimal Discount (optional)
TaxPaid Decimal TaxPaid (optional)
CreatedDate Date Created date in “yyyy-MM-dd HH:mm:ss” format (optional)
PaymentMethod String(1000) The name of the payment method used on the order (optional)
ServiceType String(1000) The service type code to assign to the order. The service type must be created prior to referencing it on the order (optional)
ChannelName String(1000) The name of the sales channel, or order source (optional)
OnHold Boolean A flag that controls whether the order can be released for picking. Inventory will still be allocated, but the order will only be releasable for picking if this is set to “false” (optional, defaults to false)
Attribute1 String(1000) Generic sales order attribute (optional)
Attribute2 String(1000) Generic sales order attribute (optional)
Attribute3 String(1000) Generic sales order attribute (optional)
Attribute4 String(1000) Generic sales order attribute (optional)
Attribute5 String(1000) Generic sales order attribute (optional)
StopShip Boolean A flag that blocks the despatch of a sales order if set to true. You will still be able to allocate and pick the order, but operators will be unable to despatch it until this flag is set to false (NOTE: This is not currently supported on mobile despatch methods - this is still in the works)
Site String(1000) The reference of the site to which the order should be assigned
DespatchTrackingNumber String(1000) The tracking number to assign to the despatch linked to this order. This can only be supplied after the order has been despatched. Typically this is provided by carrier integrations (optional)

Export:

Reference Type Description
SalesOrderNumber String(1000) The unique order number of the sales order
Customer String(1000) The Account name of the customer linked to the order
CustomerPurchaseOrderReferenceNumber String(1000) A free-text reference field to help identify and search for the order
ShippingAddressLine1 String(1000) Line 1
ShippingAddressLine2 String(1000) Line 2
ShippingAddressCity String(1000) City
ShippingAddressRegion String(1000) Region
ShippingAddressPostcode String(1000) Post code
ShippingAddressCountry String(1000) Country
ShippingAddressReference String(1000) Reference
InvoiceAddressLine 1 String(1000) Line 1
InvoiceAddressLine 2 String(1000) Line 2
InvoiceAddressCity String(1000) City
InvoiceAddressRegion String(1000) Region
InvoiceAddressPostcode String(1000) Post code
InvoiceAddressCountry String(1000) Country
InvoiceAddressReference String(1000) Reference
IsPartialShipment Boolean A flag that controls whether the order can be released for picking while partially allocated. If true, then the order can be released as soon as any item becomes available. If false, then the entire order must be allocated before it can be released
Status String(1000) The name of the status. Only the “cancelled” status is permitted on imports; all other statuses are read-only (see Sales order statuses)
RequestedDeliveryDate Date Requested date in “yyyy-MM-dd HH:mm:ss” format
ShippingCost Decimal Shipping cost
Email String(1000) Email
ContactName String(1000) Contact name
TotalSale Decimal Total sale
Discount Decimal Discount
TaxPaid Decimal TaxPaid
CreatedDate Date Created date in “yyyy-MM-dd HH:mm:ss” format
PaymentMethod String(1000) The name of the payment method used on the order
ServiceType String(1000) The service type code to assign to the order. The service type must be created prior to referencing it on the order
ChannelName String(1000) The name of the sales channel, or order source
OnHold Boolean A flag that controls whether the order can be released for picking. Inventory will still be allocated, but the order will only be releasable for picking if this is set to “false”
Attribute1 String(1000) Generic sales order attribute
Attribute2 String(1000) Generic sales order attribute
Attribute3 String(1000) Generic sales order attribute
Attribute4 String(1000) Generic sales order attribute
Attribute5 String(1000) Generic sales order attribute
StopShip Boolean A flag that blocks the despatch of a sales order if set to true. You will still be able to allocate and pick the order, but operators will be unable to despatch it until this flag is set to false (NOTE: This is not currently supported on mobile despatch methods - this is still in the works)
Site String(1000) The reference of the site to which the order is assigned

Sales order items

• Unique identifier: Combination of SalesOrderNumber, ItemCode, and Line

• Requires: Sales orders, Item types

Import & export:

Reference Type Description
SalesOrderNumber String(1000) The order number of the sales order to which the item line should be linked
ItemCode String(1000) The item code of the item to link to the sales order
QuantityOrdered Int Quantity ordered
RequestedDeliveryDate Date Requested date in “yyyy-MM-dd HH:mm:ss” format (optional)
Line String(1000) A unique identifier for the item line. No two lines on a sales order can share both an item code and a line number. Providing different line numbers allows the same item to appear more than once on a sales order (optional)
Sequence Int Sequence (optional)
SalePrice Decimal Sale price (optional)
Attribute1 String(1000) Generic sales order item attribute (optional)
Attribute2 String(1000) Generic sales order item attribute (optional)
Attribute3 String(1000) Generic sales order item attribute (optional)

Service types

• Unique identifier: Code

• Requires: Carriers

Import & export:

Reference Type Description
Carrier String(1000) Carrier name
Name String(1000) Service type name (optional)
Code String(1000) The code used to refer to the service type

Sites

• Unique identifier: Reference

Import & export:

Reference Type Description
Name String(1000) Name
Reference String(1000) Unique site reference, used to refer to the site

Suppliers

• Unique identifier: Reference

Import & export:

Reference Type Description
Name String(1000) Supplier name
Reference String(1000) Unique supplier reference
FirstName String(1000) First name (optional)
LastName String(1000) Last name (optional)
Phone String(1000) Phone number (optional)
Mobile String(1000) Mobile number (optional)
Email String(1000) Email (optional)
CreditLimit Decimal CreditLimit (optional)
Notes String(1000) Free-text field for storing notes against the supplier (optional)

Supplier addresses

• Unique identifier: AddressReference

• Requires: Suppliers

Import:

Reference Type Description
SupplierReference String(1000) The unique reference of the supplier to which the address should be linked
AddressLine1 String(1000) Line 1 (optional)
AddressLine2 String(1000) Line 2 (optional)
AddressCity String(1000) City (optional)
AddressRegion String(1000) Region (optional)
AddressPostcode String(1000) Post code (optional)
AddressCountry String(1000) Country (optional)
AddressReference String(1000) Reference (optional)

Export:

Reference Type Description
SupplierReference String(1000) The reference of the supplier to which the address is linked
AddressLine1 String(1000) Line 1
AddressLine2 String(1000) Line 2
AddressCity String(1000) City
AddressRegion String(1000) Region
AddressPostcode String(1000) Post code
AddressCountry String(1000) Country
AddressReference String(1000) Reference
SupplierName String(1000) The name of the linked supplier

Tax codes

• Unique identifier: TaxCodeName

Import & export:

Reference Type Description
TaxCodeName String(1000) Tax code name
TaxCodePercentage Decimal Tax code percentage (optional)

Users

• Unique identifier: Username

Import:

Reference Type Description
Username String(1000) User name
Password String(1000) Password text (edit only)
Role String(1000) The name of the role to which the user should be linked
DisplayName String(1000) Display name (optional)
Email String(1000) Email (optional)

Export:

Reference Type Description
Username String(1000) User name
Role String(1000) The name of the role to which the user should be linked
DisplayName String(1000) Display name (optional)
Email String(1000) Email (optional)

In addition to the templates, there are a number of symbols and status values used for some of the fields:

Unit of measures

Value Description
EA Unit
l Litre
dl Decilitre
cl Centilitre
ml Millilitre
m3 Cubic metre
ga Gallon
pt Pint
fl Fluid Ounce
g Gram
kg Kilogram
mg Milligram
lb Pound
oz Ounce

Purchase order statuses

Value
Not yet submitted
Submitted (read only)
Receiving (read only)
Complete (read only)
Cancelled
Deleted

Purchase order item statuses

Value
Pending
Complete (read only)
Closed

Sales order statuses Note - if you are attempting to set the status to cancelled via an order import, you will need to use the “Value”, not the ID.

ID Value  
0 New  
2 Allocated (read only)  
3 Being picked (read only)  
4 Picked (read only)  
5 Despatched (read only)
6 Cancelled  
7 Partially allocated (read only)  
8 Partially picked (read only)  
9 Partially despatched (read only)  

3. Integration Templates

The integration templates described above are configured via the PVX web application.

  1. Sign in to the PVX web application with your Administrator username and password
  2. Select the Integration module from the drop-down list of options in the User panel in the top right hand of the web application.

Selecting Integration module

The system displays the Integration Templates tab:

Integration Tab - Integration Templates

  1. Each template defines the full list of columns that can be imported or exported for a given record type. Configuring the template tells the system what column headers to expect for each field on an import, and what column headers to use for each field when exporting data.
  2. Select the radio button in the Select column, and click on the Configure button to define the list of column mappings:

  1. The integration template displays the PVX field name in the "Field to map" column, and prompts for the user's column name in the "Field name" field.
  1. Select the Save button to save the changes to the template, or click the cross in the top right corner of the prompt to cancel without saving the changes.

4. Change log

1.10a -> 1.10b

* Clarified on sales order imports that attempts to set the status to cancelled require the caller
to provide the status string "Cancelled"), not the ID
* Clarified on sales order imports that the "Customer" field refers to the unique "Reference" field
of the customer, not the customer Name. Exports still provide the Name of the customer
* Clarified behaviour of PO imports around suppliers

1.10 -> 1.10a

* Clarified on sales and purchase order imports that if both address data and an address reference 
are provided, then the reference is given priority and the other address data is ignored

1.9a -> 1.10

* Added a quick-start guide to help system integrators with choosing the right API tools for some
common integration scenarios
* Added the StopShip property to the sales order
* Added some information around our policy on releasing backwards-compatible API changes

1.9 -> 1.9a

* Added description of the encodeParameterData property for subscribing to events from Peoplevox. 
NOTE: This property was introduced as a non-breaking addition to the API. Existing integrations
can continue to use the subscription methods without providing this property, but new subscribers
are encouraged to explicitly provide this.

1.8a -> 1.9

* Updated IncrementalChanges event with a description of the AvailabilityEventType and Reason fields
* Updated IncrementalChanges event filter and payload fields to include the Site
* Added new section to describe the common data types shared across multiple subscriptions (for 
example, the item type)

1.8 -> 1.8a

* Added document change log

1.7 -> 1.8

* Updated available fields on integration templates
* Updated field lengths & added more meaningful descriptions on integration templates
* Specified the unique identifiers for each integration template type
* Split integration template definitions to clearly indicate the differences between imports and 
exports
* Reworded walk-through for template configuration
* Updated some status values to correctly state that they are read-only
* Fixed several broken hyperlinks
* Corrected some errors and omissions on the SOAP examples for GetData and GetReportData
* Reworded description of Authenticate method
* Various formatting improvements