Guides
Start typing to search…

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 type

API endpoint

POST

https://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.

Authenticating for Curl
Open Recipe
👍

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.

📘

Using a partner shipment ID

You can include an optional partnerShipmentId in the shipmentParameters of your request. This unique identifier can be used to reference the shipment in your own systems. The partnerShipmentId will be returned in the response and can be used for tracking and reconciliation purposes. When creating a shipment, if a partnerShipmentId is provided, it can be used in place of the shipiumShipmentId in subsequent API calls that take a shipment identifier as a path parameter.

Each example request in this document includes the optional partnerShipmentId.

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 and an optional tax ID value 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": {
        "partnerShipmentId": "myCustomPartnerShipmentId123",
        "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",
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "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
          }
      }
  ],
  "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,
  "includeLineItemsInEvaluatedServiceMethods": true,
  "shipmentParameters": {
        "partnerShipmentId": "myCustomPartnerShipmentId123",
        "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",
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "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",
                "carrierServiceMethodId": "ups-ground-service-method",
                "serviceMethodName": "UPS Ground - ana",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "base rate",
                    "rate": 1.0,
                    "carrierSurchargeId": "123451239874980",
                    "surchargeType": "base",
                    "lineItemType": "base_rate"
                  }
                  ]
            },
            {
                "carrier": "usps",
                "carrierServiceMethodId": "usps-priority-mail-express-service-method",
                "serviceMethodName": "USPS Priority Mail Express",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "ground residential",
                    "rate": 2.5,
                    "carrierSurchargeId": null,
                    "surchargeType": "residential_ground",
                    "lineItemType": "surcharge"
                  }
                  ]
            },
            {
                "carrier": "ups",
                "carrierServiceMethodId": "ups-surepost-service-method",
                "serviceMethodName": "UPS SurePost - ana",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 6.0,
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "base",
                    "rate": 1.0,
                    "carrierSurchargeId": "0987654321",
                    "surchargeType": "base",
                    "lineItemType": "base_rate"
                  }
                  ]
            },
            {
                "carrier": "fedex",
                "carrierServiceMethodId": "fedex-priority-overnight-service-method",
                "serviceMethodName": "FedEx Priority Overnight",
                "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
                "totalCost": 11.0,
                "estimatedDeliveryDate": "2023-09-09T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "fuel",
                    "rate": 1.3,
                    "carrierSurchargeId": null,
                    "surchargeType": "fuel_air_domestic",
                    "lineItemType": "fuel surcharge"
                  }
                  ]
            },
            {
                "carrier": "usps",
                "carrierServiceMethodId": "usps-priority-mail-service-method",
                "serviceMethodName": "USPS Priority Mail",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-12T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "ground residential",
                    "rate": 2.0,
                    "carrierSurchargeId": null,
                    "surchargeType": "residential_ground",
                    "lineItemType": "surcharge"
                  }
                  ]
            },
            {
                "carrier": "fedex",
                "carrierServiceMethodId": "fedex-home-delivery-service-method",
                "serviceMethodName": "FedEx Home Delivery",
                "carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
                "totalCost": 4.13,
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "ground residential",
                    "rate": 2.0,
                    "carrierSurchargeId": null,
                    "surchargeType": "residential_ground",
                    "lineItemType": "surcharge"
                  }
                  ]
            },
            {
                "carrier": "ups",
                "carrierServiceMethodId": "ups-next-day-air-saver-service-method",
                "serviceMethodName": "UPS Next Day Air Saver",
                "carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-09T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "next day",
                    "rate": 1.8,
                    "carrierSurchargeId": "0987654321",
                    "surchargeType": "delivery_residential_air",
                    "lineItemType": "surcharge"
                  }
                  ]
            },
            {
                "carrier": "usps",
                "carrierServiceMethodId": "usps-parcel-select-service-method",
                "serviceMethodName": "USPS Parcel Select",
                "carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
                "totalCost": 1.0,
                "estimatedDeliveryDate": "2023-09-14T02:00:00Z",
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "regional",
                    "rate": 0.8,
                    "carrierSurchargeId": null,
                    "surchargeType": "remote_delivery_residential_ground",
                    "lineItemType": "surcharge"
                  }
                  ]
            },
            {
                "carrier": "upsmi",
                "carrierServiceMethodId": "upsmi-parcel-select-service-method",
                "serviceMethodName": "UPS Mail Innovations Parcel Select",
                "carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
                "totalCost": 1.0,
                "injectionDetails": {},
                "rateCurrency": "usd",
                "lineItems": [
                  {
                    "name": "fuel",
                    "rate": 1.5,
                    "carrierSurchargeId": "1234567890",
                    "surchargeType": "fuel_ground",
                    "lineItemType": "fuel surcharge"
                  }
                  ]
            }
        ]
    },
    "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. This example also highlights inclusion of the originId field; thus, no ship from address details are included.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
      "currencyCode": "usd",
      "includeLabelImagesInResponse": true,
      "labelFormats": [
          "zpl"
      ],
      "eligibleForManifest": true
  },
  "shipmentParameters": {
        "partnerShipmentId": "myCustomPartnerShipmentId123",
        "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"
        },
        "originId": "my-custom-origin-ID",
        "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",
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "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": "my-custom-origin-ID",
  "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"
      ],
      "eligibleForManifest": true
  },
  "shipmentParameters": {
        "partnerShipmentId": "myCustomPartnerShipmentId123",
        "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",
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "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.

Request field

Required/Optional

Field properties

Description

currencyCode

Required

String

Currency in which all the rates for shipping carrier selection costs will be calculated

generateLabel

Optional

Boolean
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
MethodsInResponse

Optional

Boolean
trueorfalse

When true, a request will expand information on the response to include unselected service methods that made it through filtering.

includeLineItemsIn
  EvaluatedServiceMethods

Optional

Boolean
trueorfalse

When true, a response will include line item information for the returned evaluated service methods, provided that includeEvaluatedServiceMethodsInResponse is also set to true.

inlineReturnsLabel

Optional

See 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

ignoreRuleSets

Optional

Boolean
trueorfalse

When true, any configured rule sets will be ignored during carrier selection.

labelParameters
  .currencyCode

Optional

String

Currency in which all the rates for shipping carrier selection costs will be calculated

labelParameters
  .customLabelEntries

Optional

String

List of formats in which to generate the package label

labelParameters
  .customLabelEntries
  .additionalProp1

Optional

String

Additional properties to be associated with the label, beginning with the number 1

labelParameters
  .includeLabelImages
InResponse

Optional

Boolean
trueorfalse

If true, the response will include the raw image data of the labels that were requested to be generated by the carrier.

labelParameters
  .labelFormats

Optional

String enumeration
Supported formats are:

  • pdf
  • png
  • zpl

List of formats in which to generate the package label

labelParameters
  .eligibleForManifest

Optional

Boolean
trueorfalse

When true, or null, this label will be included in end-of-day and scheduled manifests. False indicates that the label should not be included in any manifests.

labelParameters
  .contentDescription

Optional, but required for return shipments

String

A short description (under 35 characters) of the package contents being returned that is passed on to the carrier. Required for return shipments only

shipmentParameters
  .includePackagesArray

Optional

Boolean
trueorfalse

If true, the packages array of details about any package(s) in the shipment is returned in the response.

shipmentParameters
  .shippedDateTime

Optional

String ($date-time)

The timestamp for when a partner will ship the product from their warehouse; the timestamp must be a valid ISO 8601 timestamp. If not provided, this value defaults to orderedDateTime.

shipmentParameters
  .orderedDateTime

Required

String ($date-time)

The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp.

shipmentParameters
  .deliveredDateTime

Optional

String ($date-time)

The timestamp for when the package was delivered; the timestamp must be a valid ISO 8601 timestamp.

shipmentParameters
  .testMode

Optional

Boolean
trueorfalse

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
  .countryCode

Required

String

The ISO 3166-1 country code for the destination address

shipmentParameters
  .destinationAddress
  .postalCode

Required

String

A country-code-appropriate postal code for the destination address

shipmentParameters
  .destinationAddress
  .addressType

Required

String enumeration
Values are:

  • commercial
  • residential

The type of location for the destination address

shipmentParameters
  .destinationAddress
  .company

Optional

String

The company name for the destination address

shipmentParameters
  .destinationAddress
  .name

Required

String

The name of the contact for the destination address

shipmentParameters
  .destinationAddress
  .emailAddress

Optional

String

The email address of the contact for the destination address

shipmentParameters
  .destinationAddress
  .phoneNumber

Optional, but may be required for certain carriers and methods

String

The phone number of the contact for the destination address

shipmentParameters
  .destinationAddress
  .phoneNumber
CountryCode

Optional, but may be required for certain carriers and methods

String

The phone number country code of the contact for the destination address

shipmentParameters
  .destinationAddress
  .city

Required

String

The name of the city for the destination address

shipmentParameters
  .destinationAddress
  .state

Required

String

The 2-letter postal abbreviation of the state for the destination address

shipmentParameters
  .destinationAddress
  .street1

Required

String

The first destination address line

shipmentParameters
  .destinationAddress
  .street2

Optional

String

The second destination address line

shipmentParameters
 .destinationAddress
 .addressLineComponents

Optional, but
preferred for Mexican addresses

String
Ex.:

  • 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. The street1 and street2 fields should not be included if using addressLineComponents, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. You can find out more about Mexican addresses in Non-U.S. Address Formats.

shipmentParameters
  .shipFromAddress
  .countryCode

Conditional

String

The ISO 3166-1 country code for the origin address; this field is required unless the optional originId field is included. If originId is included, shipFromAddress should not be included in your call.

shipmentParameters
  .shipFromAddress
  .postalCode

Conditional

String

A country-code-appropriate postal code for the origin address; this field is required unless the optional originId field is included. If originId is included, shipFromAddress should not be included in your call.

shipmentParameters
  .shipFromAddress
  .addressType

Optional

String enumeration
Values are:

  • commercial
  • residential

The type of location for the origin address

shipmentParameters
  .shipFromAddress
  .company

Optional

String

The company name for the origin address

shipmentParameters
  .shipFromAddress.name

Optional

String

The name of the contact for the origin address

shipmentParameters
  .shipFromAddress
  .emailAddress

Optional

String

The email address of the contact for the origin address

shipmentParameters
  .shipFromAddress
  .phoneNumber

Optional

String

The phone number of the contact for the origin address

shipmentParameters
  .shipFromAddress
  .phoneNumber
CountryCode

Optional

String

The phone number country code of the contact for the origin address

shipmentParameters
  .shipFromAddress.city

Optional

String

The name of the city for the origin address

shipmentParameters
  .shipFromAddress
  .state

Optional

String

The two-letter postal abbreviation of the state for the origin address

shipmentParameters
  .shipFromAddress
  .street1

Optional

String

The first address line

shipmentParameters
  .shipFromAddress
  .street2

Optional

String

The second address line

shipmentParameters
  .useShipFromAddress
  InRequest

Optional

Boolean
true or false

When true, this optional field overrides the shipper's contact name and address configured for the shipping origin in the Shipium Console, opting to use the shipFromAddress information passed in the API call.
Note: If shipping with carrierLaserShip, use caution with this flag as the carrier's strict address matching could result in an error.

shipmentParameters
  .returnToAddress.name

Optional

String

The 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
  .phoneNumber

Optional

String

The 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
CountryCode

Optional

String

The 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
  .emailAddress

Optional

String

The 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
  .company

Optional

String

The 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
  .street1

Optional

String

The 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
  .street2

Optional

String

The 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.city

Optional

String

The 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
  .state

Optional

String

The 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
  .countryCode

Optional, but required if including a returnToAddress

String

The 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
  .postalCode

Optional, but required if including a returnToAddress

String

A 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
  .addressType

Optional

String 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
  .productDetails

Optional, but required for international shipments and shipments containing hazardous materials

String
Ex.:
-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
  .productId

Optional, but required for international shipments and shipments containing hazardous materials

String
Ex.: RN03947--Z43121

A product ID for the product being checked (ISBN, UPC, etc.)

shipmentParameters
  .orderItemQuantities
  .partnerOrderId

Optional

String
Ex.: myCustomPartnerOrderId123

The unique identifier representing the order

shipmentParameters
  .orderItemQuantities
  .deliveryEstimateId

Optional

String

The delivery estimate ID associated with the product

shipmentParameters
  .orderItemQuantities
  .quantity

Optional, but required for international shipments and shipments containing hazardous materials

Integer ($int32)
Ex.: 3

The number of units of the product

shipmentParameters
  .orderItemQuantities
  .shipiumOrderId

Optional

String

Identification used to represent the group of delivery estimates purchased

shipmentParameters
  .orderItemQuantities
  .hazmat

Optional

Boolean
trueorfalse

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
  .orderItemQuantities
  .orderItemReference
  Identifier

Optional

String
Ex.: someIdentifier

An external identifier that can reference the order item that exists in an external order management system (OMS). This field will be passed to supported carriers.

shipmentParameters
  .orderItemQuantities
  .productTaxCode

Optional

String

The tax code that applies to the given product

shipmentParameters
  .orderItemQuantities
  .itemWeight.weightUnit

Optional

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)

