Using the Shipments.PUT API for Export Shipping Automation
This article explains how to structure a Shipments.PUT request in Descartes Pacejet to support export shipping. It focuses on how item data, commodity mapping and pricing work together so Pacejet can automate packaging, export documentation and customs values.
This example uses a shipment with three products, a MacBook Pro, iPad Air and iPhone 16, packed into two boxes. It shows how item-level detail can help Pacejet build package, commodity and export information automatically.
Test the API Request in Pacejet
You can test the Shipments.PUT request directly in the Pacejet User Interface without writing code. Open Samples to submit JSON and review the resulting shipment.
Sample Shipments.PUT Request
The following JSON sample shows a shipment from a facility in Texas to a customer in Toronto, Canada. It includes two packages and item-level product details for export processing.
{
"Location": "DemoNetSuite2000",
"LicenseID": "a10faa14-db54-11d5-8c05-e3ecc49d0927",
"Origin": {
"LocationType": "Facility",
"LocationSite": "MAIN",
"LocationCode": "1",
"CompanyName": "ShipItFaster.com",
"Address1": "709 E. 44th",
"City": "Lubbock",
"StateOrProvinceCode": "TX",
"PostalCode": "79404",
"CountryCode": "US",
"ContactName": "Steve Sellers",
"Email": "steve.sellers@shipitfaster.com",
"Phone": "877-722-3538"
},
"Destination": {
"LocationType": "Customer",
"LocationSite": "MAIN",
"CompanyName": "Canada Retail Imports",
"Address1": "250 King Street West",
"City": "Toronto",
"StateOrProvinceCode": "ON",
"PostalCode": "M5V1J2",
"CountryCode": "CA",
"ContactName": "Receiving Department",
"Email": "receiving@canadaretail.ca",
"Phone": "416-555-2200"
},
"ShipmentDetail": {},
"CustomFields": [
{
"name": "AutoPackShipment",
"value": "FALSE"
}
],
"PackageDetailsList": [
{
"PackageNumber": "BOXL",
"Dimensions": {
"Length": "18",
"Width": "14",
"Height": "8",
"Units": "IN"
},
"ProductDetailsList": [
{
"Number": "MACBK",
"Description": "MacBook Pro",
"Weight": "6",
"Dimensions": {
"Length": "14",
"Width": "10",
"Height": "2",
"Units": "IN"
},
"Quantity": {
"Units": "EA",
"Value": "1"
},
"commodityName": "LAPTOP",
"Price": {
"Amount": "2500.00",
"Currency": "USD"
},
"Cost": {
"Amount": "2100.00",
"Currency": "USD"
}
},
{
"Number": "IPADAIR",
"Description": "iPad Air",
"Weight": "2",
"Dimensions": {
"Length": "10",
"Width": "7",
"Height": "1",
"Units": "IN"
},
"Quantity": {
"Units": "EA",
"Value": "2"
},
"commodityName": "TABLET",
"Price": {
"Amount": "900.00",
"Currency": "USD"
},
"Cost": {
"Amount": "700.00",
"Currency": "USD"
}
}
]
},
{
"PackageNumber": "BOXM",
"Dimensions": {
"Length": "16",
"Width": "12",
"Height": "6",
"Units": "IN"
},
"ProductDetailsList": [
{
"Number": "IPHONE",
"Description": "iPhone 16",
"Weight": "1",
"Dimensions": {
"Length": "7",
"Width": "4",
"Height": "1",
"Units": "IN"
},
"Quantity": {
"Units": "EA",
"Value": "3"
},
"commodityName": "IPHONE",
"Price": {
"Amount": "1200.00",
"Currency": "USD"
},
"Cost": {
"Amount": "950.00",
"Currency": "USD"
}
},
{
"Number": "IPADAIR",
"Description": "iPad Air",
"Weight": "2",
"Dimensions": {
"Length": "10",
"Width": "7",
"Height": "1",
"Units": "IN"
},
"Quantity": {
"Units": "EA",
"Value": "1"
},
"commodityName": "TABLET",
"Price": {
"Amount": "900.00",
"Currency": "USD"
},
"Cost": {
"Amount": "700.00",
"Currency": "USD"
}
}
]
}
]
}Shipment Structure Overview
At a high level, the request includes origin and destination details, optional shipment settings and a list of packages with item-level detail. Together, these sections tell Pacejet how to build the shipment, calculate values and generate export documents.
Origin and Destination
The Origin and Destination sections define where the shipment is coming from and where it is going. These values affect rating, carrier selection and whether export processing is required.
Origin identifies the shipping facility, including address and contact details.
Destination identifies the receiving customer, including international address information.
In this example, the origin is ShipItFaster.com in Lubbock, Texas, and the destination is Canada Retail Imports in Toronto, Ontario. Because the destination country is CA, Pacejet treats this as an international shipment and enables export-related processing.
Controlling Packing Behavior
The request includes a custom field that controls how packing is handled. Enter AutoPackShipment = FALSE to indicate that the shipment is already packed and that the provided package structure should be used as is.
If this field is set to TRUE or omitted, Pacejet can pack items automatically based on packing logic defined in the system.
Packages and Items
The PackageDetailsList defines the physical shipment structure. Each package contains one or more items, and each item includes the data Pacejet needs for rating, packaging validation and export processing.
In this example, the shipment includes two packages. BOXL contains one MacBook Pro and two iPad Air units. BOXM contains three iPhone 16 units and one iPad Air.
Package Details
Each package includes the dimensions of the box and a unique identifier so Pacejet can keep the shipment structure intact.
PackageNumber is a unique identifier for the package.
Dimensions include length, width, height and units.
In this sample, BOXL is 18 x 14 x 8 inches and BOXM is 16 x 12 x 6 inches.
Item Details
Each item represents a product being shipped. This is the most important part of the request for export automation because it supplies the data Pacejet uses to build commercial and customs details.
Number is the unique item identifier from the enterprise resource planning system.
Description is the product description used in documents.
Weight is the unit weight of the item and must always be >0 (zero weights on any items will cause commodity lines to NOT be created for a shpiment).
Dimensions define the physical size of the item.
Quantity is the number of units in the package.
commodityName links the item to a Pacejet Commodity record.
Price is the selling price used for export valuation.
Cost is the internal cost, used for reporting or optional processes.
The same item can appear in multiple packages. In this sample, IPADAIR appears in both BOXL and BOXM with different quantities.
Commodity Mapping
Pacejet uses Commodity records to simplify export and freight configuration. Instead of sending full export details for every item, the external system sends a single commodityName value that maps to a commodity already configured in Pacejet.
Each commodity in Pacejet can contain predefined attributes such as harmonized codes, country of origin, export classifications and freight class or National Motor Freight Classification details.
In this sample, LAPTOP is assigned to the MacBook Pro, TABLET is assigned to the iPad Air and IPHONE is assigned to the iPhone 16.
When the shipment is processed, Pacejet uses the commodityName value to attach the required export and freight attributes automatically.
Price and Cost Usage
Each item includes both Price and Cost, with an amount and currency. For export shipments, Price is the primary driver of value calculations. Cost can still be helpful for internal reporting or optional workflows.
In this sample, Price is used to build commodity-level values, calculate the total customs value and support commercial invoice generation. Cost is included for reference and can support internal reporting.
Package Information Creation
When Pacejet receives the shipment, it creates a Package Information section in the user interface. This reflects the package structure sent in the request so users can review the shipment exactly as it was submitted.
Each package can be expanded to show its contents, including item quantities and item details.
Declared Value Automation
Pacejet can calculate package-level declared values automatically using item Price data. This behavior can also be overridden with automation rules.
Without an override, the sample data would produce a package value of 4300.00 USD for BOXL and 4500.00 USD for BOXM, based on the item prices and quantities in each package. In this article's example workflow, a rule sets the declared value for each package to 100 USD instead.
Note: If no override is applied, declared value is typically calculated from the sum of item prices in each package.
Commodity and International Section
For international shipments, Pacejet creates a Commodity / International section. This section transforms item-level detail into commodity-level summaries that can be used for export documents.
Each row represents a commodity rather than an individual item. Pacejet groups items by commodityName and calculates total quantity across all packages, total weight, unit price and extended value.
In this sample, Pacejet creates three rows. LAPTOP has a quantity of one and an extended value of 2500.00 USD. TABLET has a total quantity of three and an extended value of 2700.00 USD. IPHONE has a quantity of three and an extended value of 3600.00 USD.
Customs Value Calculation
Pacejet can calculate the total customs value automatically by summing all item prices across the shipment. This behavior can also be controlled with rules.
Based on this sample JSON, the total customs value is 8800.00 USD. That total comes from 2500.00 USD for the MacBook Pro, 2700.00 USD for all iPad Air units and 3600.00 USD for the iPhone 16 units.
The calculated customs value appears on the shipment confirmation and is used for export documentation.
Commercial Invoice Generation
Using the commodity summaries and pricing data, Pacejet generates a commercial invoice with the export details needed for the shipment.
The invoice includes commodity descriptions, quantities, unit values, total values and country and classification data from the commodity records.
Key Takeaways
This sample shows the minimum data needed to automate export shipping through the Pacejet API. If you provide detailed item data, send a commodityName that maps to Pacejet Commodity records and include Price and Cost values for each item, Pacejet can build packages, calculate values and generate export documents without requiring the source system to manage export-specific logic.
Provide detailed item data, including weight, dimensions and quantity.
Send a commodityName value that maps to configured Pacejet Commodity records.
Include Price and Cost values for each item.
Make sure every item has a weight > 0 or commodity details will not be created.
Predefine packaging, or allow Pacejet to pack automatically.
Use rules in Pacejet to control declared value and customs value behavior.