Peoplevox
Submit an Idea

Event Subscriptions

Introduction

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 eight different events to which a third-party can subscribe (the IDs for these event types are used internally but you may see them in a few places):

  • 1 - AvailabilityChanges

  • 2 - SalesOrderStatusChanges

  • 3 - GoodsReceived

  • 4 - TrackingNumberReceived

  • 5 - IncrementalChanges

  • 6 - Returns

  • 7 - DespatchPackageTrackingNumberReceived

  • 9 - DespatchPackageDespatched

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.

Tip: When subscribing to an event, we recommend that you use filters to narrow down the scope of the data that you want to receive. If you know that you only want to receive data from a specific moment, include this in your filter. For example, if you’re setting up an inventory subscription on 01/01/2019 and you only want to receive new inventory changes, then make sure your subscription filter ignores any inventory updates prior to 01/01/2019. To do that, you would provide a filter like this:

UpdateTimestamp > DateTime(2019,01,01,00,00,00)

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 following fields to be included on the callback.

Note: To use them in the callback parameters, just reference the property name. To use these in a filter, 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:

  • GoodsInId

  • Reference

  • DeliveryDateTime

  • ReconciledDateTime

  • DeliveryNote

  • Site.Reference

  • Consignments.PurchaseOrder.Reference *

  • Consignments.PurchaseOrder.RequestedDeliveryDate *

  • Consignments.PurchaseOrder.PurchaseOrderNumber *

  • Consignments.PurchaseOrder.SubmittedDateTimeStamp *

  • Consignments.PurchaseOrder.EndDateTimeStamp *

  • Consignments.PurchaseOrder.ExpectedDeliveryDate *

  • Consignments.PurchaseOrder.Supplier.Name *

  • Consignments.PurchaseOrder.Supplier.Reference *

  • Consignments.PurchaseOrder.PurchaseOrderStatus.Name *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.Quantity *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.Line *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.Sequence *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.CostPrice *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.RequestedDeliveryDate *

  • Consignments.PurchaseOrder.PurchaseOrderItemTypes.ExpectedDeliveryDate *

  • Consignments.ConsignmentItemTypes.Quantity *

  • Consignments.ConsignmentItemTypes.CreateInventoryItemDateTime *

  • Consignments.ConsignmentItemTypes.ReconciledDateTime *

  • Consignments.ConsignmentItemTypes.ExpiryDateTime *

  • Consignments.ConsignmentItemTypes.QuantityReceivedToQuarantine *

  • Consignments.ConsignmentItemTypes.ItemType.Fields *

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

Tip: If your integration needs to support multiple POs on a single receipt, then you will want to list out the PO for which each item was received. Using "Consignments.PurchaseOrder.PurchaseOrderNumber" will give you a list of the distinct PO numbers on the receipt, but it will not correlate them with the items. To get the PO number per item, you should instead use "Consignments.ConsignmentItemTypes.Consignment.PurchaseOrder.PurchaseOrderNumber".


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:

  • All Despatch fields listed here

  • DespatchPackage.Fields *

  • Picks.NumberOfContainers *

  • Picks.NumberOfSpaces *

  • Picks.StartTimestamp *

  • Picks.EndTimestamp *

  • SalesOrder.Fields

  • SalesOrder.SalesOrderItems.SalesOrderItemPickings.ItemType.Fields *

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

  • One sales order can have multiple despatches (though typically it does not; the first despatch for a sales order creates a despatch, and subsequent despatches against the same order append additional packages to that. The exception is when performing a despatch by load, during which a new despatch is always created for each order)

  • One despatch can have multiple packages

  • Each package can have between zero and one tracking numbers

  • The despatch itself can also have between zero and one tracking numbers


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:

  • QuantityChanged

  • UpdatedBy

  • UpdateTimestamp

  • Reason

  • AvailabilityEventType.Description

  • ItemType.Fields

  • Site.Reference

  • ReferenceNumber