The unit in which weight values are provided

shipmentParameters
  .orderItemQuantities
  .itemWeight.weight

Optional

Number ($float)
Ex.: 50

The value of the weight

shipmentParameters
  .packagingType
  .packagingMaterial

Conditional

String enumeration
Values are:

  • box
  • envelope
  • flat_pack
  • mailing_tube
  • parcel_pallet

The material type of the packaging. REQUIRED whenpackagingTypeId is not provided. OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if the packagingMaterial is not defined in the pre-configured packaging associated with the packagingTypeId.

shipmentParameters
  .packagingType
  .packagingSizeName

Optional

String
Ex.: 13x12x10 box

A custom name for the packaging

shipmentParameters
  .packagingType
  .packagingTypeId

Conditional

String
Ex.: ebd94f8b-d390-4c9c-987f-b88343f5bf45

The unique identifier for a pre-configured packaging type defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID. When this value is present, linearDimensions and packagingMaterial become optional as fallback fields. When this value is absent, linearDimensions and packagingMaterial are required.

shipmentParameters
  .packagingType
  .packagingWeight
  .weight

Optional

Number ($float)
Ex.: 50

The value of the weight

shipmentParameters
  .packagingType
  .packagingWeight
  .weightUnit

Optional

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)

The unit in which weight values are provided

