TABLE OF CONTENTS


Getting set up in Shiptheory

Creating your Peoplevox instance

To create a new Peoplevox instance go to your integrations page and click on Peoplevox to add a new integration.


You will be redirected to your Peoplevox integration page. Make a note of the URL shown there.

Getting your API Token

Peoplevox integrations leverage Shiptheory's API to download your shipments. You will therefore need an API token to use Peoplevox. Peoplevox integrations use long-lasting user tokens, not the short-lived tokens generated by the API's "/token" endpoint. 


To generate a token navigate to your user tokens page which can be found by navigating to the user icon in the bottom left of your screen.


To create a new token enter a name in the text input at the top of the page and click Create. Please note that token names must be unique.


Once you've clicked create you will see your token - make a copy of it now and keep it safe. This is the only time your token will be displayed.

Getting set up in Peoplevox

Creating your Shiptheory Integration

Log into Peoplevox and select the Integration pane.


Select Carrier Integration and then click Add New


Set the fields to the following:

  • Name: Shiptheory
  • Timeout: 10000
  • API Key: Your API token you copied
  • Endpoint: The endpoint from your integration page
  • Tracking number format - {outbound}  - this option means that only the outbound tracking number will be returned to Peoplevox.
  • Request schema version: 2.0


Requesting shipping labels and documents

Add a document type called "Shipping Label" with a reference of "shipping_label" and map it to a print template of your choice.


Note: If you would also like Shiptheory to generate and return other document types, then please follow this guide.


Then click Save

Import your Shiptheory configured services into Peoplevox

For Shiptheory to update Peoplevox with the actual shipping service selected by automated shipping rules, Shiptheory services will need to be set up in Peoplevox. 


To export configured services from Shiptheory go to the Peoplevox integration page and click to get your services CSV:

Review the file. There are four columns: Carrier, Name, Code and OutboundReference.


You must first ensure that any Carrier names (the first column on the CSV) already exist in Peoplevox. You can confirm if they exist by navigating to the Carriers tab in Peoplevox and checking if the carrier exists (under the Name heading, or by using the search). If you need to create a new carrier, you can do so by clicking Add, typing the name as it appears and then Save.


Once the carriers are created or confirmed as existing already, you can go to the Integration section of Peoplevox and navigate to the Integration templates tab (default). The CSV then be uploaded by selecting the "Service types" integration template and clicking import.


How Peoplevox behaves with Shiptheory once set up

General Behaviour

When you print a request for a Despatch package in Peoplevox a request will be sent to Shiptheory. Shiptheory will use its automated shipping rules to book a shipment and return a label and tracking number to Peoplevox. Shiptheory will also update the shipping service used for each shipment on the Despatch package in Peoplevox.


Things to look out for

  • If you have both the Shiptheory print client and the Peoplevox print client set up and your Shipping rule in Shiptheory is set to print to a printer then you may see the same label printed twice as the 2 clients work independently of each other. If you wish to use the Peoplevox print client then ensure that your shipping rules do not have a printer assigned to them. 
  • If your shipping rules are not set to create a label then Shiptheory will return a failure response to Peoplevox. Please ensure that your shipping rules are set to immediately create a label and not to schedule a shipment or mark a shipment for approval otherwise your shipment will still be processed in Shiptheory, but you will not receive a label in Peoplevox.
  • When your shipment in Shiptheory is marked as complete any further print requests from Peoplevox will not update any shipment details or create any new carrier bookings. Instead, it will skip over these steps and return the shipping label.
  • If your Shiptheory services are not set up in Peoplevox, Despatch and Despatch package records in Peoplevox will be updated to "Unknown Carrier / Unknown Service". Following any changes to shipping services configured in Shiptheory, you should reimport your services into Peoplevox following the guide above.