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 typeAPI endpoint
POSThttps://api.shipium.com/api/v1/shipment/carrierselection/label
🔐

Authentication for API Calls

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

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 tables provide required, conditional, 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.

📘

Character normalization

Text values in address fields may be automatically normalized before being sent to carriers. Accented characters are converted to ASCII equivalents (e.g., é becomes e), and some special characters may be removed depending on carrier requirements. For more information, see Data Handling and Character Normalization.

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.

Top-level request fields

Required fields

Field

Details

currencyCode

Type: String
Example: usd
Description: Currency in which all the rates for shipping carrier selection costs will be calculated

Optional fields

Field

Details

generateLabel

Type: Boolean
Values: true or false
Description: 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.

includeEvaluatedServiceMethodsInResponse

Type: Boolean
Values: true or false
Description: When true, a request will expand information on the response to include unselected service methods that made it through filtering.

includeLineItemsInEvaluatedServiceMethods

Type: Boolean
Values: true or false
Description: When true, a response will include line item information for the returned evaluated service methods, provided that includeEvaluatedServiceMethodsInResponse is also set to true.

inlineReturnsLabel

Type: Object
Description: Details of the shipment to be returned and its corresponding destination addresses, contact, and fulfillment context details. See Return Labels for guidance on generating a return shipment label when calling this API.

ignoreRuleSets

Type: Boolean
Values: true or false
Description: When true, any configured rule sets will be ignored during carrier selection.

labelParameters fields

Conditional fields

Field

Details

labelParameters.contentDescription

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

Optional fields

Field

Details

labelParameters.currencyCode

Type: String
Description: Currency in which all the rates for shipping carrier selection costs will be calculated

labelParameters.customLabelEntries

Type: String
Description: List of formats in which to generate the package label

labelParameters.customLabelEntries .additionalProp1

Type: String
Description: Additional properties to be associated with the label, beginning with the number 1

labelParameters .includeLabelImagesInResponse

Type: Boolean
Values: true or false
Description: If true, the response will include the raw image data of the labels that were requested to be generated by the carrier.

labelParameters.labelFormats

Type: String (enumeration)
Values: pdf, png, zpl
Description: List of formats in which to generate the package label

labelParameters.eligibleForManifest

Type: Boolean
Values: true or false
Description: 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.

shipmentParameters fields

Required fields

Field

Details

shipmentParameters.orderedDateTime

Type: String (date-time)
Description: The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp.

shipmentParameters.destinationAddress .countryCode

Type: String
Description: The ISO 3166-1 country code for the destination address

shipmentParameters.destinationAddress .postalCode

Type: String
Description: A country-code-appropriate postal code for the destination address

shipmentParameters.destinationAddress .addressType

Type: String (enumeration)
Values: commercial, residential Description: The type of location for the destination address

shipmentParameters.destinationAddress .name

Type: String
Description: The name of the contact for the destination address

shipmentParameters.destinationAddress .city

Type: String
Description: The name of the city for the destination address

shipmentParameters.destinationAddress .state

Type: String
Description: The 2-letter postal abbreviation of the state for the destination address

shipmentParameters.destinationAddress .street1

Type: String
Description: The first destination address line

Conditional fields

Field

Details

shipmentParameters.destinationAddress .phoneNumber

Type: String
Condition: May be required for certain carriers and methods
Description: The phone number of the contact for the destination address

shipmentParameters.destinationAddress .phoneNumberCountryCode

Type: String
Condition: May be required for certain carriers and methods
Description: The phone number country code of the contact for the destination address

shipmentParameters.shipFromAddress .countryCode

Type: String
Condition: Required unless the optional originId field is included. If originId is included, shipFromAddress should not be included in your call.
Description: The ISO 3166-1 country code for the origin address

shipmentParameters.shipFromAddress .postalCode

Type: String
Condition: Required unless the optional originId field is included. If originId is included, shipFromAddress should not be included in your call.
Description: A country-code-appropriate postal code for the origin address

shipmentParameters.originId

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

shipmentParameters.returnToAddress .countryCode

