Carrier and Method Selection & Shipment Label API

Determine carrier service method and print shipping labels all in one call with Shipium's Carrier and Method Selection & Shipment Label API.

Get started

To use the Carrier and Method Selection & Shipment Label API, you can follow the instructions on this page, which also include guidance for additional options when calling the API. Information about determining carrier service method and generating shipment labels within the Shipium platform can be found in the Carrier and Service Method & Shipment Labels, Carrier and Method Selection, and Shipment Labels documentation.

Determine carrier service method with or without shipping labels with the Carrier and Method Selection & Shipment Label API

The Shipium Carrier and Method Selection & Shipment Label API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Carrier and Method Selection & Shipment Label API calls is included in the table below.

API typeAPI endpoint
POSThttps://api.shipium.com/api/v1/shipment/carrierselection/label

📘

Authentication for API Calls

In the cURL example on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

👉

Test mode

Want to run some examples and not charge any real money against your account?

You can add testMode: "true" to the data passed to any label call to retrieve labels without charging money in a carrier-specific manner. Most carriers will mark their labels in a way to make clear that they are void, such as inserting "VOID" throughout the label or using a predefined ID.

The examples below contain the testMode flag to err on the side of caution – remove it to make production calls.

The required and optional fields for calling the Carrier and Method Selection & Shipment Label API are included in the Request and Response Fields for API Calls section of this document.

Determine carrier and ship method without retrieving a label

Example cURL call

This example shows a request to determine the carrier service method for a shipment without retrieving a shipment label:

curl --request POST   
  --url https://api.shipium.com/api/v1/shipment/carrierselection/label 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following minimum fields should be included in your JSON request. This example request body also includes an optional return-to address object that is included in the shipmentParameters.

Note that the generateLabel value is set to "false" to not create a label with the request and the includePackagesArray value is set to "true" to include the package information in the response.

{
  "currencyCode": "usd",
  "generateLabel": "false",
  "shipmentParameters": {
        "includePackagesArray": "true",
        "shippedDateTime": "2023-09-06T18:30:55.558Z",
        "orderedDateTime": "2022-04-07T18:30:55.558Z",
        "testMode": "true",
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St.",
        },
        "returnToAddress": {
            "name": "Rod Runner",
            "phoneNumber": "865-433-9999",
            "phoneNumberCountryCode": "+2",
            "emailAddress": "[email protected]",
            "company": "ACME",
            "street1": "456 Main St.",
            "street2": "Suite 8",
            "city": "Albuquerque",
            "state": "NM",
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
  },
        "orderItemQuantities": [
            {
                "productId": "ET-14-4000",
                "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": "13",
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": "15",
                "width": "10",
                "height": "5",
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": "13",
            "weightUnit": "oz"
        },
  }
}

Example response body

{
  "shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
  "orderedDateTime": "2022-04-07T18:30:55.558Z",
  "shippedDateTime": "2023-09-06T18:30:55.558Z",
  "ignoreUpgradeSpendLimits": false,
  "fulfillmentType": "customer",
  "packages": [
      {
          "orderItemQuantities": [
              {
                  "productId": "ET-14-4000",
                  "quantity": 2,
                  "productDetails": [],
                  "hazmat": false
              }
          ],
          "packagingType": {
              "packagingMaterial": "box",
              "linearDimensions": {
                  "linearUnit": "in",
                  "length": 15.0,
                  "width": 10.0,
                  "height": 5.0
              },
              "packagingWeight": {
                  "weightUnit": "oz",
                  "weight": 13.0
              }
          },
          "totalWeight": {
              "weightUnit": "oz",
              "weight": 13.0
          }
      }
  ],
  "orderItemQuantities": [
      {
          "productId": "ET-14-4000",
          "quantity": 2,
          "productDetails": [],
          "hazmat": false
      }
  ],
  "destinationAddress": {
      "name": "Wile E. Coyote",
      "phoneNumber": "888-555-1234",
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
  },
  "shipFromAddress": {
      "name": "Ro Drunner",
      "phoneNumber": "5555555555",
      "emailAddress": "[email protected]",
      "company": "Sell It",
      "street1": "401 N. Centre St.",
      "city": "Pottsville",
      "state": "PA",
      "countryCode": "US",
      "postalCode": "17901"
  },
   "returnToAddress": {
      "name": "Rod Runner",
      "phoneNumber": "865-433-9999",
      "phoneNumberCountryCode": "+2",
      "emailAddress": "[email protected]",
      "company": "ACME",
      "street1": "456 Main St.",
      "street2": "Suite 8",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
   },
  "fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
  "requestFulfillmentContextIds": [],
  "originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
  "packagingType": {
      "packagingMaterial": "box",
      "linearDimensions": {
          "linearUnit": "in",
          "length": 15.0,
          "width": 10.0,
          "height": 5.0
      },
      "packagingWeight": {
          "weightUnit": "oz",
          "weight": 13.0
      }
  },
  "totalWeight": {
      "weightUnit": "oz",
      "weight": 13.0
  },
  "shipmentTags": [],
  "carrierSelection": {
      "status": "success",
      "statusDetails": "success",
      "carrierSelectionId": "911b488c-c620-4663-a554-bf9628e7ff43",
      "shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
      "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
      "carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
      "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:dXBzbWktcGFyY2VsLXNlbGVjdC1zZXJ2aWNlLW1ldGhvZDo6NDNjYTI3ZDctZmUzNi00YjI1LTk4MDAtYTdmMTE2ZDIyMTQxOjdiODExNzA0LTlhMTYtNGQzYi1iODQ5LTQzYzcyNzk0MTVhYzpmZTFlMjg1Mi1kNTBiLTQ5OGQtOGIxMC05MGJiMWM5ODFjZTA6dXBzbWk6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
      "carrier": "upsmi",
      "carrierServiceMethodId": "upsmi-parcel-select-service-method",
      "serviceMethodName": "UPS Mail Innovations Parcel Select",
      "totalCost": 1.0,
      "carrierCompareCost": 1.0,
      "carrierInvoiceCost": 1.0,
      "operationalCost": 1.0,
      "thirdPartyBilling": false,
      "carrierSelectionDateTime": "2024-03-25T19:44:22.232Z"
  },
  "saturdayDelivery": false,
  "deliverySignatureOption": "None",
  "forceThirdPartyBilling": false,
  "createdWithVersion": "v2",
  "multiParcel": false,
  "testMode": true
}

Determine carrier and ship method without retrieving a label, with tenants

Example cURL call

This example shows a request to determine the carrier service method for a shipment without retrieving a shipment label, and associating a tenant with the shipment:

curl --request POST   
  --url https://api.shipium.com/api/v1/shipment/carrierselection/label 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following minimum fields should be included in your JSON request. Note the inclusion of tenantId in the shipment parameters.