shipmentParameters
  .packagingType
  .linearDimensions
  .length

Conditional

Number ($float)
Ex.: 13

The longest linear dimension (i.e., the longest side of a box or envelope)

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentParameters
  .packagingType
  .linearDimensions
  .width

Conditional

Number ($float)
Ex.: 12

The second longest linear dimension (i.e., the second longest side of a box or envelope)

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentParameters
  .packagingType
  .linearDimensions
  .height

Conditional

Number ($float)
Ex.: 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.

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentParameters
  .packagingType
  .linearDimensions
  .linearUnit

Conditional

String enumeration
Values are:

  • cm (centimeter)
  • in (inch)

The unit in which linear dimensions are provided

  • *REQUIRED when packagingTypeId is not provided.** OPTIONAL when packagingTypeId is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
shipmentParameters
  .totalWeight.weight

Optional

Number ($float)
Ex.: 50

The value of the weight

shipmentParameters
  .totalWeight
  .weightUnit

Optional

String enumeration
Values are:

  • g (gram)
  • kg (kilogram)
  • lb (pound)
  • oz (ounce)

The unit in which weight values are provided

shipmentParameters
  .fulfillmentContext

Optional

String

This is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.

shipmentParameters
  .fulfillment
ContextIds

Optional

String

A collection of fulfillment context IDs or fulfillment context aliases to use in the fulfillment context detail search