Type: String
Condition: Required if including a returnToAddress. This return-to address will override a return-to address configured for an origin or carrier account.
Description: The ISO 3166-1 country code for the address of the location where the package is being returned.

shipmentParameters.returnToAddress .postalCode

Type: String
Condition: Required if including a returnToAddress. This return-to address will override a return-to address configured for an origin or carrier account.
Description: A country code appropriate postal code for the address of the location where the package is being returned

shipmentParameters.orderItemQuantities .productDetails

Type: String
Example: limited_quantity (or lq), ormd (or orm-d), perishable, bound_printed_matter (or bpm)
Condition: Required for international shipments and shipments containing hazardous materials
Description: A list of properties that may affect the shipping of the product

shipmentParameters.orderItemQuantities .productId

Type: String
Example: RN03947--Z43121
Condition: Required for international shipments and shipments containing hazardous materials
Description: A product ID for the product being checked (ISBN, UPC, etc.)

shipmentParameters.orderItemQuantities .quantity

Type: Integer (int32)
Example: 3
Condition: Required for international shipments and shipments containing hazardous materials
Description: The number of units of the product

shipmentParameters.packagingType .packagingMaterial

Type: String (enumeration)
Values: box, envelope, flat_pack, mailing_tube, parcel_pallet
Condition: Required when packagingTypeId is not provided. Optional when packagingTypeId is provided; in this case, the value from the request will be used if the packagingMaterial is not defined in the pre-configured packaging associated with the packagingTypeId.
Description: The material type of the packaging

shipmentParameters.packagingType .packagingTypeId

Type: String
Example: ebd94f8b-d390-4c9c-987f-b88343f5bf45
Condition: 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. When this value is absent, linearDimensions and packagingMaterial are required.
Description: The unique identifier for a pre-configured packaging type defined in the Shipium Console

shipmentParameters.packagingType .linearDimensions.length

Type: Number (float)
Example: 13
Condition: Required when packagingTypeId is not provided. Optional when packagingTypeId is provided; in this case, the value from the request will be used if dimensions are not defined in the pre-configured packaging.
Description: The longest linear dimension (i.e., the longest side of a box or envelope)

shipmentParameters.packagingType .linearDimensions.width

Type: Number (float)
Example: 12
Condition: Required when packagingTypeId is not provided. Optional when packagingTypeId is provided; in this case, the value from the request will be used if dimensions are not defined in the pre-configured packaging.
Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)

shipmentParameters.packagingType .linearDimensions.height

Type: Number (float)
Example: 10
Condition: Required when packagingTypeId is not provided. Optional when packagingTypeId is provided; in this case, the value from the request will be used if dimensions are not defined in the pre-configured packaging.
Description: The least long linear dimension (i.e., the shortest side of a box or envelope)
Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.

shipmentParameters.packagingType .linearDimensions.linearUnit

Type: String (enumeration)
Values: cm (centimeter), in (inch)
Condition: Required when packagingTypeId is not provided. Optional when packagingTypeId is provided; in this case, the value from the request will be used if dimensions are not defined in the pre-configured packaging.
Description: The unit in which linear dimensions are provided

shipmentParameters.deliveryWindow .endWindow.hour

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The end time hour for the delivery timeframe

shipmentParameters.deliveryWindow .endWindow.minute

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The end time minute for the delivery timeframe

shipmentParameters.deliveryWindow .endWindow.nano

Type: Integer (int32)
Condiiton: Required when including deliveryWindow
Description: The end time nano for the delivery timeframe

shipmentParameters.deliveryWindow .endWindow.second

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The end time second for the delivery timeframe

shipmentParameters.deliveryWindow .startWindow.hour

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The start time hour for the delivery timeframe

shipmentParameters.deliveryWindow .startWindow.minute

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The start time minute for the delivery timeframe

shipmentParameters.deliveryWindow .startWindow.nano

Type: Integer (int32)
Condition: Required when including deliveryWindow
Description: The start time nano for the delivery timeframe

shipmentParameters.deliveryWindow .startWindow.second