{
  "currencyCode": "usd",
  "generateLabel": "false",
  "includeEvaluatedServiceMethodsInResponse": "true",
  "shipmentParameters": {
        "tenantId" : "3b343401-7a52-4709-a053-ab35ec9ecd5b",
        "shippedDateTime": "2023-09-06T18:30:55.558Z",
        "orderedDateTime": "2022-04-07T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "orderItemQuantities": [
            {
                "productId": "ET-14-4000",
                "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": "13",
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": "15",
                "width": "10",
                "height": "5",
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": "13",
            "weightUnit": "oz"
        },
  }
}

Example response body

{
    "shipiumShipmentId": "afca15f1-4084-49a4-9792-1c78f641ac5e",
    "orderedDateTime": "2022-04-07T18:30:55.558Z",
    "shippedDateTime": "2023-09-06T18:30:55.558Z",
    "rawDesiredDeliveryDate": "2024-04-03",
    "desiredDeliveryDate": "2024-04-04T05:59:59.999Z",
    "desiredDeliveryDateLocal": "2024-04-03T23:59:59.999",
    "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
    "estimatedDeliveryDateLocal": "2024-09-11T20:00:00",
    "destinationTimezoneId": "America/Albuquerque",
    "originTimezoneId": "America/Pottsville",
    "ignoreUpgradeSpendLimits": false,
    "fulfillmentType": "customer",
    "orderItemQuantities": [
        {
            "productId": "ET-14-4000",
            "quantity": 2,
            "productDetails": [],
            "shipiumOrderId": "123",
            "hazmat": false
        },
        {
            "productId": "7G-100-0756",
            "quantity": 1,
            "productDetails": [],
            "hazmat": false
        }
    ],
    "destinationAddress": {
        "name": "Wile E. Coyote",
        "phoneNumber": "888-555-1234",
        "street1": "123 Main St.",
        "street2": "Suite 42",
        "city": "Albuquerque",
        "state": "NM",
        "countryCode": "US",
        "postalCode": "87121",
        "addressType": "commercial"
    },
    "shipFromAddress": {
        "name": "Ro Drunner",
        "phoneNumber": "5555555555",
        "emailAddress": "[email protected]",
        "company": "Sell It",
        "street1": "401 N. Centre St.",
        "city": "Pottsville",
        "state": "PA",
        "countryCode": "US",
        "postalCode": "17901"
    },
    "requestFulfillmentContextIds": [],
    "originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
    "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 15.0,
            "width": 10.0,
            "height": 5.0
        },
        "packagingWeight": {
            "weightUnit": "oz",
            "weight": 13.0
        }
    },
    "totalWeight": {
        "weightUnit": "oz",
        "weight": 13.0
    },
    "shipmentTags": [
        "test"
    ],
    "carrierSelection": {
        "status": "success",
        "statusDetails": "success",
        "carrierSelectionId": "1fb236b0-91a2-4aba-a8e2-f2431a70c8e5",
        "shipiumShipmentId": "afca15f1-4084-49a4-9792-1c78f641ac5e",
        "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
        "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
        "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:dXBzLWdyb3VuZC1zZXJ2aWNlLW1ldGhvZDo6NDExNmI3MmQtZjJmOC00YTBiLWE4ZGItN2VmN2E0ZGE5MWIxOjhjZDNlOTU4LWE1ZTktNGRkYS1hMmRhLTcyN2M1ZDJjMGQxMzoxMDg1NGMwNC01NTVjLTRmMDktOWEwZi1lZDA1NDJjNzUwNjk6dXBzOjVhMWVhNzI4LTRiYTItNGNjNi04OTJjLTFmMTIyZjM1MDc3NTo6",
        "carrier": "ups",
        "carrierServiceMethodId": "ups-ground-service-method",
        "serviceMethodName": "UPS Ground -ana",
        "totalCost": 1.0,
        "carrierCompareCost": 1.0,
        "carrierInvoiceCost": 1.0,
        "operationalCost": 1.0,
        "thirdPartyBilling": false,
        "carrierSelectionDateTime": "2024-04-03T14:42:20.434Z",
        "carrierZoneId": "ups-zone-7",
        "evaluatedServiceMethods": [
            {
                "carrier": "ups",
                "serviceMethodName": "UPS Ground -ana",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "usps",
                "serviceMethodName": "USPS Priority Mail Express",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "ups",
                "serviceMethodName": "UPS SurePost - ana",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 6.0,
                "injectionDetails": {}
            },
            {
                "carrier": "fedex",
                "serviceMethodName": "FedEx Priority Overnight",
                "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
                "totalCost": 11.0,
                "estimatedDeliveryDate": "2023-09-09T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "usps",
                "serviceMethodName": "USPS Priority Mail",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "fedex",
                "serviceMethodName": "FedEx Home Delivery",
                "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
                "totalCost": 4.13,
                "injectionDetails": {}
            },
            {
                "carrier": "ups",
                "serviceMethodName": "UPS Next Day Air Saver",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-09T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "usps",
                "serviceMethodName": "USPS Parcel Select",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-14T02:00:00Z",
                "injectionDetails": {}
            },
            {
                "carrier": "upsmi",
                "serviceMethodName": "UPS Mail Innovations Parcel Select",
                "carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
                "totalCost": 1.0,
                "injectionDetails": {}
            }
        ]
    },
    "saturdayDelivery": false,
    "deliverySignatureOption": "None",
    "forceThirdPartyBilling": false,
    "createdWithVersion": "v2",
    "multiParcel": false,
    "testMode": true
}

Determine carrier and ship method and generate a standard shipment label

Example cURL call

This example shows a request to determine the carrier service method for a shipment and also retrieve a shipment label:

curl --request POST   
  --url https://api.shipium.com/api/v1/shipment/carrierselection/label 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following minimum fields should be included in your JSON request. For this example, a value of true is being passed for the generateLabel, includeLabelImageInResponse, and manifest fields. Shipment manifests are required by some carriers. You can read more in Manifest Shipments.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
      "currencyCode": "usd",
      "includeLabelImagesInResponse": true,
      "labelFormats": [
          "zpl"
      ],
      "manifest": true
  },
  "shipmentParameters": {
        "shippedDateTime": "2024-04-06T18:30:55.558Z",
        "orderedDateTime": "2024-04-03T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "orderItemQuantities": [
            {
                "productId": "ET-14-4000",
                "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": "13",
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": "15",
                "width": "10",
                "height": "5",
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": "13",
            "weightUnit": "oz"
        },
  }
}

Example response body

