Overview

While requests sent to the Shipments resource without any identification will be automatically assigned a Transaction ID, the best-practice (as illustrated earlier in this guide) for most shipping integrations is to pass a TransactionID and an ExternalTransactionID to prevent duplicate shipments and align reference fields for users.

For example, using a Packing List number as both the Transaction ID and External Transaction ID for Shipments works well if your ERP permits multiple shipments against a single Sales Order to completely ship all ordered products.

Preventing duplicate shipments with Transaction ID

Select the Shipments endpoint, choose any sample request or enter your own, include the TransactionID and ExternalTransactionID values like those shown below, click “Run It” to submit the request one time, and then click “Run It” again to submit the same request a second time. Submitting the same request with a duplicate Transaction ID results in the error message “TransactionID xxxxxxx has already been imported. Use PUT to delete and re-import”.

{
  "Location": "APITest",
  "ExternalTransactionID": "1234501",
  "TransactionID": "1234501",
  "Origin": { … },
  "Destination": { … }
}

Using familiar reference numbers in shipping

Another reason to set your own TransactionID and ExternalTransactionID values is to provide users with familiar reference values such as packing lists numbers. For example, where the Transaction ID shown on the Shipping Workbench is the same as the Packing List in the ERP.

Processing manual shipments without ERP integration

While most shipping transactions with Pacejet are processed with integration, some users ship samples or other “manual” or “miscellaneous” shipments not associated with any order and not integrated with an ERP or other system (e.g. samples). Pacejet supports manual shipments by allowing users to directly enter shipping data or use “saved templates” for frequent shipping scenarios. Because manual shipments include no ExternalTransactionID, no ConfirmsList records are created and asynchronous integration will not attempt to update an ERP or other system.

Updating shipments before and after shipping with carriers

Last minute changes are an unfortunate part of most shipping operations and most companies, for one reason or another, will sometimes need to change or cancel shipments at some point in the fulfillment process. The Pacejet platform supports several different “void” activities to manage various changes such as shipping with a different carrier, update the order with more or different products, or cancelling the shipment altogether. Some use-cases involve activities in the Pacejet user interface and others involving different Pacejet API resources (e.g. VoidConfirms) or different actions on resources (e.g. PUT Shipments).

One best practice process for shipping integrations is to use basic retry logic to handle situations such as temporary Internet connectivity loss. To help with retries, POST Shipments will detect and block duplicate resource adds for the same TransactionID (another reason to send a transactionID aligned with a value in your ERP). Note that the Pacejet API will return a 409 CONFLICT status code when this action is attempted along with the result message shown below.

If a user cancels a shipment entirely in the ERP, the shipping integration can use the DELETE action with Shipments to delete the shipment in Pacejet. If the shipment has changed in the ERP and the integration needs to update Pacejet, the PUT action can be used instead of POST to delete and replace Shipments. However, if a user has already processed a shipment with a carrier and a DELETE or PUT is attempted, Pacejet will return 409 CONFLICT with the message shown below.

There are currently two ways to support reprocessing of a shipment. One is to use the Void page and the other starting with Version 2, is to use the DELETE verb which has the same behavior as a void. To use the UI, users must first use the Transactions | Void Shipments page to locate a shipment by tracking number or TransactionID and process a void. Depending on the carrier, this may issue a carrier void transaction but will also then issue a void transaction in Pacejet. In order to retain a transactional history, Pacejet does not actually delete voided shipment from the system but instead reassigns them to a new ID while with a VOID status while retaining access to the original ExternalTransactionID and TransactionID.

For a shipping integration to automatically revert ERP activities when users void transactions, the ConfirmsList resource supports a /New/VoidConfirms option to locate voided transactions that have not yet been reverted.

The other option is to use DELETE verb of Shipments. With version 2 of the API, when deleting a shipment, it retains the transaction history. It will reassign the shipment a new transaction number.

The number assigned is the next available transaction number. The voided shipment with the new transaction number can also be viewed on the Shipments page.

With Version 1 of DELETE Shipments, the entire transaction of a completed shipment would be deleted rather than have a new transaction number. Also, for Version 2, like the Void functionality, deleting a Shipment that has a status of Planned or Error will remove the records.