Type: String (byte)
Condition: Required when including deliveryWindow
Description: The start time second for the delivery timeframe

Optional fields

Field

Details

shipmentParameters.includePackagesArray

Type: Boolean
Values: true or false
Description: If true, the packages array of details about any package(s) in the shipment is returned in the response.

shipmentParameters.shippedDateTime

Type: String (date-time)
Description: 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.deliveredDateTime

Type: String (date-time)
Description: The timestamp for when the package was delivered; the timestamp must be a valid ISO 8601 timestamp.

shipmentParameters.testMode

Type: Boolean
Values: true or false
Description: 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 .company

Type: String
Description: The company name for the destination address

shipmentParameters.destinationAddress .emailAddress

Type: String
Description: The email address of the contact for the destination address

shipmentParameters.destinationAddress .street2

Type: String
Description: The second destination address line

shipmentParameters.destinationAddress .addressLineComponents

Type: Object
Example: streetName: "Fovisste Fuentes Brotantes", primaryAddressNumber: "12", secondaryAddressNumber: "302", district: "Iztacalco", neighborhood: "Agrícola Pantitlán"
Description: 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. Preferred for Mexican addresses. You can find out more about Mexican addresses in Non-U.S. Address Formats.

shipmentParameters.shipFromAddress .addressType

Type: String (enumeration)
Values: commercial, residential
Description: The type of location for the origin address

shipmentParameters.shipFromAddress .company

Type: String
Description: The company name for the origin address

shipmentParameters.shipFromAddress .name

Type: String
Description: The name of the contact for the origin address

shipmentParameters.shipFromAddress .emailAddress

Type: String
Description: The email address of the contact for the origin address

shipmentParameters.shipFromAddress .phoneNumber

Type: String
Description: The phone number of the contact for the origin address

shipmentParameters.shipFromAddress .phoneNumberCountryCode

Type: String
Description: The phone number country code of the contact for the origin address

shipmentParameters.shipFromAddress.city

Type: String
Description: The name of the city for the origin address

shipmentParameters.shipFromAddress.state

Type: String
Description: The 2-letter postal abbreviation of the state for the origin address

shipmentParameters.shipFromAddress .street1

Type: String
Description: The first address line

shipmentParameters.shipFromAddress .street2

Type: String
Description: The second address line

shipmentParameters .useShipFromAddressInRequest

Type: Boolean
Values: true or false
Description: 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 carrier LaserShip, use caution with this flag as the carrier's strict address matching could result in an error.

shipmentParameters.returnToAddress.name

Type: String
Description: 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 returnToAddress object is included in the sample call for carrier selection without label generation.

shipmentParameters.returnToAddress .phoneNumber

Type: String
Description: 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 .phoneNumberCountryCode

Type: String
Description: 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

Type: String
Description: 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

Type: String
Description: 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

Type: String
Description: 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

Type: String
Description: 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

Type: String
Description: 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

Type: String
Description: 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 .addressType

Type: String (enumeration)
Values: commercial, residential
Description: 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 .partnerOrderId

Type: String
Example: myCustomPartnerOrderId123
Description: The unique identifier representing the order

shipmentParameters.orderItemQuantities .deliveryEstimateId

Type: String
Description: The delivery estimate ID associated with the product

shipmentParameters.orderItemQuantities .shipiumOrderId

Type: String
Description: Identification used to represent the group of delivery estimates purchased

shipmentParameters.orderItemQuantities .hazmat

Type: Boolean
Values: true or false
Description: 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 .orderItemReferenceIdentifier

Type: String
Example: someIdentifier
Description: 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

Type: String
Description: The tax code that applies to the given product

shipmentParameters.orderItemQuantities .itemWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce)
Description: The unit in which weight values are provided

shipmentParameters.orderItemQuantities .itemWeight.weight

Type: Number (float)
Example: 50
Description: The value of the weight

shipmentParameters.packagingType .packagingSizeName

Type: String
Example: 13x12x10 box
Description: A custom name for the packaging