{
  "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
  "orderedDateTime": "2022-04-07T18:30:55.558Z",
  "shippedDateTime": "2024-04-09T14:39:27.511Z",
  "ignoreUpgradeSpendLimits": false,
  "fulfillmentType": "customer",
  "orderItemQuantities": [
      {
          "productId": "ET-14-4000",
          "quantity": 2,
          "productDetails": [],
          "hazmat": false
      }
  ],
  "destinationAddress": {
      "name": "Wile E. Coyote",
      "phoneNumber": "888-555-1234",
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
  },
  "shipFromAddress": {
      "name": "Ro Drunner",
      "phoneNumber": "6612475319",
      "emailAddress": "[email protected]",
      "company": "Sell It",
      "street1": "401 N. Centre St.",
      "city": "Pottsville",
      "state": "PA",
      "countryCode": "US",
      "postalCode": "17901"
  },
  "fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
  "requestFulfillmentContextIds": [],
  "originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
  "packagingType": {
      "packagingMaterial": "box",
      "linearDimensions": {
          "linearUnit": "in",
          "length": 15.0,
          "width": 10.0,
          "height": 5.0
      },
      "packagingWeight": {
          "weightUnit": "oz",
          "weight": 13.0
      }
  },
  "totalWeight": {
      "weightUnit": "oz",
      "weight": 13.0
  },
  "shipmentTags": [],
  "carrierSelection": {
      "status": "success",
      "statusDetails": "success",
      "carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
      "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
      "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
      "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
      "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
      "carrier": "fedex",
      "carrierServiceMethodId": "fedex-express-saver-service-method",
      "serviceMethodName": "FedEx Express Saver",
      "totalCost": 3.25,
      "carrierCompareCost": 3.25,
      "carrierInvoiceCost": 3.25,
      "operationalCost": 3.25,
      "thirdPartyBilling": false,
      "carrierSelectionDateTime": "2024-04-09T14:39:27.773Z",
      "carrierZoneId": "fedex-express-zone-7"
  },
  "carrierLabel": {
      "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
      "carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
      "shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
      "status": "success",
      "statusDetails": "success",
      "effectiveShipDateTime": "2024-04-10T04:00:00Z",
      "labelCreationDateTime": "2024-04-09T14:39:30.192Z",
      "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
      "carrier": "fedex",
      "carrierServiceName": "FedEx Corporation Account - 2",
      "serviceMethodName": "FedEx Express Saver",
      "carrierServiceMethodId": "fedex-express-saver-service-method",
      "carrierShipmentId": "794622496766",
      "carrierTrackingId": "794622496766",
      "shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",
      "carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622496766",
      "carrierLabelCurrencyCode": "USD",
      "carrierLabelPrice": 3.25,
      "billableWeight": {
          "weightUnit": "lb",
          "weight": 6.0
      },
      "documents": [
          {
              "labelExpiration": "2024-04-23T14:39:30.177778742Z",
              "labelFormat": "zpl",
              "labelProperties": {
                  "height": 4.0,
                  "width": 6.0,
                  "linearUnits": "in",
                  "dpi": 203,
                  "labelOrientation": "rotate_0"
              },
              "labelImage": {
                  "imageEncoding": "base64",
                  "imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI0OTY3NjYwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNDk2NzY2XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
              },
              "labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/5191f46a-7d43-4d8f-a859-f9193938b30f/carrierSelection/777584eb-0f08-44d6-98d0-df8bc1eba1c1/label/198edb20-1076-42d8-8723-830dd6f27ef4/zpl",
          }
      ],
      "internationalDocuments": [],
      "labelFailoverOccurred": false,
      "testMode": true,
      "multiParcel": false
  },
  "saturdayDelivery": false,
  "deliverySignatureOption": "None",
  "forceThirdPartyBilling": false,
  "createdWithVersion": "v2",
  "multiParcel": false,
  "testMode": true
}

Determine carrier and ship method and generate a standard shipment label, with tenants

Example cURL call

This example shows a request to determine the carrier service method for a shipment and also retrieve a shipment label, with the inclusion of a tenant:

curl --request POST   
  --url https://api.shipium.com/api/v1/shipment/carrierselection/label 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'  
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following minimum fields should be included in your JSON request. For this example, a value of true is being passed for the generateLabel, includeLabelImageInResponse, and manifest fields. Shipment manifests are required by some carriers. You can read more in Manifest Shipments.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
      "currencyCode": "usd",
      "includeLabelImagesInResponse": true,
      "labelFormats": [
          "zpl"
      ],
      "manifest": true
  },
  "shipmentParameters": {
        "tenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
        "shippedDateTime": "2024-04-06T18:30:55.558Z",
        "orderedDateTime": "2024-04-03T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "orderItemQuantities": [
            {
                "productId": "ET-14-4000",
                "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": "13",
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": "15",
                "width": "10",
                "height": "5",
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": "13",
            "weightUnit": "oz"
        },
  }
}

Example response body

{
  "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
  "orderedDateTime": "2022-04-07T18:30:55.558Z",
  "shippedDateTime": "2024-04-09T14:39:27.511Z",
  "ignoreUpgradeSpendLimits": false,
  "fulfillmentType": "customer",
  "orderItemQuantities": [
      {
          "productId": "ET-14-4000",
          "quantity": 2,
          "productDetails": [],
          "hazmat": false
      }
  ],
  "destinationAddress": {
      "name": "Wile E. Coyote",
      "phoneNumber": "888-555-1234",
      "street1": "123 Main St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "commercial"
  },
  "shipFromAddress": {
      "name": "Ro Drunner",
      "phoneNumber": "5555555555",
      "emailAddress": "[email protected]",
      "company": "Sell It",
      "street1": "401 N. Centre St.",
      "city": "Pottsville",
      "state": "PA",
      "countryCode": "US",
      "postalCode": "17901"
  },
  "fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
  "requestFulfillmentContextIds": [],
  "originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
  "packagingType": {
      "packagingMaterial": "box",
      "linearDimensions": {
          "linearUnit": "in",
          "length": 15.0,
          "width": 10.0,
          "height": 5.0
      },
      "packagingWeight": {
          "weightUnit": "oz",
          "weight": 13.0
      }
  },
  "totalWeight": {
      "weightUnit": "oz",
      "weight": 13.0
  },
  "shipmentTags": [],
  "carrierSelection": {
      "status": "success",
      "statusDetails": "success",
      "carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
      "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
      "partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
      "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
      "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
      "carrier": "fedex",
      "carrierServiceMethodId": "fedex-express-saver-service-method",
      "serviceMethodName": "FedEx Express Saver",
      "totalCost": 3.25,
      "carrierCompareCost": 3.25,
      "carrierInvoiceCost": 3.25,
      "operationalCost": 3.25,
      "thirdPartyBilling": false,
      "carrierSelectionDateTime": "2024-04-09T14:39:27.773Z",
      "carrierZoneId": "fedex-express-zone-7"
  },
  "carrierLabel": {
      "shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
      "carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
      "shipiumTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
      "partnerTenantId": "tenantid_123",
      "shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
      "status": "success",
      "statusDetails": "success",
      "effectiveShipDateTime": "2024-04-10T04:00:00Z",
      "labelCreationDateTime": "2024-04-09T14:39:30.192Z",
      "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
      "carrier": "fedex",
      "carrierServiceName": "FedEx Corporation Account - 2",
      "serviceMethodName": "FedEx Express Saver",
      "carrierServiceMethodId": "fedex-express-saver-service-method",
      "carrierShipmentId": "794622496766",
      "carrierTrackingId": "794622496766",
      "shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",
      "carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622496766",
      "carrierLabelCurrencyCode": "USD",
      "carrierLabelPrice": 3.25,
      "billableWeight": {
          "weightUnit": "lb",
          "weight": 6.0
      },
      "documents": [
          {
              "labelExpiration": "2024-04-23T14:39:30.177778742Z",
              "labelFormat": "zpl",
              "labelProperties": {
                  "height": 4.0,
                  "width": 6.0,
                  "linearUnits": "in",
                  "dpi": 203,
                  "labelOrientation": "rotate_0"
              },
              "labelImage": {
                  "imageEncoding": "base64",
                  "imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI0OTY3NjYwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNDk2NzY2XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
              },
              "labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/5191f46a-7d43-4d8f-a859-f9193938b30f/carrierSelection/777584eb-0f08-44d6-98d0-df8bc1eba1c1/label/198edb20-1076-42d8-8723-830dd6f27ef4/zpl",
          }
      ],
      "internationalDocuments": [],
      "labelFailoverOccurred": false,
      "testMode": true,
      "multiParcel": false
  },
  "saturdayDelivery": false,
  "deliverySignatureOption": "None",
  "forceThirdPartyBilling": false,
  "createdWithVersion": "v2",
  "requestTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
  "shipiumTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
  "partnerTenantId": "tenantid_123",
  "multiParcel": false,
  "testMode": true
}