Note: The ReferenceNumber field is available from version 9.4.0 onwards, and contains the SalesOrderNumber that corresponds with any allocation, deallocation, or order cancellation activities.

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:

  • Unknown

  • Receive

  • Register

  • Sales order allocation

  • Sales order deallocation

  • Sales order cancellation

  • Removal / Quarantine

  • Stock take

  • Adjustment

  • Despatched

  • Returns

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

  • Despatched

  • Stock quantity updated

  • Sales order Allocation

  • Sales order Deallocation

  • Sales order deleted - {SalesOrderNumber}

  • Deleting {ItemCode} from {SalesOrderNumber}

  • Moved in to {Removal Barcode}

  • Moved out of {Removal Barcode}

  • Location quarantined

  • Location unquarantined

  • Sales order Cancellation

  • Site changed

  • Container removed to {Removal Barcode}

  • Container moved back in to stock

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:

  • ReturnId

  • DateTimestamp

  • ReturnCode

  • SalesOrder.Fields

  • ReturnItems.ItemType.Fields *

  • ReturnItems.SoldPrice *

  • ReturnItems.QuantityDespatched *

  • ReturnItems.QuantityReturned *

  • ReturnItems.Comments *

  • ReturnItems.HolderId *

  • ReturnItems.Holder.Site.Name *

  • ReturnItems.Holder.Site.Reference *

  • ReturnItems.ReturnReason.Code *

  • ReturnItems.ReturnReason.Description *

  • ReturnItems.ReturnsCondition.Code *

  • ReturnItems.ReturnsCondition.Description *

  • ReturnItems.ReturnsCondition.IsReusable *

  • User.Username

  • User.DisplayName

  • NumberOfDaysSinceDespatched

  • DespatchDetail.Carrier.Name

  • DespatchDetail.Carrier.Reference

  • DespatchDetail.ServiceType.Code

  • DespatchDetail.ServiceType.Name

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

Note: The following fields are now available with version 23.10-02 as part of the returns and RMA release.

  • ReturnAuthorization.ReturnAuthorizationNumber

  • ReturnAuthorization.ReturnTrackingNumber

  • ReturnAuthorization.ReturnExpectedDeliveryDate

  • ReturnAuthorization.ReturnSenderName

  • ReturnAuthorization.ReturnAuthorizationComments

  • ReturnAuthorization.ReturnAuthorizationStatu.Name

  • ReturnAuthorization.SalesOrder.Fields

  • ReturnAuthorization.Site.Name

  • ReturnAuthorization.Site.Reference

  • ReturnItems.ReturnAuthorizationItem.ReturnAuthorizationItemLineNumber *

  • ReturnItems.ReturnAuthorizationItem.ReturnAuthorizationItemComments *

  • ReturnItems.ReturnAuthorizationItem.ReturnAuthorizationItemStatu.Name*

  • ReturnItems.ReturnAuthorizationItem.ReturnReason.Code *

  • ReturnItems.ReturnAuthorizationItem.ReturnReason.Description *

  • ReturnItems.ReturnAuthorizationItem.ReturnsCondition.Code *

  • ReturnItems.ReturnAuthorizationItem.ReturnsCondition.Description *

  • ReturnItems.ReturnAuthorizationItem.ReturnsCondition.IsReusable *


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:

  • All DespatchPackage fields listed here

  • Despatch.Fields

  • Despatch.SalesOrder.Fields

  • Despatch.Picks.NumberOfContainers *

  • Despatch.Picks.NumberOfSpaces *

  • Despatch.Picks.StartTimestamp *

  • Despatch.Picks.EndTimestamp *

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

  • All DespatchPackage fields listed here

  • Despatch.Fields

  • Despatch.SalesOrder.Fields

  • Despatch.Picks.NumberOfContainers *

  • Despatch.Picks.NumberOfSpaces *

  • Despatch.Picks.StartTimestamp *

  • Despatch.Picks.EndTimestamp *

  • DespatchItems.Quantity *

  • DespatchItems.ItemType.Fields *

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

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

SalesOrderStatusChanges

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

GoodsReceived

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

TrackingNumberReceived

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

IncrementalChanges

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

Returns

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

DespatchPackageTrackingNumberReceived

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

DespatchPackageDespatched