shipmentParameters
  .originId

Conditional

String

Either the Shipium-generated origin ID or your organization's own origin ID, used to identify the origin where the shipment will be processed; if you opt to include an originId in your call, the shipFromAddress should not be included.

shipmentParameters
  .fulfillmentType

Optional

String enumeration
Values are:

  • at_large
  • customer
  • hundredweight
  • reship
  • returns
  • unknown

The fulfillment methodology of the shipment

shipmentParameters
  .partnerShipmentId

Optional

String

An optional unique identifier that may be used for the shipment

shipmentParameters
  .purchaseOrder
Identifier

Optional

String

String passed to carriers as a purchase order identifier

shipmentParameters
  .referenceIdentifier

Optional

String

String 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
Identifier

Optional

String

String provided by your organization that is passed to carriers as a reference

shipmentParameters
  .partnerReference
Identifier2

Optional

String

String provided by your organization that is passed to carriers as a reference2

shipmentParameters
  .carrierProcessingId

Optional

String

Carrier-provided identifier; supplied when it is needed to process the shipment

shipmentParameters
  .shipOption

Optional

String
Ex.: standard

A high-level shipping option shown to or selected by a customer

shipmentParameters
  .shipmentTags

Optional

String

A collection of free-form tags that may be added to the shipment

shipmentParameters
  .tenantId

Optional

String

Either 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
Transit

Optional

Integer ($int32)
Ex.: 3

Indicates the number of business days from the ship time by when the shipment needs to be delivered

shipmentParameters
  .carrierName

Optional

String
Ex.: UPS

The carrier that was used for delivering the package

shipmentParameters
  .carrierTrackingId

Optional

String

The carrier's tracking identification for the package

shipmentParameters
  .deliveryNote

Optional

String

String passed to carriers for a delivery note

shipmentParameters
  .deliverySignature
Option

Optional

String 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.hour