Retrieve a previously generated label

The endpoint for retrieving a label is provided below.

Path

GET https://shiptime-service.shipium.com/api/v1/deliveryexperience/shipment/carrierSelection/label/{shipiumLabelId}?includeLabelImagesInResponse=true

Required path element: shipiumLabelId

Required parameter: includeLabelImageinResponse

Example request body

The request body is empty for this call.

Example response body

{
  "shipiumShipmentId": "17a793fc-f90c-421c-8af5-ae8f51084270",
  "carrierSelectionId": "e8a561fd-e70b-4950-82c7-4489e3c2a2b2",
  "shipiumTenantId": "3b343401-7a52-4709-a053-ab35ec9ecd5b",
  "partnerTenantId": "tenantid_123",
  "shipiumLabelId": "d9067cb5-99d4-4252-aa26-41b82b81950b",
  "status": "success",
  "statusDetails": "success",
  "effectiveShipDateTime": "2024-04-10T04:00:00Z",
  "labelCreationDateTime": "2024-04-09T14:49:20.585Z",
  "serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
  "carrier": "fedex",
  "carrierServiceName": "FedEx Corporation Account - 2",
  "serviceMethodName": "FedEx Express Saver",
  "carrierServiceMethodId": "fedex-express-saver-service-method",
  "carrierShipmentId": "794622502879",
  "carrierTrackingId": "794622502879",
  "carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622502879",
  "carrierLabelCurrencyCode": "USD",
  "carrierLabelPrice": 61.3,
  "billableWeight": {
      "weightUnit": "lb",
      "weight": 6.0
  },
  "documents": [
      {
          "labelExpiration": "2024-04-23T14:49:20.573369416Z",
          "labelFormat": "zpl",
          "labelProperties": {
              "height": 4.0,
              "width": 6.0,
              "linearUnits": "in",
              "dpi": 203,
              "labelOrientation": "rotate_0"
          },
          "labelImage": {
              "imageEncoding": "base64",
              "imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI1MDI4NzkwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNTAyODc5XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
          },
          "labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/17a793fc-f90c-421c-8af5-ae8f51084270/carrierSelection/e8a561fd-e70b-4950-82c7-4489e3c2a2b2/label/d9067cb5-99d4-4252-aa26-41b82b81950b/zpl",
      }
  ],
  "internationalDocuments": [],
  "labelFailoverOccurred": false,
  "testMode": true,
  "multiParcel": false
}

Request and response fields for API calls

The following table provides required and optional fields for calling the Carrier and Method Selection & Shipment Label API. However, the API is flexible to suit multiple use cases, and not all specialty fields are defined in this document. You can find additional support in the Carrier and Method Selection & Label API Reference and in the linked pages in this description.

In general, shipmentParameters are included for determining carrier service method, and labelParameters are included for generating shipment labels. Multi-parcel shipments require inclusion of multiParcelShipmentParameters in place of shipmentParameters.

International shipments must include customsInfo parameters in either shipmentParameters or multiParcelShipmentParameters. You can find the customsInfo parameters to include in the Customs Info for Shipments document. Additionally, you may need to declare some items as hazardous material, which has its own requirements.

If your organization utilizes injection sites in your network, you can also include injectionParameters by passing an injectionProfileId or injectionSiteId.

If you're interested in running simulations, you'll need to include simulationParameters.

Request fieldRequired/OptionalField propertiesDescription
currencyCodeRequiredStringCurrency in which all the rates for shipping carrier selection costs will be calculated
generateLabelOptionalBoolean
True or False
When true, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the labelParameters field of this object. When false, this step is skipped and the system will record what carrier service method would have generated a label for.
includeEvaluatedService MethodsInResponseOptionalBoolean
True or False
When true, a request will expand information on the response to include unselected service methods that made it through filtering.
inlineReturnsLabelOptionalSee Return Labels for guidance on generating a return shipment label when calling this API.Details of the shipment to be returned and its corresponding destination addresses, contact, and fulfillment context details
labelParameters .currencyCodeOptionalStringCurrency in which all the rates for shipping carrier selection costs will be calculated
labelParameters .customLabelEntriesOptionalStringList of formats in which to generate the package label
labelParameters .customLabelEntries .additionalProp1OptionalStringAdditional properties to be associated with the label, beginning with the number 1
labelParameters .includeLabelImages InResponseOptionalBoolean
True or False
If true, the response will include the raw image data of the labels that were requested to be generated by the carrier.
labelParameters .labelFormatsOptionalString enumeration
Supported formats are:

- PDF
- PNG
- ZPL
List of formats in which to generate the package label
labelParameters .manifestOptionalBoolean
True or False
If true, a manifest for the label is generated.
labelParameters .contentDescriptionOptional, but required for return shipmentsStringA short description (under 35 characters) of the package contents being returned that is passed on to the carrier. Required for return shipments only
shipmentParameters .includePackagesArrayOptionalBoolean
True or False
If true, the packages array of details about any package(s) in the shipment is returned in the response.
shipmentParameters .shippedDateTimeOptionalString ($date-time)The timestamp for when a partner will ship the product from their warehouse; the timestamp must be a valid ISO 8601 timestamp.
shipmentParameters .orderedDateTimeOptionalString ($date-time)The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp.
shipmentParameters .deliveredDateTimeOptionalString ($date-time)The timestamp for when the package was delivered; the timestamp must be a valid ISO 8601 timestamp.
shipmentParameters .testModeOptionalBoolean
True or False
If true, a test mode shipment will be created. Carrier selection will consider carriers and service methods in test mode, and label generation will generate a test label.
shipmentParameters .destinationAddress .countryCodeRequiredStringThe ISO 3166-1 country code for the destination address
shipmentParameters .destinationAddress .postalCodeRequiredStringA country-code-appropriate postal code for the destination address
shipmentParameters .destinationAddress .addressTypeRequiredString enumeration
Values are:

- Commercial
- Residential
The type of location for the destination address
shipmentParameters .destinationAddress .companyOptionalStringThe company name for the destination address
shipmentParameters .destinationAddress .nameOptionalStringThe name of the contact for the destination address
shipmentParameters .destinationAddress .emailAddressOptionalStringThe email address of the contact for the destination address
shipmentParameters .destinationAddress .phoneNumberOptionalStringThe phone number of the contact for the destination address
shipmentParameters .destinationAddress .phoneNumber CountryCodeOptionalStringThe phone number country code of the contact for the destination address
shipmentParameters .destinationAddress .cityOptionalStringThe name of the city for the destination address
shipmentParameters .destinationAddress .stateOptionalStringThe 2-letter postal abbreviation of the state for the destination address
shipmentParameters .destinationAddress .street1OptionalStringThe first destination address line
shipmentParameters .destinationAddress .street2OptionalStringThe second destination address line
addressLineComponentsOptionalString
Example:

- streetName: "Fovisste Fuentes Brotantes"
- primaryAddressNumber: "12"
- secondaryAddressNumber: "302"
- district: "Iztacalco"
- neighborhood: "Agrícola Pantitlán"
The address line components for the address, used for some international shipments. This is an optional object that can be included in shipmentParameters to replace the street1, street2, city, and state fields. They may not be included with those fields, or an error will be returned. This optional address object is not included in the example JSON requests for this API call.
shipmentParameters .shipFromAddress .countryCodeRequiredStringThe ISO 3166-1 country code for the origin address
shipmentParameters .shipFromAddress .postalCodeRequiredStringA country-code-appropriate postal code for the origin address
shipmentParameters .shipFromAddress .addressTypeOptionalString
Values are:

- Commercial
- Residential
The type of location for the origin address
shipmentParameters .shipFromAddress .companyOptionalStringThe company name for the origin address
shipmentParameters .shipFromAddress.nameOptionalStringThe name of the contact for the origin address
shipmentParameters .shipFromAddress .emailAddressOptionalStringThe email address of the contact for the origin address
shipmentParameters .shipFromAddress .phoneNumberOptionalStringThe phone number of the contact for the origin address
shipmentParameters .shipFromAddress .phoneNumber CountryCodeOptionalStringThe phone number country code of the contact for the origin address
shipmentParameters .shipFromAddress.cityOptionalStringThe name of the city for the origin address
shipmentParameters .shipFromAddress .stateOptionalStringThe two-letter postal abbreviation of the state for the origin address
shipmentParameters .shipFromAddress .street1OptionalStringThe first address line
shipmentParameters .shipFromAddress .street2OptionalStringThe second address line
shipmentParameters .returnToAddress.nameOptionalStringThe name associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. The returnTo address object is included in the sample call for carrier selection without label generation.
shipmentParameters .returnToAddress .phoneNumberOptionalStringThe phone number of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .phoneNumber CountryCodeOptionalStringThe phone number country code of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .emailAddressOptionalStringThe email address of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .companyOptionalStringThe company of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .street1OptionalStringThe first address line of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .street2OptionalStringThe second address line of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress.cityOptionalStringThe city of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .stateOptionalStringThe 2-letter abbreviation of the location's state where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .countryCodeOptional, but required if including a returnToAddressStringThe ISO 3166-1 country code for the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .postalCodeOptional, but required if including a returnToAddressStringA country code appropriate postal code for the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .returnToAddress .addressTypeOptionalString enumeration
Values:

- Commercial
- Residential
The type of location for the return-to address; this return-to address will override a return-to address configured for an origin or carrier account.
shipmentParameters .orderItemQuantities .productDetailsRequiredString
Examples:
-limited_quantity (or lq)

- ormd (or orm-d)
- perishable
- bound_printed_matter (or bpm)
A list of properties that may affect the shipping of the product
shipmentParameters .orderItemQuantities .productIdRequiredString
Example: RN03947--Z43121
A product ID for the product being checked (ISBN, UPC, etc.)
shipmentParameters .orderItemQuantities .partnerOrderIdOptionalString
Example: myCustomPartnerOrderId123
The unique identifier representing the order
shipmentParameters .orderItemQuantities .deliveryEstimateIdOptionalStringThe delivery estimate ID associated with the product
shipmentParameters .orderItemQuantities .quantityRequiredInteger ($int32)
Example: 3
The number of units of the product
shipmentParameters .orderItemQuantities .shipiumOrderIdOptionalStringIdentification used to represent the group of delivery estimates purchased
shipmentParameters .orderItemQuantities .hazmatOptionalBoolean
True or False
If true, this indicates that the item is hazardous material (hazmat). The default value is false. For hazmat requirements, you can refer to Hazardous Materials.
shipmentParameters .packagingType .packagingMaterialOptionalString enumeration
Values are:

- Box
- Envelope
- Flat_Pack
- Mailing_Tube
- Parcel_Pallet
The type of packaging used to create the package for the shipment
shipmentParameters .packagingType .packagingSizeNameOptionalString
Example: 13x12x10 Box
A custom name for the packaging
shipmentParameters .packagingType .packagingTypeIdOptional, but required if linearDimensions is not providedString
Example: ebd94f8b-d390-4c9c-987f-b88343f5bf45
The packagingTypeId that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, linearDimensions is required.
shipmentParameters .packagingType .packagingWeight .weightOptionalNumber ($float)
Example: 50
The value of the weight
shipmentParameters .packagingType .packagingWeight .weightUnitOptionalString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit in which weight values are provided
shipmentParameters .packagingType .linearDimensions .lengthOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 13
The longest linear dimension (i.e., the longest side of a box or envelope)
shipmentParameters .packagingType .linearDimensions .widthOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 12
The second longest linear dimension (i.e., the second longest side of a box or envelope)
shipmentParameters .packagingType .linearDimensions .heightOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 10
The least long linear dimension (i.e., the shortest side of a box or envelope).
Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.
shipmentParameters .packagingType .linearDimensions .linearUnitOptional, but required if the packagingTypeId is not includedString enumeration
Values are:

- cm (centimeter)
- in (inch)
The unit in which linear dimensions are provided
shipmentParameters .totalWeight.weightOptionalNumber ($float)
Example: 50
The value of the weight
shipmentParameters .totalWeight .weightUnitOptionalString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit in which weight values are provided
shipmentParameters .fulfillmentContextOptionalStringThis is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.
shipmentParameters .fulfillment ContextIdsOptionalStringA collection of fulfillment context IDs or fulfillment context aliases to use in the fulfillment context detail search
shipmentParameters .fulfillmentTypeOptionalString enumeration
Values are:

- At_Large
- Customer
- Hundredweight
- Reship
- Returns
- Unknown
The fulfillment methodology of the shipment
shipmentParameters .partnerShipmentIdOptionalStringAn optional unique identifier that may be used for the shipment
shipmentParameters .purchaseOrder IdentifierOptionalStringString passed to carriers as a purchase order identifier
shipmentParameters .referenceIdentifierOptionalStringString passed to carriers as a reference; this field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name: referenceIdentifier2 (up to 5 reference identifiers)
shipmentParameters .partnerReference IdentifierOptionalStringString provided by your organization that is passed to carriers as a reference
shipmentParameters .partnerReference Identifier2OptionalStringString provided by your organization that is passed to carriers as a reference2
shipmentParameters .carrierProcessingIdOptionalStringCarrier-provided identifier; supplied when it is needed to process the shipment
shipmentParameters .shipOptionOptionalString
Example: Standard
A high-level shipping option shown to or selected by a customer
shipmentParameters .shipmentTagsOptionalStringA collection of free-form tags that may be added to the shipment
shipmentParameters .tenantIdOptionalStringEither the Shipium Tenant ID or the Tenant ID provided by your organization (Partner Provided ID). When present, this is used to indicate the tenant associated with the shipment.
shipmentParameters .businessDaysOf TransitOptionalInteger ($int32)
Example: 3
Indicates the number of business days from the ship time by when the shipment needs to be delivered
shipmentParameters .carrierNameOptionalString
Example: UPS
The carrier that was used for delivering the package
shipmentParameters .carrierTrackingIdOptionalStringThe carrier's tracking identification for the package
shipmentParameters .deliveryNoteOptionalStringString passed to carriers for a delivery note
shipmentParameters .deliverySignature OptionOptionalString enumeration
Values are:

- AdultResidentSignature
- AdultSignature
- None
- ResidentSignature
- Signature
- Unknown
A delivery signature option passed in the API request; the default value is none.
shipmentParameters .deliveryWindow .endWindow.hourOptional, but required when including deliveryWindowString ($byte)The end time hour for the delivery timeframe
shipmentParameters .deliveryWindow .endWindow.minuteOptional, but required when including deliveryWindowString ($byte)The end time minute for the delivery timeframe
shipmentParameters .deliveryWindow .endWindow.nanoOptional, but required when including deliveryWindowInteger ($int32)The end time nano for the delivery timeframe
shipmentParameters .deliveryWindow .endWindow.secondOptional, but required when including deliveryWindowString ($byte)The end time second for the delivery timeframe
shipmentParameters .deliveryWindow .startWindow.hourOptional, but required when including deliveryWindowString ($byte)The start time hour for the delivery timeframe
shipmentParameters .deliveryWindow .startWindow.minuteOptional, but required when including deliveryWindowString ($byte)The start time minute for the delivery timeframe
shipmentParameters .deliveryWindow .startWindow.nanoOptional, but required when including deliveryWindowInteger ($int32)The start time nano for the delivery timeframe
shipmentParameters .deliveryWindow .startWindow.secondOptional, but required when including deliveryWindowString ($byte)The start time second for the delivery timeframe
shipmentParameters .deliveryWindow .timeZoneOptionalStringThe time zone for this delivery window; if no time zone is passed, the time zone will be taken from the destination address.
shipmentParameters .desiredDeliveryDateOptionalString
Example: 2019-10-31T20:00:00Z
The string representation of either an ISO-8601 date or a local date for desired delivery: yyyy-mm-dd. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label.
shipmentParameters .desiredDeliveryDate Options .exactDateDeliveryOptionalBoolean
True or False
If true, this instructs the carrier to deliver the package on the date provided in the desiredDeliveryDate field.
shipmentParameters .desiredDeliveryDate Options .guaranteedDateDeliveryOptionalBoolean
True or False
If true, this indicates that your organization is willing to accept any applicable carrier date certain surcharge to the estimated label cost. Not all carriers support guaranteed date delivery. This restricts carrier selection to service methods that can support guaranteed date delivery .
shipmentParameters .desiredDeliveryDate Options .upgradeCostDeltaMaxOptionalString If set, this is the maximum amount of additional spend that your organization is willing to pay to upgrade a shipment to the desired delivery date (DDD) if the lowest cost carrier service method is unable to safely meet the DDD.
shipmentParameters .desiredDeliveryDate Options.currencyCodeOptionalString enumeration
Ex.: USD
The ISO-4217 currency code of the upgradeCostDeltaMax
shipmentParameters .preferredCarrier DeliveryDateTimeOptionalStringThe string representation of either an ISO-8601 date; the date-time the package is intended to arrive to the customer. This will be passed through to the carrier.
shipmentParameters .saturdayDeliveryOptionalBoolean
True or False
If you pass saturdayDelivery, you can specify whether or not you want Saturday delivery to be an option for this package.

Note: This does not guarantee a Saturday delivery.
shipmentParameters .forceThirdParty BillingOptionalBoolean
True or False
If true, this indicates that third party billing is a requirement for this shipment. No service method should be selected that does not support third party billing.
shipmentParameters .thirdPartyBilling SetIdOptionalStringEither the Shipium third party billing set ID or the third party billing set ID provided by your organization. When present, this is used to indicate the third party billing set that should be used for the billing of the shipment.
shipmentParameters .ignoreUpgradeSpend LimitsOptionalBoolean
True or False
If true, this indicates that the shipment can ignore all of your organization's configured upgrade limits for the potential upgrade required to deliver the shipment by the desired delivery date.

The Carrier and Method Selection & Shipment Label response attributes are defined in the following table.