https://my-website.com/so={Despatch.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 HTTP 200 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.


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:

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

  • eventType: the type of the event to which the caller wishes to subscribe. AvailabilityChanges, SalesOrderStatusChanges, GoodsReceived, TrackingNumberReceived, IncrementalChanges, Returns, DespatchPackageTrackingNumberReceived, or DespatchPackageDespatched.

  • filter: a search value used to filter the events that are raised. Subscribers may leave this blank to receive all events of the chosen type.

  • callbackUrl: a URL that PVX will call when the event is raised.

  • encodeParameterData: a Boolean setting that defines whether the subscriber wishes to receive event data in a URL-encoded format. Setting this value to “true” on a subscription request will instruct Peoplevox to HTML-encode any potentially dangerous characters in the event data. Note that this encoding is only applied to the data that is injected into the URL and parameter placeholders; the purpose of this setting is to ensure that when placeholders are replaced with actual event data, the resulting URL and parameters do not become invalid. Subscribers may wish to set this when their subscription references a field that is likely to contain large quantities of string data, such as {ItemType.Description}. This setting will preserve any delimiters that Peoplevox introduces when presenting a collection. To parse a subscription that is encoded, subscribers should first identify the substring that represents the data for a given parameter, then they should split based upon the delimiter (if it is a collection), then they should decode each member of the collection.

Return value

SubscribeEventResponse object.

  • ResponseId: 0 if call has succeeded, -1 if failed.

  • Detail: SubscriptionId

  • TotalCount: 0

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>https://my-website.com/item={ItemCode}&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 


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

  • eventType: the type of the event to which the caller wishes to subscribe. AvailabilityChanges, SalesOrderStatusChanges, GoodsReceived, TrackingNumberReceived, IncrementalChanges, Returns, DespatchPackageTrackingNumberReceived, or DespatchPackageDespatched.

  • filter: a search value used to filter the events that are raised. Subscribers may leave this blank to receive all events of the chosen type.

  • postUrl: a URL that PVX will call when the event is raised.

  • postParams: the POST parameters that PVX will include in the body of the request when the event is raised.

  • encodeParameterData: a Boolean setting that defines whether the subscriber wishes to receive event data in a URL-encoded format. Setting this value to “true” on a subscription request will instruct Peoplevox to HTML-encode any potentially dangerous characters in the event data. Note that this encoding is only applied to the data that is injected into the URL and parameter placeholders; the purpose of this setting is to ensure that when placeholders are replaced with actual event data, the resulting URL and parameters do not become invalid. Subscribers may wish to set this when their subscription references a field that is likely to contain large quantities of string data, such as {ItemType.Description}. This setting will preserve any delimiters that Peoplevox introduces when presenting a collection. To parse a subscription that is encoded, subscribers should first identify the substring that represents the data for a given parameter, then they should split based upon the delimiter (if it is a collection), then they should decode each member of the collection.

Return value

SubscribeEventResponse object.

  • ResponseId: 0 if call has succeeded, -1 if failed.

  • Detail: SubscriptionId

  • TotalCount: 0

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>https://my-website.com/ProcessAvailabilityChanges</peop:postUrl>
         <peop:postParams>item={ItemCode}&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 xmln="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> 

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

  • eventType: the type of the event to which the caller wishes to subscribe. AvailabilityChanges, SalesOrderStatusChanges, GoodsReceived, TrackingNumberReceived, IncrementalChanges, Returns, DespatchPackageTrackingNumberReceived, or DespatchPackageDespatched.

  • filter: a search value used to filter the events that are raised. Subscribers may leave this blank to receive all events of the chosen type.

  • sitesFilter: a search value specifically used to filter the events by Site reference. Can be used in conjunction with the filter.

  • callbackUrl: a URL that PVX will call when the event is raised.

  • encodeParameterData: a Boolean setting that defines whether the subscriber wishes to receive event data in a URL-encoded format. Setting this value to “true” on a subscription request will instruct Peoplevox to HTML-encode any potentially dangerous characters in the event data. Note that this encoding is only applied to the data that is injected into the URL and parameter placeholders; the purpose of this setting is to ensure that when placeholders are replaced with actual event data, the resulting URL and parameters do not become invalid. Subscribers may wish to set this when their subscription references a field that is likely to contain large quantities of string data, such as {ItemType.Description}. This setting will preserve any delimiters that Peoplevox introduces when presenting a collection. To parse a subscription that is encoded, subscribers should first identify the substring that represents the data for a given parameter, then they should split based upon the delimiter (if it is a collection), then they should decode each member of the collection.