shipmentParameters.packagingType .packagingWeight.weight

Type: Number (float)
Example: 50
Description: The value of the weight

shipmentParameters.packagingType .packagingWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce)
Description: The unit in which weight values are provided

shipmentParameters.totalWeight.weight

Type: Number (float)
Example: 50
Description: The value of the weight

shipmentParameters.totalWeight.weightUnit

Type: String (enumeration)
Values: g (gram), kg (kilogram), lb (pound), oz (ounce)
Description: The unit in which weight values are provided

shipmentParameters.fulfillmentContext

Type: String
Description: This is used to limit carrier selection to carrier accounts that contain a matching fulfillment context.

shipmentParameters.fulfillmentContextIds

Type: String
Description: A collection of fulfillment context IDs or fulfillment context aliases to use in the fulfillment context detail search

shipmentParameters.fulfillmentType

Type: String (enumeration)
Values: at_large, customer, hundredweight, reship, returns, unknown
Description: The fulfillment methodology of the shipment

shipmentParameters.partnerShipmentId

Type: String
Description: An optional unique identifier that may be used for the shipment

shipmentParameters.purchaseOrderIdentifier

Type: String
Description: String passed to carriers as a purchase order identifier

shipmentParameters.referenceIdentifier

Type: String
Description: 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 .partnerReferenceIdentifier

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

shipmentParameters .partnerReferenceIdentifier2

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

shipmentParameters.carrierProcessingId

Type: String
Description: Carrier-provided identifier; supplied when it is needed to process the shipment

shipmentParameters.shipOption

Type: String
Example: standard
Description: A high-level shipping option shown to or selected by a customer

shipmentParameters.shipmentTags

Type: String
Description: A collection of free-form tags that may be added to the shipment

shipmentParameters.tenantId

Type: String
Description: 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.businessDaysOfTransit

Type: Integer (int32)
Example: 3
Description: Indicates the number of business days from the ship time by when the shipment needs to be delivered

shipmentParameters.carrierName

Type: String
Example: ups
Description: The carrier that was used for delivering the package

shipmentParameters.carrierTrackingId

Type: String
Description: The carrier's tracking identification for the package

shipmentParameters.deliveryNote

Type: String
Description: String passed to carriers for a delivery note

shipmentParameters.deliverySignatureOption

Type: String (enumeration )
Values: AdultResidentSignature, AdultSignature, None, ResidentSignature, Signature, Unknown
Description: A delivery signature option passed in the API request. The default value is None.

shipmentParameters.deliveryWindow.timeZone

Type: String
Description: 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

Type: String (date-time) Example: 2019-10-31T20:00:00Z
Description: 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.desiredDeliveryDateOptions .guaranteedDateDelivery

Type: Boolean
Values: true or false
Description: 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.desiredDeliveryDateOptions .exactDateDelivery

Type: Boolean
Values: true or false
Description: 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.desiredDeliveryDateOptions .upgradeCostDeltaMax

Type: String
Description: 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.desiredDeliveryDateOptions .currencyCode

Type: String
Description: The ISO 4217 currency code of the upgradeCostDeltaMax

shipmentParameters.desiredDeliveryDateOptions .timeInTransitSetting

Type: String (enumeration)
Values: very_conservative, conservative, standard, aggressive
Description: Including this field in your API call will override any time-in-transit setting configuration, on a per shipment basis.

shipmentParameters .preferredCarrierDeliveryDateTime

Type: String (date-time)
Description: 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

Type: String
Description: 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.forceThirdPartyBilling

Type: Boolean
Values: true or false
Description: 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.thirdPartyBillingSetId

Type: String
Description: 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.thirdPartyBillingAccounts

Type: Array of thirdPartyBillingAccounts objects
Description: 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.ignoreUpgradeSpendLimits

Type: Boolean
Values: true or false
Description: 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.configurationOverrides .maximumAdditionalDaysToHold

Type: Integer
Description: 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 .taxIdentificationNumber

Type: String
Example: 12345
Description: 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.

Response attributes

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 6 days ago

What’s Next