Response attributeDescription
shipiumShipmentIdThe unique identifier for the shipment
partnerShipmentIdThe optional unique identifier that may be used for the shipment
orderedDateTimeThe timestamp for when the customer placed an order for the product
shippedDateTimeThe timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse
rawDesiredDeliveryDateThe timestamp passed in by you (or your fulfillment partner) for the intended date the package will arrive to the customer
desiredDeliveryDateThe timestamp for the adjusted desired delivery date; this date includes all adjustments that Shipium has made to the requested desired delivery date. Shipium will use this date-time for carrier selection. For desiredDeliveryDateOptions details, see Desired and Guaranteed Delivery Dates.
desiredDeliveryDateLocalThe timestamp for the adjusted desired delivery date, expressed in local time at the destination address; this date includes all adjustments that Shipium has made to the requested desired delivery date. Shipium will use this date-time for carrier selection. For desiredDeliveryDateOptions details, see Desired and Guaranteed Delivery Dates.
preferredCarrierDeliveryDateTimeThe string representation of an ISO-8601 date; the date-time the package is intended to arrive to the customer; this will be passed through to the carrier.
returnsLabelA representation of the return label generated along with the original shipment label; see Return Labels for details.
businessDaysOfTransitIndicates the number of business days from the ship time by when the shipment needs to be delivered
estimatedDeliveryDateThe date and time by when the package is estimated to be delivered to the customer
estimatedDeliveryDateLocalThe date and time by when the package is estimated to be delivered to the customer, expressed in local time at the destination address
destinationTimezoneIdAn identifier for the destination address timezone
originTimezoneIdAn identifier for the origin address timezone
ignoreUpgradeSpendLimitsIndicates that the shipment can ignore all of your pre-configured upgrade limits for the potential upgrade required to deliver the shipment by the desired delivery date
deliveredDateTimeThe timestamp for when the package was delivered to the customer
cancellationDateTimeThe timestamp for when a shipment is canceled; this field will default to null when the shipment is not canceled. A shipment cannot be canceled after a label has been created.
fulfillmentTypeFulfillment methodology of the shipment
carrierNameThe carrier that was used for delivering the package to your customer
carrierTrackingIdThe carrier's tracking identification for the package
packagesA list of packages comprising the shipment; this is for multi-parcel shipments only.
orderItemQuantitiesA list of order items comprising the package; see the request fields in the previous table for the complete list of fields and descriptions.
destinationAddressSee the request fields in the previous table for the complete list of fields and descriptions.
shipOptionA high-level shipping option shown to or selected by a customer
shipFromAddressSee the request fields in the previous table for the complete list of fields and descriptions.
returnToAddressSee the request fields in the previous table for the complete list of fields and descriptions.
injectionAddressThe address of the location where the package is being returned; this is for inclusion of injection sites only. See the request fields in the previous table for either the destinationAddress or shipFromAddress object for the complete list of fields and descriptions.
fulfillmentCenterIdThe Shipium identifier for the fulfillment center where the shipment will depart
fulfillmentContextIdThe Shipium identifier for the fulfillment context where the shipment will depart
partnerFulfillmentContextIdYour organization's alias for the fulfillment context where the shipment will depart
requestFulfillmentContextIdsA collection of fulfillment context IDs or fulfillment context aliases used in the fulfillment context detail search
packagingTypeFields describing the physical properties of the package; see the request fields in the previous table for the complete list of fields and descriptions.
totalWeightThe weight of this type of packaging empty; see the request fields in the previous table for the complete list of fields and descriptions.
shipmentTagsA collection of free-form tags that may be added to this shipment
carrierSelection.statusDefines the result of the carrier selection call; values returned will be success, no_decision, or [uncosted](https://docs.shipium.com/v2.0/docs/labels-without-costing) .
carrierSelection.statusDetailsDetails explaining the result status; pertinent when the status is no_decision
carrierSelection.carrierSelectionIdUnique ID of the carrier selection for later reference
carrierSelection.shipiumShipmentIdThe unique identifier for the shipment
carrierSelection.partnerShipmentIdThe optional unique identifier that may be used for the shipment
carrierSelection.partnerIdYour organization's unique ID
carrierSelection.carrierAccountIdUnique ID of the carrier account selected for shipping
carrierSelection.serviceMethodUrnSpecific version of the service level of the shipping carrier selected
carrierSelection.serviceMethodIdentifierIdentifier of the specific version of the service method of the shipping carrier selected
carrierSelection.carrierThe carrier that was used for delivering the package to your customer
carrierSelection.carrierServiceMethodIdMaps to the unique internal Shipium ID that represents a carrier service method definition; see Supported Carriers for a list of carrier service method IDs.
carrierSelection.serviceMethodNameName of the carrier service method selected during the carrier selection process
carrierSelection.totalCostCost used for carrier selection
carrierSelection.carrierCompareCostExpected cost from the carrier label create
carrierSelection.carrierInvoiceCostExpected cost that carrier will charge at billing time
carrierSelection.operationalCostCarrier invoice cost plus operational costs such as injection line haul
carrierSelection.thirdPartyBillingIndicates if the selected service method will be billed to a third party
carrierSelection.carrierSelectionDateTimeISO-8601 formatted date when the carrier selection decision was made
carrierSelection.injectionDetailsInjection profile and injection site details; see Injection for information about injection sites.
carrierSelection.carrierZoneIdThe carrier zone that is being considered
carrierSelection.evaluatedServiceMethodsAn optional expansion of what carrier service methods were eligible but went unselected
carrierSelection.evaluatedServiceMethods .carrierThe carrier that was used for delivering the package to your customer
carrierSelection.evaluatedServiceMethods .serviceMethodNameName of the carrier service method selected during the carrier selection process
carrierSelection.evaluatedServiceMethods .carrierAccountIdUnique ID of the carrier account selected for shipping
carrierSelection.evaluatedServiceMethods .totalCostCost used for carrier selection
carrierSelection.evaluatedServiceMethods .estimatedDeliveryDateThe estimated date that the shipment will arrive at its destination
carrierSelection.evaluatedServiceMethods .injectionDetailsInjection profile and injection site details; see Injection for information about injection sites.
carrierLabelThis is populated if a label is generated for the carrier and service determined by carrier selection.
carrierLabel.shipiumShipmentIdThe unique identifier for the shipment
carrierLabel.partnerShipmentIdThe optional unique identifier that may be used for the shipment
carrierLabel.carrierSelectionIdUnique ID of the carrier selection for later reference
carrierLabel.shipiumTenantIdThe Shipium-generated tenant ID. When present, this is used to indicate the tenant associated with the shipment.
carrierLabel.partnerTenantIdThe tenant ID provided by your organization. When present, this is used to indicate the tenant associated with the shipment.
carrierLabel.statusDefines the result of the carrier label call; values returned will be success, failure, voided, failover, generated, label_created, manifested, and manifest_failure.
carrierLabel.statusDetailsDetails explaining the result status; pertinent when the status is partial or failed
carrierLabel.effectiveShipDateTimeShipium's calculation for the effective ship date time that a shipment will ship out; this date-time will be used for the carrier label and for limits.
estimatedInjectionDateTimeShipium's calculation for the date-time that a shipment will arrive at the injection site; if present, this date-time will be used for the carrier label.
carrierLabel.labelCreationDateTimeThe timestamp that the label object was created; this is used primarily for explaining future dated shipments.
carrierLabel.serviceMethodIdentifierThe URN used to identify the service method for your organization
carrierLabel.carrierUnique ID of the carrier
carrierLabel.carrierServiceNameName of the carrier for which the label was generated
carrierLabel.serviceMethodNameName of the service method for which the label was generated
carrierLabel.carrierServiceMethodIdMaps to the unique internal Shipium ID that represents a carrier service method definition; see Supported Carriers for a list of carrier service method IDs.
carrierLabel.carrierShipmentIdCarrier's identification for the shipment
carrierLabel.carrierTrackingIdCarrier's tracking identification for the package
carrierLabel.shipiumTrackingIdShipium's tracking identification for the package
carrierLabel.carrierTrackingLinkCarrier's direct tracking link (URL) for the package
carrierLabel.carrierGroupIdCarrier's identification for grouping multiple packages together (for example, Canada Post groups shipments for manifesting)
carrierLabel.packageScannableIdIdentifier provided that matches the scannable barcode on the label
partnerThirdPartyBillingAccountIdThe ID that your organization provided for the third party billing account that was used if the label was billed to a third party
shipiumThirdPartyBillingAccountIdThe Shipium-generated ID of the third party billing account that was used if the label was billed to a third party
thirdPartyBillingForDutiesAndTaxesWhether or not the third party paid the taxes and duties
carrierLabel.carrierLabelCurrencyCodeCurrency code of the price of the label
carrierLabel.carrierLabelPriceCost charged by the carrier for shipping the package at the chosen service level
carrierLabel.billableWeight.weightUnitThe unit in which weight values are provided
carrierLabel.billableWeight.weightThe value of the weight
carrierLabel.documents.labelExpirationDate-time when the label expires and is no longer valid
carrierLabel.documents.labelFormatDefines the format the shipment label was generated in by the carrier
carrierLabel.documents.labelPropertiesMetadata describing the label
carrierLabel.documents.labelProperties .heightTop to bottom measurement of the label
carrierLabel.documents.labelProperties .widthRight to left measurement of the label
carrierLabel.documents.labelProperties .linearUnitsThe linear units representing the label height and label width
carrierLabel.documents.labelProperties.dpiThe dpi (dots per inch) used by the label printer
carrierLabel.documents.labelProperties .labelOrientationThe direction that the label will be printed
carrierLabel.documents.labelProperties .nonZplLabelDimensionsThe dimensions used to print non-ZPL labels, if they need to be different than ZPL dimensions
carrierLabel.documents.labelImage .imageEncodingFormat in which the imageContents field is encoded (e.g., Base64)
carrierLabel.documents.labelImage .imageContentsRaw contents of the shipment label image encoded in Base64; end users will need to decode this data using the format information supplied in the labelInfo field.
carrierLabel.documents.labelUrlThe link to the shipment label file
carrierLabel.documents.carrierTrackingIdThe tracking ID associated with the label
carrierLabel.documents.carrierTrackingLinkThe tracking link associated with the label
carrierLabel.documents .packageReferenceIdentifierThe package reference ID that was passed in by the customer to be associated with the package; this is most frequently used for multi-parcel shipments. This can be used to cross reference international documents and carrier labels.
carrierLabel.documents.packageScannableIdThe package scannable ID associated with the label
carrierLabel.documents.carrierShipmentIdThe carrier shipment ID associated with the label
carrierLabel.internationalDocumentsList of international customs documents generated by the carrier for the shipment; see Customs Info for Shipments for details.
carrierLabel.labelFailoverOccurredWhen true, signifies that label creation failover logic was exercised
carrierLabel.labelFailoverDetailsProvides legacy and detailed debugging information on the label creation attempts when failover logic is used
carrierLabel.trackingInfoDetails of the tracking history and status of the package
carrierLabel.testModeA flag denoting whether the label is a test label
carrierLabel.multiParcelA flag denoting whether the label is for multi-parcel shipments
customsInfoCustoms information about the package for international shipping; see Customs Info for Shipments for details.
saturdayDeliveryIndicates that this shipment is marked for Saturday delivery; does not guarantee delivery on Saturday
deliverySignatureOptionIndicates the delivery signature option selected for the shipment
deliveryWindowA preferred delivery window passed to the carrier as a delivery note
deliveryNoteString passed to carriers for a delivery note
forceThirdPartyBillingIndicates that third party billing is forced for this shipment
requestThirdPartyBillingSetIdEither the Shipium third party billing set ID or the third party billing set ID provided by your organization; when present, this is the third party billing set ID sent on the request.
referenceIdentifierString passed to carriers as a reference
partnerReferenceIdentifierString provided by your organization that was passed to carriers as a reference
partnerReferenceIdentifier2String provided by your organization that was passed to carriers as a reference2
purchaseOrderIdentifierString passed to carriers as a purchase order identifier
carrierProcessingIdCarrier-provided identifier; supplied when it is needed to process the shipment
fulfillmentContextWhen present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.
requestTenantIdEither the Shipium tenant ID or the tenant ID provided by your organization; when present, this is the tenant ID sent on the request.
createdWithVersionThe version used when creating the shipment: v1 or v2.
shipmentPropertiesA list of high-level properties about the shipment
multiParcelIndicates if the shipment is multi-parcel
testModeA flag denoting whether the shipment is a test shipment

Additional options for calling the Carrier and Method Selection & Shipment Label API

Some cases require additional consideration, such as designating a desired delivery date or specifying a shipment as containing hazardous materials. These use cases are briefly listed here and described in more detail in Carrier and Method Selection & Shipment Labels.

  • Shipment timing. Ship options and delivery date specification (ship option, configurable ship option, desired delivery date, guaranteed delivery date, business days of transit)
  • Carrier options. Service method specification and FedEx One Rate (carrier service method allow list, supported carriers)
  • Configured shipment settings. Fulfillment contexts and tenants (origin, carrier contract, tenant)
  • Special processing and accessorial designations. Shipment parameters (delivery signature, Saturday delivery, transportation type, business days of transit, hundredweight)
  • Order and package details. Product specifications, packaging planning, and multiparcel shipments (bound printed matter)
  • Hazardous materials and perishable items. Hazmat, limited quantity, ORMD, lithium-ion, perishable, dry ice
  • Customs specifications. Customs, international, electronic export information, incoterms, US territory, Army Post Office (APO), Fleet Post Office (FPO), Diplomatic Post Office (DPO)
  • Analytics. Evaluated service methods (unselected carrier methods, carrier selection, rate selection)
  • Account billing. Third party billing and labels without costing
  • Carrier failover. Carrier failover is a setting within the Shipium Console that allows you to have a carrier as part of your fulfillment network but with a contingency in place in case there is an issue when calling that carrier for a shipment.

FAQ

Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?

A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: