Domestic Shipping

To successfully create and process a domestic shipment, you must provide the following essential details. While many additional parameters can be added to the shipment object, this example demonstrates the minimum information required to generate a label for a domestic shipment.

{
   "shipment":{
      "to_location":{
         "first_name":"string", // or company
         "address1":"string",
         "city":"string",
         "state":"string", // for a US state use the two-digit state code
         "country":"string", // two-digit country code
         "postal_code":"string",
         "phone":"string"
      },      
      "from_location":{
         "company":"Test Test", // or first_name
         "address1":"string",
         "city":"string",
         "state":"string",
         "country":"string",
         "postal_code":"string",
         "phone":"string"
      },
      "parcels":[
         {
            "length":17.0,
            "width":20.0,
            "height":11.0,
            "weight":240.0,
            "package_type":"string"
         }
      ],
      "service_id":1172
   }
}

Shipment Object Breakdown

• Shipment Object: The primary container for all shipment-related details.
• to_location / from_location: The to_location and from_location objects are required to define the destination and origin addresses.
• parcels: The parcels array is necessary to specify the package’s dimensions using the fields length, width, height, weight, and package_type.
• service_id: The service_id identifies the shipping service used (e.g., USPS Priority Mail, UPS Ground, or FedEx 2Day).
  • If you're unsure of the correct service_id needed, use the Rates endpoint to retrieve available rates and service IDs.

Errors and Warnings

If any of the required fields are omitted, the system will return an error. For example, if the parcel object is missing, you'll see an error message like this:

Example Error: Status: 500 - Internal Server Error

{
    "status": "error",
    "error_code": "parcel.missing_parcels",
    "error_message": "Missing parcels for request. At least one parcel is required."
}

US Territories and Military Shipments

Shipping to a U.S. territory or military destination (APO/FPO) requires using a domestic service with USPS. However, the shipment object also needs additional information such as an HS Tariff Code or EEL/PFC code. Refer to the International Shipments section for more details.