Return value

SubscribeEventWithSitesFiltersResponse object.

  • ResponseId: 0 if call has succeeded, -1 if failed.

  • Detail: SubscriptionId

  • TotalCount: 0

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>https://my-website.com/item={ItemCode}&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>


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.


Sales order / SalesOrder

  • SalesOrderNumber

  • TotalNumberOfPicks

  • TotalNumberOfFinishedPicks

  • CustomerPurchaseOrderReferenceNumber

  • PriorityId

  • IsPartialShipmentOk

  • StatusId

  • RequestedDeliveryDate

  • ShippingCost

  • Email

  • ContactName

  • TotalSale

  • Discount

  • TaxPaid

  • CreatedDate

  • ChannelName

  • OnHold

  • Attribute1

  • Attribute2

  • Attribute3

  • Attribute4

  • Attribute5

  • StopShip

  • SalesOrderStatu.Name

  • ShippingAddress.Line1

  • ShippingAddress.Line2

  • ShippingAddress.TownCity

  • ShippingAddress.Region

  • ShippingAddress.PostCode

  • ShippingAddress.CountryName

  • InvoiceAddress.Line1

  • InvoiceAddress.Line2

  • InvoiceAddress.TownCity

  • InvoiceAddress.Region

  • InvoiceAddress.PostCode

  • InvoiceAddress.CountryName

  • Site.Reference

  • ServiceType.Name

  • ServiceType.Code


Item type / ItemType

  • ItemCode

  • Name

  • Barcode

  • Description

  • Active

  • ItemTypeGroupName

  • UnitOfMeasureSymbol

  • DefaultEconomicOrderQuantity

  • DefaultLeadTime

  • DefaultSuppliersPartNumber

  • HasSerialNumbers

  • UseManufacturersSerialNumber

  • ReorderPoint

  • PickPolicyName

  • Traceability

  • ShelfLife

  • DefaultNumberItemsPerContainer

  • ContainerTypeName

  • DefaultNumberItemsPerOuterCase

  • DefaultNumberItemsPerInnerCase

  • BuyPrice

  • WholesalePrice

  • RetailPrice

  • Weight

  • WeightMeasureSymbol

  • Height

  • Width

  • Depth

  • DimensionMeasureSymbol

  • Tags

  • Attribute1

  • Attribute2

  • Attribute3

  • Attribute4

  • Attribute5

  • Attribute6

  • Attribute7

  • Attribute8

  • Attribute9

  • Attribute10

  • Attribute11

  • Attribute12

  • Attribute13

  • Attribute14

  • Attribute15

  • OnHand (AvailabilityChanges only)

  • Allocated (AvailabilityChanges only)

  • Available (AvailabilityChanges only)

  • POQuantityOutstanding (AvailabilityChanges only)

  • SOQuantityOrdered (AvailabilityChanges only)

  • RequiredStock (AvailabilityChanges only)

  • MinimumPickLocationQuantity

  • DefaultReplenishmentQuantity


Despatch

  • DespatchNumber

  • TrackingNumber

  • StartTimestamp

  • EndTimestamp

  • NumberOfPackages

  • TrackingNumberTimestamp

  • Carrier.Name

  • Carrier.Reference

  • ServiceType.Name

  • ServiceType.Code

  • LoadReference


Despatch package / DespatchPackage

  • Weight

  • Height

  • Width

  • Depth

  • TrackingNumber

  • PackageNumber

  • PackageType.Name

  • PackageType.Weight

  • PackageType.Height

  • PackageType.Width

  • PackageType.Depth


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

  • SubscriptionId: an integer value that identifies the subscription from which the caller wishes to unsubscribe. This ID can be found in the Detail of the response from the initial subscription request.

Return value

UnsubscribeEventResponse object.

  • ResponseId: 0 if call has succeeded, -1 if failed.

  • Detail: True, or False when the specified subscription is not found.

  • TotalCount: 0

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>


Back to Top