Skip to main content
Meet Fred Fred picture Fred runs an online pet furniture business, www.fred-bed.com. He doesn’t own any physical store, his customers purchase pet furniture online. He sells dog beds that his customers customize with their favorite cushion. He has learned that it’s easier for him to ship the cushion and bed in separate packages. Fred needs to know how to multi-ship his items, to make it easier for his business and to save money. He also needs to share the tracking information with his customers so they can track the progress of their packages. Fred creates parcels for each part of his order that he can use over and over. 
curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 50,
  "width": 30,
  "height": 30,
  "distance_unit": "cm",
  "weight": 10,
  "mass_unit": "kg",
  "template": "",
  "metadata": "Bed-Base-1-of-2"
}'


curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 50,
  "width": 30,
  "height": 10,
  "distance_unit": "cm",
  "weight": 5,
  "mass_unit": "kg",
  "template": "",
  "metadata": "Tartan-pattern-2-of-2"
}'
The response includes the object ID for the parcels that were created. 
"object_id": "ed07d387707d477090066befcccd3d2b"
"object_id": "efad281d588a456c85be772133de50db"
These parcels can then be used to create a multi-piece shipment. The response is the shipment object that includes rate options for the shipment. The rates show the cost (amount) for both parcels together. In the background, when Fred creates the shipment with multiple parcels, the Shippo API does the work to create the multi-piece shipment, hiding the complexity from Fred.
Create shipment request
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
                "name": "Fred",
                "street1": "215 Clayton St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94117",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@fred-bed.com"
            },
  "address_to": {
                "name": "Mrs. Hippo",
                "street1": "965 Mission St.",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94105",
                "country": "US",
                "phone": "+1 555 341 9393",
                "email": "support@shippo.com"
            },
  "parcels": [ "ed07d387707d477090066befcccd3d2b", "efad281d588a456c85be772133de50db"],
  "extra": {},
  "async": false
}'
Create shipment response
"rates": [
        {
            "object_created": "2023-07-25T15:43:52.528Z",
            "object_id": "4f0d1707d8d442bd8c9faf6e7a5c4829",
            "object_owner": "support@fred-bed.com",
            "shipment": "65d7dc06708342238772a0dafab9b7b4",
            "attributes": [
                "FASTEST"
            ],
            "amount": "121.18",
            "currency": "USD",
            "amount_local": "121.18",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air® Early",
                "token": "ups_next_day_air_early_am",
                "terms": "",
                "extended_token": "ups_next_day_air_early_am",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "08:30:00",
            "duration_terms": "Next business day delivery by 8:30 a.m., 9:00 a.m., or 9:30 a.m. ",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        }
]
Fred can purchase the labels by passing the rate to the transaction endpoint. The response is a list of transaction objects, one transaction for each parcel. Fred can use the label_url to print labels for each parcel. The tracking_number from the response is the principal (mstr) tracking number of the entire Shipment. This tracking number associates all tracking numbers in the shipment. As an example, this label has the mstr tracking number on it that includes information about the status of the entire multi-piece shipment.
Purchase label request
curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "4f0d1707d8d442bd8c9faf6e7a5c4829",
  "label_file_type": "PDF",
  "async": false
}'
Purchase label response
{
   "results":[
      {
         "object_state":"VALID",
         "status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"support@fred-bed.com",
         "was_test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":{
            "object_created":"2014-07-17T00:43:50.402Z",
            "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
            "status":"UNKNOWN",
            "status_details":"",
            "status_date":null
         },
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "eta":"2014-07-21T12:00:00.000Z",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "commercial_invoice_url": "",
         "messages":[

         ],
         "metadata":""
      },
      {...},
      {...}
   ]
}