Optional, but required when including deliveryWindow

String ($byte)

The end time hour for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .endWindow.minute

Optional, but required when including deliveryWindow

String ($byte)

The end time minute for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .endWindow.nano

Optional, but required when including deliveryWindow

Integer ($int32)

The end time nano for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .endWindow.second

Optional, but required when including deliveryWindow

String ($byte)

The end time second for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .startWindow.hour

Optional, but required when including deliveryWindow

String ($byte)

The start time hour for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .startWindow.minute

Optional, but required when including deliveryWindow

String ($byte)

The start time minute for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .startWindow.nano

Optional, but required when including deliveryWindow

Integer ($int32)

The start time nano for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .startWindow.second

Optional, but required when including deliveryWindow

String ($byte)

The start time second for the delivery timeframe

shipmentParameters
  .deliveryWindow
  .timeZone

Optional

String

The time zone for this delivery window; if no time zone is passed, the time zone will be taken from the destination address.

shipmentParameters
  .desiredDeliveryDate

Optional

String
Ex.: 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
  .guaranteedDateDelivery

Optional

Boolean
trueorfalse

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
  .exactDateDelivery

Optional

Boolean
trueorfalse

If true, this instructs the carrier to deliver the package on the date provided in the desiredDeliveryDate field. Desired, Exact, & Guaranteed Delivery Dates provides details on exact date delivery.

shipmentParameters
  .desiredDeliveryDate
Options
  .upgradeCostDeltaMax

Optional

String

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.currencyCode

Optional

String

The ISO-4217 currency code of the upgradeCostDeltaMax

shipmentParameters
  .desiredDeliveryDate
  Options.timeInTransit
  Setting

Optional

String enumeration
Values are:

  • very_conservative
  • conservative
  • standard
  • aggressive

Including this field in your API call will override any time-in-transit setting configuration, on a per shipment basis.

shipmentParameters
  .preferredCarrier
DeliveryDateTime

Optional

Boolean
trueorfalse

The 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
  .saturdayDelivery

Optional

String

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
Billing

Optional

Boolean
trueorfalse

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
SetId

Optional

String

Either 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
  .thirdPartyBilling
Accounts

Optional

Array of thirdPartyBillingAccounts objects

Include third party billing account information in calls to Shipium's APIs without configuring your third party billing account in the Shipium Console. You can find out how to do so in Bill a Third Party.

shipmentParameters
  .ignoreUpgradeSpend
Limits

Optional

Boolean
trueorfalse

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.

shipmentParameters
  .configuration
  Overrides.maximum
  AdditionalDaysToHold

Optional

Integer

To optimize shipping costs, you can leverage the Maximum Additional Days to Hold feature. This optional setting allows your organization to instruct the system to consider holding a shipment at your fulfillment center for a specified number of extra days, beyond the originally requested ship date, if doing so enables the selection of a more economical carrier service. You can find more information about this feature in Additional Days to Hold a Shipment.

shipmentParameters
  .customsInfo
  .taxIdentification
  Number

Optional

String
Ex.: 12345

This optional value can be passed to override any tax ID number (also known as an employer identification number, or EIN) that is configured in your network settings (e.g., at the tenant level for a fulfillment context), on a per-shipment basis. This value also can be passed in multiParcelShipmentParameters.customsInfo for a multi-parcel shipment. You can find more information in Tax Identification Number .

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, Exact, & 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, Exact, & 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; included in the response when either a desired delivery date or business days of transit value is included in the call request.
estimatedDeliveryDateLocalThe date and time by when the package is estimated to be delivered to the customer, expressed in local time at the destination address; included in the response when either a desired delivery date or business days of transit value is included in the call request.
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 .carrierServiceMethodIdThe carrier service method ID for the service method
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.
carrierSelection.evaluatedServiceMethods .rateCurrencyThe currency of the rate for the selected carrier and service method, which also applies to lineItems
carrierSelection.evaluatedServiceMethods .lineItems.nameThe name of the rate modification
carrierSelection.evaluatedServiceMethods .lineItems.carrierSurchargeIdThe identifier for the carrier surcharge
carrierSelection.evaluatedServiceMethods .lineItems.surchargeTypeThe type of surcharge for this item; a null value will result for non-surcharges.
carrierSelection.evaluatedServiceMethods .lineItems.lineItemTypeThe type of rate line item for this rate modification
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 (pre-configured vs. ad-hoc packaging definition), and multi-parcel shipments
  • 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:

Updated 19 days ago

What’s Next