Carrier and Method Selection & Shipment Label API
Determine carrier service method and print shipping labels all in one call with Shipium's Carrier and Method Selection & Shipment Label API.
Get started
To use the Carrier and Method Selection & Shipment Label API, you can follow the instructions on this page, which also include guidance for additional options when calling the API. Information about determining carrier service method and generating shipment labels within the Shipium platform can be found in the Carrier and Service Method & Shipment Labels, Carrier and Method Selection, and Shipment Labels documentation.
Determine carrier service method with or without shipping labels with the Carrier and Method Selection & Shipment Label API
The Shipium Carrier and Method Selection & Shipment Label API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Carrier and Method Selection & Shipment Label API calls is included in the table below.
| API type | API endpoint |
|---|---|
| POST | https://api.shipium.com/api/v1/shipment/carrierselection/label |
Authentication for API Calls
In the cURL example on this page, the environment variable
AUTHSTRINGis 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
testModeflag to err on the side of caution – remove it to make production calls.
The required and optional fields for calling the Carrier and Method Selection & Shipment Label API are included in the Request and Response Fields for API Calls section of this document.
Determine carrier and ship method without retrieving a label
Example cURL call
This example shows a request to determine the carrier service method for a shipment without retrieving a shipment label:
curl --request POST
--url https://api.shipium.com/api/v1/shipment/carrierselection/label
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
Example request body
The following minimum fields should be included in your JSON request. This example request body also includes an optional return-to address object that is included in the shipmentParameters.
Note that the generateLabel value is set to "false" to not create a label with the request and the includePackagesArray value is set to "true" to include the package information in the response.
{
"currencyCode": "usd",
"generateLabel": "false",
"shipmentParameters": {
"includePackagesArray": "true",
"shippedDateTime": "2023-09-06T18:30:55.558Z",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"testMode": "true",
"destinationAddress": {
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
"city": "Albuquerque",
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"shipFromAddress": {
"countryCode": "US",
"postalCode": "17901",
"city": "Pottsville",
"state": "PA",
"street1": "401 N. Centre St.",
},
"returnToAddress": {
"name": "Rod Runner",
"phoneNumber": "865-433-9999",
"phoneNumberCountryCode": "+2",
"emailAddress": "[email protected]",
"company": "ACME",
"street1": "456 Main St.",
"street2": "Suite 8",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
},
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2
}
],
"packagingType": {
"packagingMaterial": "box",
"packagingWeight": {
"weight": "13",
"weightUnit": "oz"
},
"linearDimensions": {
"length": "15",
"width": "10",
"height": "5",
"linearUnit": "in"
}
},
"totalWeight": {
"weight": "13",
"weightUnit": "oz"
},
}
}
Example response body
{
"shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"shippedDateTime": "2023-09-06T18:30:55.558Z",
"ignoreUpgradeSpendLimits": false,
"fulfillmentType": "customer",
"packages": [
{
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2,
"productDetails": [],
"hazmat": false
}
],
"packagingType": {
"packagingMaterial": "box",
"linearDimensions": {
"linearUnit": "in",
"length": 15.0,
"width": 10.0,
"height": 5.0
},
"packagingWeight": {
"weightUnit": "oz",
"weight": 13.0
}
},
"totalWeight": {
"weightUnit": "oz",
"weight": 13.0
}
}
],
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2,
"productDetails": [],
"hazmat": false
}
],
"destinationAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"shipFromAddress": {
"name": "Ro Drunner",
"phoneNumber": "5555555555",
"emailAddress": "[email protected]",
"company": "Sell It",
"street1": "401 N. Centre St.",
"city": "Pottsville",
"state": "PA",
"countryCode": "US",
"postalCode": "17901"
},
"returnToAddress": {
"name": "Rod Runner",
"phoneNumber": "865-433-9999",
"phoneNumberCountryCode": "+2",
"emailAddress": "[email protected]",
"company": "ACME",
"street1": "456 Main St.",
"street2": "Suite 8",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
"requestFulfillmentContextIds": [],
"originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
"packagingType": {
"packagingMaterial": "box",
"linearDimensions": {
"linearUnit": "in",
"length": 15.0,
"width": 10.0,
"height": 5.0
},
"packagingWeight": {
"weightUnit": "oz",
"weight": 13.0
}
},
"totalWeight": {
"weightUnit": "oz",
"weight": 13.0
},
"shipmentTags": [],
"carrierSelection": {
"status": "success",
"statusDetails": "success",
"carrierSelectionId": "911b488c-c620-4663-a554-bf9628e7ff43",
"shipiumShipmentId": "3185ae04-d465-408a-9ae2-a98c7499e6bc",
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
"carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:dXBzbWktcGFyY2VsLXNlbGVjdC1zZXJ2aWNlLW1ldGhvZDo6NDNjYTI3ZDctZmUzNi00YjI1LTk4MDAtYTdmMTE2ZDIyMTQxOjdiODExNzA0LTlhMTYtNGQzYi1iODQ5LTQzYzcyNzk0MTVhYzpmZTFlMjg1Mi1kNTBiLTQ5OGQtOGIxMC05MGJiMWM5ODFjZTA6dXBzbWk6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "upsmi",
"carrierServiceMethodId": "upsmi-parcel-select-service-method",
"serviceMethodName": "UPS Mail Innovations Parcel Select",
"totalCost": 1.0,
"carrierCompareCost": 1.0,
"carrierInvoiceCost": 1.0,
"operationalCost": 1.0,
"thirdPartyBilling": false,
"carrierSelectionDateTime": "2024-03-25T19:44:22.232Z"
},
"saturdayDelivery": false,
"deliverySignatureOption": "None",
"forceThirdPartyBilling": false,
"createdWithVersion": "v2",
"multiParcel": false,
"testMode": true
}
Determine carrier and ship method without retrieving a label, with tenants
Example cURL call
This example shows a request to determine the carrier service method for a shipment without retrieving a shipment label, and associating a tenant with the shipment:
curl --request POST
--url https://api.shipium.com/api/v1/shipment/carrierselection/label
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
Example request body
The following minimum fields should be included in your JSON request. Note the inclusion of tenantId in the shipment parameters.
{
"currencyCode": "usd",
"generateLabel": "false",
"includeEvaluatedServiceMethodsInResponse": "true",
"shipmentParameters": {
"tenantId" : "3b343401-7a52-4709-a053-ab35ec9ecd5b",
"shippedDateTime": "2023-09-06T18:30:55.558Z",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"testMode": true,
"destinationAddress": {
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
"city": "Albuquerque",
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"shipFromAddress": {
"countryCode": "US",
"postalCode": "17901",
"city": "Pottsville",
"state": "PA",
"street1": "401 N. Centre St."
},
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2
}
],
"packagingType": {
"packagingMaterial": "box",
"packagingWeight": {
"weight": "13",
"weightUnit": "oz"
},
"linearDimensions": {
"length": "15",
"width": "10",
"height": "5",
"linearUnit": "in"
}
},
"totalWeight": {
"weight": "13",
"weightUnit": "oz"
},
}
}
Example response body
{
"shipiumShipmentId": "afca15f1-4084-49a4-9792-1c78f641ac5e",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"shippedDateTime": "2023-09-06T18:30:55.558Z",
"rawDesiredDeliveryDate": "2024-04-03",
"desiredDeliveryDate": "2024-04-04T05:59:59.999Z",
"desiredDeliveryDateLocal": "2024-04-03T23:59:59.999",
"estimatedDeliveryDate": "2023-09-12T02:00:00Z",
"estimatedDeliveryDateLocal": "2024-09-11T20:00:00",
"destinationTimezoneId": "America/Albuquerque",
"originTimezoneId": "America/Pottsville",
"ignoreUpgradeSpendLimits": false,
"fulfillmentType": "customer",
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2,
"productDetails": [],
"shipiumOrderId": "123",
"hazmat": false
},
{
"productId": "7G-100-0756",
"quantity": 1,
"productDetails": [],
"hazmat": false
}
],
"destinationAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"shipFromAddress": {
"name": "Ro Drunner",
"phoneNumber": "5555555555",
"emailAddress": "[email protected]",
"company": "Sell It",
"street1": "401 N. Centre St.",
"city": "Pottsville",
"state": "PA",
"countryCode": "US",
"postalCode": "17901"
},
"requestFulfillmentContextIds": [],
"originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
"packagingType": {
"packagingMaterial": "box",
"linearDimensions": {
"linearUnit": "in",
"length": 15.0,
"width": 10.0,
"height": 5.0
},
"packagingWeight": {
"weightUnit": "oz",
"weight": 13.0
}
},
"totalWeight": {
"weightUnit": "oz",
"weight": 13.0
},
"shipmentTags": [
"test"
],
"carrierSelection": {
"status": "success",
"statusDetails": "success",
"carrierSelectionId": "1fb236b0-91a2-4aba-a8e2-f2431a70c8e5",
"shipiumShipmentId": "afca15f1-4084-49a4-9792-1c78f641ac5e",
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
"carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:dXBzLWdyb3VuZC1zZXJ2aWNlLW1ldGhvZDo6NDExNmI3MmQtZjJmOC00YTBiLWE4ZGItN2VmN2E0ZGE5MWIxOjhjZDNlOTU4LWE1ZTktNGRkYS1hMmRhLTcyN2M1ZDJjMGQxMzoxMDg1NGMwNC01NTVjLTRmMDktOWEwZi1lZDA1NDJjNzUwNjk6dXBzOjVhMWVhNzI4LTRiYTItNGNjNi04OTJjLTFmMTIyZjM1MDc3NTo6",
"carrier": "ups",
"carrierServiceMethodId": "ups-ground-service-method",
"serviceMethodName": "UPS Ground -ana",
"totalCost": 1.0,
"carrierCompareCost": 1.0,
"carrierInvoiceCost": 1.0,
"operationalCost": 1.0,
"thirdPartyBilling": false,
"carrierSelectionDateTime": "2024-04-03T14:42:20.434Z",
"carrierZoneId": "ups-zone-7",
"evaluatedServiceMethods": [
{
"carrier": "ups",
"serviceMethodName": "UPS Ground -ana",
"carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
"totalCost": 1.0,
"estimatedDeliveryDate": "2023-09-12T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "usps",
"serviceMethodName": "USPS Priority Mail Express",
"carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
"totalCost": 1.0,
"estimatedDeliveryDate": "2023-09-12T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "ups",
"serviceMethodName": "UPS SurePost - ana",
"carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
"totalCost": 6.0,
"injectionDetails": {}
},
{
"carrier": "fedex",
"serviceMethodName": "FedEx Priority Overnight",
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
"totalCost": 11.0,
"estimatedDeliveryDate": "2023-09-09T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "usps",
"serviceMethodName": "USPS Priority Mail",
"carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
"totalCost": 1.0,
"estimatedDeliveryDate": "2023-09-12T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "fedex",
"serviceMethodName": "FedEx Home Delivery",
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
"totalCost": 4.13,
"injectionDetails": {}
},
{
"carrier": "ups",
"serviceMethodName": "UPS Next Day Air Saver",
"carrierAccountId": "8cd3e958-a5e9-4dda-a2da-727c5d2c0d13",
"totalCost": 1.0,
"estimatedDeliveryDate": "2023-09-09T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "usps",
"serviceMethodName": "USPS Parcel Select",
"carrierAccountId": "5a4b52e4-bcf9-4cb4-928d-84d3ca838e43",
"totalCost": 1.0,
"estimatedDeliveryDate": "2023-09-14T02:00:00Z",
"injectionDetails": {}
},
{
"carrier": "upsmi",
"serviceMethodName": "UPS Mail Innovations Parcel Select",
"carrierAccountId": "7b811704-9a16-4d3b-b849-43c7279415ac",
"totalCost": 1.0,
"injectionDetails": {}
}
]
},
"saturdayDelivery": false,
"deliverySignatureOption": "None",
"forceThirdPartyBilling": false,
"createdWithVersion": "v2",
"multiParcel": false,
"testMode": true
}
Determine carrier and ship method and generate a standard shipment label
Example cURL call
This example shows a request to determine the carrier service method for a shipment and also retrieve a shipment label:
curl --request POST
--url https://api.shipium.com/api/v1/shipment/carrierselection/label
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
Example request body
The following minimum fields should be included in your JSON request. For this example, a value of true is being passed for the generateLabel, includeLabelImageInResponse, and manifest fields. Shipment manifests are required by some carriers. You can read more in Manifest Shipments.
{
"currencyCode": "usd",
"generateLabel": true,
"labelParameters": {
"currencyCode": "usd",
"includeLabelImagesInResponse": true,
"labelFormats": [
"zpl"
],
"manifest": true
},
"shipmentParameters": {
"shippedDateTime": "2024-04-06T18:30:55.558Z",
"orderedDateTime": "2024-04-03T18:30:55.558Z",
"testMode": true,
"destinationAddress": {
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
"city": "Albuquerque",
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"shipFromAddress": {
"countryCode": "US",
"postalCode": "17901",
"city": "Pottsville",
"state": "PA",
"street1": "401 N. Centre St."
},
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2
}
],
"packagingType": {
"packagingMaterial": "box",
"packagingWeight": {
"weight": "13",
"weightUnit": "oz"
},
"linearDimensions": {
"length": "15",
"width": "10",
"height": "5",
"linearUnit": "in"
}
},
"totalWeight": {
"weight": "13",
"weightUnit": "oz"
},
}
}
Example response body
{
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"shippedDateTime": "2024-04-09T14:39:27.511Z",
"ignoreUpgradeSpendLimits": false,
"fulfillmentType": "customer",
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2,
"productDetails": [],
"hazmat": false
}
],
"destinationAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"shipFromAddress": {
"name": "Ro Drunner",
"phoneNumber": "6612475319",
"emailAddress": "[email protected]",
"company": "Sell It",
"street1": "401 N. Centre St.",
"city": "Pottsville",
"state": "PA",
"countryCode": "US",
"postalCode": "17901"
},
"fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
"requestFulfillmentContextIds": [],
"originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
"packagingType": {
"packagingMaterial": "box",
"linearDimensions": {
"linearUnit": "in",
"length": 15.0,
"width": 10.0,
"height": 5.0
},
"packagingWeight": {
"weightUnit": "oz",
"weight": 13.0
}
},
"totalWeight": {
"weightUnit": "oz",
"weight": 13.0
},
"shipmentTags": [],
"carrierSelection": {
"status": "success",
"statusDetails": "success",
"carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceMethodId": "fedex-express-saver-service-method",
"serviceMethodName": "FedEx Express Saver",
"totalCost": 3.25,
"carrierCompareCost": 3.25,
"carrierInvoiceCost": 3.25,
"operationalCost": 3.25,
"thirdPartyBilling": false,
"carrierSelectionDateTime": "2024-04-09T14:39:27.773Z",
"carrierZoneId": "fedex-express-zone-7"
},
"carrierLabel": {
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
"shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
"status": "success",
"statusDetails": "success",
"effectiveShipDateTime": "2024-04-10T04:00:00Z",
"labelCreationDateTime": "2024-04-09T14:39:30.192Z",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceName": "FedEx Corporation Account - 2",
"serviceMethodName": "FedEx Express Saver",
"carrierServiceMethodId": "fedex-express-saver-service-method",
"carrierShipmentId": "794622496766",
"carrierTrackingId": "794622496766",
"shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622496766",
"carrierLabelCurrencyCode": "USD",
"carrierLabelPrice": 3.25,
"billableWeight": {
"weightUnit": "lb",
"weight": 6.0
},
"documents": [
{
"labelExpiration": "2024-04-23T14:39:30.177778742Z",
"labelFormat": "zpl",
"labelProperties": {
"height": 4.0,
"width": 6.0,
"linearUnits": "in",
"dpi": 203,
"labelOrientation": "rotate_0"
},
"labelImage": {
"imageEncoding": "base64",
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI0OTY3NjYwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNDk2NzY2XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
},
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/5191f46a-7d43-4d8f-a859-f9193938b30f/carrierSelection/777584eb-0f08-44d6-98d0-df8bc1eba1c1/label/198edb20-1076-42d8-8723-830dd6f27ef4/zpl",
}
],
"internationalDocuments": [],
"labelFailoverOccurred": false,
"testMode": true,
"multiParcel": false
},
"saturdayDelivery": false,
"deliverySignatureOption": "None",
"forceThirdPartyBilling": false,
"createdWithVersion": "v2",
"multiParcel": false,
"testMode": true
}
Determine carrier and ship method and generate a standard shipment label, with tenants
Example cURL call
This example shows a request to determine the carrier service method for a shipment and also retrieve a shipment label, with the inclusion of a tenant:
curl --request POST
--url https://api.shipium.com/api/v1/shipment/carrierselection/label
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
Example request body
The following minimum fields should be included in your JSON request. For this example, a value of true is being passed for the generateLabel, includeLabelImageInResponse, and manifest fields. Shipment manifests are required by some carriers. You can read more in Manifest Shipments.
{
"currencyCode": "usd",
"generateLabel": true,
"labelParameters": {
"currencyCode": "usd",
"includeLabelImagesInResponse": true,
"labelFormats": [
"zpl"
],
"manifest": true
},
"shipmentParameters": {
"tenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
"shippedDateTime": "2024-04-06T18:30:55.558Z",
"orderedDateTime": "2024-04-03T18:30:55.558Z",
"testMode": true,
"destinationAddress": {
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
"city": "Albuquerque",
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"shipFromAddress": {
"countryCode": "US",
"postalCode": "17901",
"city": "Pottsville",
"state": "PA",
"street1": "401 N. Centre St."
},
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2
}
],
"packagingType": {
"packagingMaterial": "box",
"packagingWeight": {
"weight": "13",
"weightUnit": "oz"
},
"linearDimensions": {
"length": "15",
"width": "10",
"height": "5",
"linearUnit": "in"
}
},
"totalWeight": {
"weight": "13",
"weightUnit": "oz"
},
}
}
Example response body
{
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"shippedDateTime": "2024-04-09T14:39:27.511Z",
"ignoreUpgradeSpendLimits": false,
"fulfillmentType": "customer",
"orderItemQuantities": [
{
"productId": "ET-14-4000",
"quantity": 2,
"productDetails": [],
"hazmat": false
}
],
"destinationAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"shipFromAddress": {
"name": "Ro Drunner",
"phoneNumber": "5555555555",
"emailAddress": "[email protected]",
"company": "Sell It",
"street1": "401 N. Centre St.",
"city": "Pottsville",
"state": "PA",
"countryCode": "US",
"postalCode": "17901"
},
"fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
"requestFulfillmentContextIds": [],
"originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
"packagingType": {
"packagingMaterial": "box",
"linearDimensions": {
"linearUnit": "in",
"length": 15.0,
"width": 10.0,
"height": 5.0
},
"packagingWeight": {
"weightUnit": "oz",
"weight": 13.0
}
},
"totalWeight": {
"weightUnit": "oz",
"weight": 13.0
},
"shipmentTags": [],
"carrierSelection": {
"status": "success",
"statusDetails": "success",
"carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceMethodId": "fedex-express-saver-service-method",
"serviceMethodName": "FedEx Express Saver",
"totalCost": 3.25,
"carrierCompareCost": 3.25,
"carrierInvoiceCost": 3.25,
"operationalCost": 3.25,
"thirdPartyBilling": false,
"carrierSelectionDateTime": "2024-04-09T14:39:27.773Z",
"carrierZoneId": "fedex-express-zone-7"
},
"carrierLabel": {
"shipiumShipmentId": "5191f46a-7d43-4d8f-a859-f9193938b30f",
"carrierSelectionId": "777584eb-0f08-44d6-98d0-df8bc1eba1c1",
"shipiumTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
"partnerTenantId": "tenantid_123",
"shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
"status": "success",
"statusDetails": "success",
"effectiveShipDateTime": "2024-04-10T04:00:00Z",
"labelCreationDateTime": "2024-04-09T14:39:30.192Z",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceName": "FedEx Corporation Account - 2",
"serviceMethodName": "FedEx Express Saver",
"carrierServiceMethodId": "fedex-express-saver-service-method",
"carrierShipmentId": "794622496766",
"carrierTrackingId": "794622496766",
"shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622496766",
"carrierLabelCurrencyCode": "USD",
"carrierLabelPrice": 3.25,
"billableWeight": {
"weightUnit": "lb",
"weight": 6.0
},
"documents": [
{
"labelExpiration": "2024-04-23T14:39:30.177778742Z",
"labelFormat": "zpl",
"labelProperties": {
"height": 4.0,
"width": 6.0,
"linearUnits": "in",
"dpi": 203,
"labelOrientation": "rotate_0"
},
"labelImage": {
"imageEncoding": "base64",
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI0OTY3NjYwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNDk2NzY2XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
},
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/5191f46a-7d43-4d8f-a859-f9193938b30f/carrierSelection/777584eb-0f08-44d6-98d0-df8bc1eba1c1/label/198edb20-1076-42d8-8723-830dd6f27ef4/zpl",
}
],
"internationalDocuments": [],
"labelFailoverOccurred": false,
"testMode": true,
"multiParcel": false
},
"saturdayDelivery": false,
"deliverySignatureOption": "None",
"forceThirdPartyBilling": false,
"createdWithVersion": "v2",
"requestTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
"shipiumTenantId": "3b343401-7a52-4709-a053-ab35ecs8cadb",
"partnerTenantId": "tenantid_123",
"multiParcel": false,
"testMode": true
}
Retrieve a previously generated label
The endpoint for retrieving a label is provided below.
Path
GET https://shiptime-service.shipium.com/api/v1/deliveryexperience/shipment/carrierSelection/label/{shipiumLabelId}?includeLabelImagesInResponse=true
Required path element: shipiumLabelId
Required parameter: includeLabelImageinResponse
Example request body
The request body is empty for this call.
Example response body
{
"shipiumShipmentId": "17a793fc-f90c-421c-8af5-ae8f51084270",
"carrierSelectionId": "e8a561fd-e70b-4950-82c7-4489e3c2a2b2",
"shipiumTenantId": "3b343401-7a52-4709-a053-ab35ec9ecd5b",
"partnerTenantId": "tenantid_123",
"shipiumLabelId": "d9067cb5-99d4-4252-aa26-41b82b81950b",
"status": "success",
"statusDetails": "success",
"effectiveShipDateTime": "2024-04-10T04:00:00Z",
"labelCreationDateTime": "2024-04-09T14:49:20.585Z",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceName": "FedEx Corporation Account - 2",
"serviceMethodName": "FedEx Express Saver",
"carrierServiceMethodId": "fedex-express-saver-service-method",
"carrierShipmentId": "794622502879",
"carrierTrackingId": "794622502879",
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622502879",
"carrierLabelCurrencyCode": "USD",
"carrierLabelPrice": 61.3,
"billableWeight": {
"weightUnit": "lb",
"weight": 6.0
},
"documents": [
{
"labelExpiration": "2024-04-23T14:49:20.573369416Z",
"labelFormat": "zpl",
"labelProperties": {
"height": 4.0,
"width": 6.0,
"linearUnits": "in",
"dpi": 203,
"labelOrientation": "rotate_0"
},
"labelImage": {
"imageEncoding": "base64",
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMzAxXkdCNzUzLDIsMl5GUwpeRk8xMiw1NjdeR0I3NzcsMiwyXkZTCl5GTzQ2NCwxNzBeR0IyLDEyOSwyXkZTCl5GTzI4LDkwOV5BME4sMjQsMjReRldOXkZIXkZEVFJLI15GUwpeRk8yOCw5NjdeQTBOLDI3LDMyXkZXTl5GSF5GRF5GUwpeRk8xMzYsODc5XkEwTiwyNywzNl5GV05eRkheRkReRlMKXkZPMzIsMTcyXkFkTiwwLDBeRldOXkZIXkZET1JJR0lOIElEOlJER0EgXkZTCl5GTzIyNCwxNzJeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8zMiwxOTBeQWROLDAsMF5GV05eRkheRkRNQUMgQlJPV05eRlMKXkZPMzIsMjA4XkFkTiwwLDBeRldOXkZIXkZEU0FLUyBPRkYgNVRIXkZTCl5GTzMyLDIyNl5BZE4sMCwwXkZXTl5GSF5GRDI1IEtFWVNUT05FIEJMVkReRlMKXkZPMzIsMjQ0XkFkTiwwLDBeRldOXkZIXkZEXkZTCl5GTzMyLDI2Ml5BZE4sMCwwXkZXTl5GSF5GRFBPVFRTVklMTEUsIFBBIDE3OTAxXkZTCl5GTzMyLDI4MF5BZE4sMCwwXkZXTl5GSF5GRFVOSVRFRCBTVEFURVMgVVNeRlMKXkZPNDc4LDIwOF5BZE4sMCwwXkZXTl5GSF5GRENBRDogMDAwMDAwMC9XU1hJMzYwMF5GUwpeRk8xNSwzMTNeQTBOLDIxLDIxXkZXTl5GSF5GRFRPXkZTCl5GTzYwLDMxMV5BME4sMzgsMzheRldOXkZIXkZEV0lMRSBFLiBDT1lPVEVeRlMKXkZPNjAsMzUzXkEwTiwzOCwzOF5GV05eRkheRkReRlMKXkZPNjAsMzk1XkEwTiwzOCwzOF5GV05eRkheRkQxMjMgTUFJTiBTVC5eRlMKXkZPNjAsNDM3XkEwTiwzOCwzOF5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzYwLDQ3OV5BME4sNDMsNDBeRldOXkZIXkZEQUxCVVFVRVJRVUUgTk0gODcxMjFeRlMKXkZPMzUsNTIxXkEwTiwyMSwyMV5GV05eRkheRkQoODg4KSA1NTUtMTIzNF5GUwpeRk82NzcsNjczXkdCMTA0LDEwLDEwXkZTCl5GTzY3Nyw2ODNeR0IxMCwxMTIsMTBeRlMKXkZPNzcxLDY4M15HQjEwLDExMiwxMF5GUwpeRk82NzcsNzk1XkdCMTA0LDEwLDEwXkZTCl5GTzY1Miw2MTFeQTBOLDQzLDU4XkZXTl5GSF5GREZlZEV4XkZTCl5GTzcwOCw2NTBeQTBOLDE5LDI2XkZXTl5GSF5GREV4cHJlc3NeRlMKXkZPNjk3LDY5MV5BME4sMTI4LDEzN15GV05eRkheRkRFXkZTCl5GTzIxLDU3OF5CWTIsM15CQ04sMjUsTixOLE5eRldOXkZENzEyMyBNQUlOIFNULl5GUwpeRk8yMSw2MTFeQlkyLDJeQjdOLDEwLDUsMTReRkheRldOXkZIXkZEWyk+XzFFMDFfMUQwMjg3MTIxXzFEODQwXzFEMjBfMUQ3OTQ2MjI1MDI4NzkwMjAxXzFERkRFXzFENTEwMDg4MDAwXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRDEyMyBNYWluIFN0Ll8xREFsYnVxdWVycXVlXzFETk1fMURXaWxlIEUuIENveW90ZV8xRTA2XzFEMTBaRUQwMDhfMUQxMlo4ODg1NTUxMjM0XzFEMTRaU3VpdGUgNDJfMUQxNVoxMTQwNzUzNTFfMUQyMFpfMUNfMUQzMVoxMDAxOTIxMzcxNTUwMDA4NzEyMTAwNzk0NjIyNTAyODc5XzFEMzJaMDJfMUQzNFowMV8xRDM5WlJER0FfMURfMUUwOV8xREZEWF8xRHpfMUQ4XzFENS1fMDgwPV8xRF83RkBfMUVfMDReRlMKXkZPNDc4LDI2Ml5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzEyLDg1Nl5HQjc3NywyLDJeRlMKXkZPNDk0LDEwNTJeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83OTEsMjgyXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o0LzVEODAvOUFFM15GUwpeRk85NSw5MTNeQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NjJeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEIE1PTiAtIDE1IEFQUiA1OjAwUF5GUwpeRk8zMDksOTE0XkEwTiw1MSwzOF5GV05eRkheRkI0OTAsLCxSLF5GRCAgICAgIEVYUFJFU1MgU0FWRVJeRlMKXkZPNDEzLDk2Nl5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDA4XkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODcxMjFeRlMKXkZPNTc0LDEwNjheQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEIE5NLVVTXkZTCl5GTzY5NSwxMDUyXkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GREFCUV5GUwpeRk8zOSwxMDk0XkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPNzUsMTE1NV5CWTMsMl5CQ04sMjAwLE4sTixOLE5eRldOXkZEPjsxMDAxOTIxMzcxNTUwMDA4NzEyMTAwMDAwMDAwMDAwMDAwXkZTCl5GTzEzNSwxMjE1XkEwTiwxMjgsMTM3XkZXTl5GSF5GRFNBTVBMRV5GUwpeRk8yOCwxMDA0XkEwTiwxMDcsOTZeRldOXkZIXkZEUFMgT05NQSBeRlMKXkZPNzkwLDY4NV5BME4sMTMsMTheRldCXkZIXkZESjI0MjAyNDA0MDQwMXV2XkZTCl5GTzQ3OCwxNzJeQWROLDAsMF5GV05eRkheRkRTSElQIERBVEU6IDEwQVBSMjReRlMKXkZPNDc4LDE5MF5BZE4sMCwwXkZXTl5GSF5GREFDVFdHVDogMC44MSBMQl5GUwpeRk80NzgsMjI2XkFkTiwwLDBeRldOXkZIXkZERElNUzogMTV4MTB4NSBJTl5GUwpeRk8zMjgsNTI2XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogXkZTCl5GTzM4LDU0MF5BYk4sMTEsN15GV05eRkheRkRJTlY6IF5GUwpeRk8zOCw1NTReQWJOLDExLDdeRldOXkZIXkZEUE86IF5GUwpeRk80MjgsNTU0XkFiTiwxMSw3XkZXTl5GSF5GRERFUFQ6IF5GUwpeRk8yNSw5MzBeR0I1OCwxLDFeRlMKXkZPMjUsOTMwXkdCMSwyNiwxXkZTCl5GTzgzLDkzMF5HQjEsMjYsMV5GUwpeRk8yNSw5NTZeR0I1OCwxLDFeRlMKXkZPMzEsOTM2XkFkTiwwLDBeRldOXkZIXkZEMDIwMV5GUwpeUFExCl5YWgo="
},
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/17a793fc-f90c-421c-8af5-ae8f51084270/carrierSelection/e8a561fd-e70b-4950-82c7-4489e3c2a2b2/label/d9067cb5-99d4-4252-aa26-41b82b81950b/zpl",
}
],
"internationalDocuments": [],
"labelFailoverOccurred": false,
"testMode": true,
"multiParcel": false
}
Request and response fields for API calls
The following table provides required and optional fields for calling the Carrier and Method Selection & Shipment Label API. However, the API is flexible to suit multiple use cases, and not all specialty fields are defined in this document. You can find additional support in the Carrier and Method Selection & Label API Reference and in the linked pages in this description.
In general, shipmentParameters are included for determining carrier service method, and labelParameters are included for generating shipment labels. Multi-parcel shipments require inclusion of multiParcelShipmentParameters in place of shipmentParameters.
International shipments must include customsInfo parameters in either shipmentParameters or multiParcelShipmentParameters. You can find the customsInfo parameters to include in the Customs Info for Shipments document. Additionally, you may need to declare some items as hazardous material, which has its own requirements.
If your organization utilizes injection sites in your network, you can also include injectionParameters by passing an injectionProfileId or injectionSiteId.
If you're interested in running simulations, you'll need to include simulationParameters.
| Request field | Required/Optional | Field properties | Description |
|---|---|---|---|
currencyCode | Required | String | Currency in which all the rates for shipping carrier selection costs will be calculated |
generateLabel | Optional | BooleanTrue or False | When true, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the labelParameters field of this object. When false, this step is skipped and the system will record what carrier service method would have generated a label for. |
includeEvaluatedService MethodsInResponse | Optional | BooleanTrue or False | When true, a request will expand information on the response to include unselected service methods that made it through filtering. |
inlineReturnsLabel | Optional | See Return Labels for guidance on generating a return shipment label when calling this API. | Details of the shipment to be returned and its corresponding destination addresses, contact, and fulfillment context details |
labelParameters .currencyCode | Optional | String | Currency in which all the rates for shipping carrier selection costs will be calculated |
labelParameters .customLabelEntries | Optional | String | List of formats in which to generate the package label |
labelParameters .customLabelEntries .additionalProp1 | Optional | String | Additional properties to be associated with the label, beginning with the number 1 |
labelParameters .includeLabelImages InResponse | Optional | BooleanTrue or False | If true, the response will include the raw image data of the labels that were requested to be generated by the carrier. |
labelParameters .labelFormats | Optional | String enumeration Supported formats are: - PDF- PNG- ZPL | List of formats in which to generate the package label |
labelParameters .manifest | Optional | BooleanTrue or False | If true, a manifest for the label is generated. |
labelParameters .contentDescription | Optional, but required for return shipments | String | A short description (under 35 characters) of the package contents being returned that is passed on to the carrier. Required for return shipments only |
shipmentParameters .includePackagesArray | Optional | BooleanTrue or False | If true, the packages array of details about any package(s) in the shipment is returned in the response. |
shipmentParameters .shippedDateTime | Optional | String ($date-time) | The timestamp for when a partner shipped the product from their warehouse; the timestamp must be a valid ISO 8601 timestamp. |
shipmentParameters .orderedDateTime | Optional | String ($date-time) | The timestamp for when the customer placed the order for this product; the timestamp must be a valid ISO 8601 timestamp. |
shipmentParameters .deliveredDateTime | Optional | String ($date-time) | The timestamp for when the package was delivered; the timestamp must be a valid ISO 8601 timestamp. |
shipmentParameters .testMode | Optional | BooleanTrue or False | If true, a test mode shipment will be created. Carrier selection will consider carriers and service methods in test mode, and label generation will generate a test label. |
shipmentParameters .destinationAddress .countryCode | Required | String | The ISO 3166-1 country code for the destination address |
shipmentParameters .destinationAddress .postalCode | Required | String | A country-code-appropriate postal code for the destination address |
shipmentParameters .destinationAddress .addressType | Required | String enumeration Values are: - Commercial- Residential | The type of location for the destination address |
shipmentParameters .destinationAddress .company | Optional | String | The company name for the destination address |
shipmentParameters .destinationAddress .name | Optional | String | The name of the contact for the destination address |
shipmentParameters .destinationAddress .emailAddress | Optional | String | The email address of the contact for the destination address |
shipmentParameters .destinationAddress .phoneNumber | Optional | String | The phone number of the contact for the destination address |
shipmentParameters .destinationAddress .phoneNumber CountryCode | Optional | String | The phone number country code of the contact for the destination address |
shipmentParameters .destinationAddress .city | Optional | String | The name of the city for the destination address |
shipmentParameters .destinationAddress .state | Optional | String | The 2-letter postal abbreviation of the state for the destination address |
shipmentParameters .destinationAddress .street1 | Optional | String | The first destination address line |
shipmentParameters .destinationAddress .street2 | Optional | String | The second destination address line |
addressLineComponents | Optional | String Example: - streetName: "Fovisste Fuentes Brotantes"- primaryAddressNumber: "12"- secondaryAddressNumber: "302"- district: "Iztacalco"- neighborhood: "Agrícola Pantitlán" | The address line components for the address, used for some international shipments. This is an optional object that can be included in shipmentParameters to replace the street1, street2, city, and state fields. They may not be included with those fields, or an error will be returned. This optional address object is not included in the example JSON requests for this API call. |
shipmentParameters .shipFromAddress .countryCode | Required | String | The ISO 3166-1 country code for the origin address |
shipmentParameters .shipFromAddress .postalCode | Required | String | A country-code-appropriate postal code for the origin address |
shipmentParameters .shipFromAddress .addressType | Optional | String Values are: - Commercial- Residential | The type of location for the origin address |
shipmentParameters .shipFromAddress .company | Optional | String | The company name for the origin address |
shipmentParameters .shipFromAddress.name | Optional | String | The name of the contact for the origin address |
shipmentParameters .shipFromAddress .emailAddress | Optional | String | The email address of the contact for the origin address |
shipmentParameters .shipFromAddress .phoneNumber | Optional | String | The phone number of the contact for the origin address |
shipmentParameters .shipFromAddress .phoneNumber CountryCode | Optional | String | The phone number country code of the contact for the origin address |
shipmentParameters .shipFromAddress.city | Optional | String | The name of the city for the origin address |
shipmentParameters .shipFromAddress .state | Optional | String | The two-letter postal abbreviation of the state for the origin address |
shipmentParameters .shipFromAddress .street1 | Optional | String | The first address line |
shipmentParameters .shipFromAddress .street2 | Optional | String | The second address line |
shipmentParameters .returnToAddress.name | Optional | String | The name associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. The returnTo address object is included in the sample call for carrier selection without label generation. |
shipmentParameters .returnToAddress .phoneNumber | Optional | String | The phone number of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .phoneNumber CountryCode | Optional | String | The phone number country code of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .emailAddress | Optional | String | The email address of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .company | Optional | String | The company of the contact associated with the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .street1 | Optional | String | The first address line of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .street2 | Optional | String | The second address line of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress.city | Optional | String | The city of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .state | Optional | String | The 2-letter abbreviation of the location's state where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .countryCode | Optional, but required if including a returnToAddress | String | The ISO 3166-1 country code for the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .postalCode | Optional, but required if including a returnToAddress | String | A country code appropriate postal code for the address of the location where the package is being returned; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .returnToAddress .addressType | Optional | String enumeration Values: - Commercial- Residential | The type of location for the return-to address; this return-to address will override a return-to address configured for an origin or carrier account. |
shipmentParameters .orderItemQuantities .productDetails | Required | String Examples: - limited_quantity (or lq)- ormd (or orm-d)- perishable- bound_printed_matter (or bpm) | A list of properties that may affect the shipping of the product |
shipmentParameters .orderItemQuantities .productId | Required | String Example: RN03947--Z43121 | A product ID for the product being checked (ISBN, UPC, etc.) |
shipmentParameters .orderItemQuantities .partnerOrderId | Optional | String Example: myCustomPartnerOrderId123 | The unique identifier representing the order |
shipmentParameters .orderItemQuantities .deliveryEstimateId | Optional | String | The delivery estimate ID associated with the product |
shipmentParameters .orderItemQuantities .quantity | Required | Integer ($int32) Example: 3 | The number of units of the product |
shipmentParameters .orderItemQuantities .shipiumOrderId | Optional | String | Identification used to represent the group of delivery estimates purchased |
shipmentParameters .orderItemQuantities .hazmat | Optional | BooleanTrue or False | If true, this indicates that the item is hazardous material (hazmat). The default value is false. For hazmat requirements, you can refer to Hazardous Materials. |
shipmentParameters .packagingType .packagingMaterial | Optional | String enumeration Values are: - Box- Envelope- Flat_Pack- Mailing_Tube- Parcel_Pallet | The type of packaging used to create the package for the shipment |
shipmentParameters .packagingType .packagingSizeName | Optional | String Example: 13x12x10 Box | A custom name for the packaging |
shipmentParameters .packagingType .packagingTypeId | Optional, but required if linearDimensions is not provided | String Example: ebd94f8b-d390-4c9c-987f-b88343f5bf45 | The packagingTypeId that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, linearDimensions is required. |
shipmentParameters .packagingType .packagingWeight .weight | Optional | Number ($float) Example: 50 | The value of the weight |
shipmentParameters .packagingType .packagingWeight .weightUnit | Optional | String enumeration Values are: - g (gram)- kg (kilogram)- lb (pound)- oz (ounce) | The unit in which weight values are provided |
shipmentParameters .packagingType .linearDimensions .length | Optional, but required if the packagingTypeId is not included | Number ($float) Example: 13 | The longest linear dimension (i.e., the longest side of a box or envelope) |
shipmentParameters .packagingType .linearDimensions .width | Optional, but required if the packagingTypeId is not included | Number ($float) Example: 12 | The second longest linear dimension (i.e., the second longest side of a box or envelope) |
shipmentParameters .packagingType .linearDimensions .height | Optional, but required if the packagingTypeId is not included | Number ($float) Example: 10 | The least long linear dimension (i.e., the shortest side of a box or envelope). Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. |
shipmentParameters .packagingType .linearDimensions .linearUnit | Optional, but required if the packagingTypeId is not included | String enumeration Values are: - cm (centimeter)- in (inch) | The unit in which linear dimensions are provided |
shipmentParameters .totalWeight.weight | Optional | Number ($float) Example: 50 | The value of the weight |
shipmentParameters .totalWeight .weightUnit | Optional | String enumeration Values are: - g (gram)- kg (kilogram)- lb (pound)- oz (ounce) | The unit in which weight values are provided |
shipmentParameters .fulfillmentContext | Optional | String | This is used to limit carrier selection to carrier accounts that contain a matching fulfillment context. |
shipmentParameters .fulfillment ContextIds | Optional | String | A collection of fulfillment context IDs or fulfillment context aliases to use in the fulfillment context detail search |
shipmentParameters .fulfillmentType | Optional | String enumeration Values are: - At_Large- Customer- Hundredweight- Reship- Returns- Unknown | The fulfillment methodology of the shipment |
shipmentParameters .partnerShipmentId | Optional | String | An optional unique identifier that may be used for the shipment |
shipmentParameters .purchaseOrder Identifier | Optional | String | String passed to carriers as a purchase order identifier |
shipmentParameters .referenceIdentifier | Optional | String | String passed to carriers as a reference; this field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name: referenceIdentifier2 (up to 5 reference identifiers) |
shipmentParameters .partnerReference Identifier | Optional | String | String provided by your organization that is passed to carriers as a reference |
shipmentParameters .partnerReference Identifier2 | Optional | String | String provided by your organization that is passed to carriers as a reference2 |
shipmentParameters .carrierProcessingId | Optional | String | Carrier-provided identifier; supplied when it is needed to process the shipment |
shipmentParameters .shipOption | Optional | String Example: Standard | A high-level shipping option shown to or selected by a customer |
shipmentParameters .shipmentTags | Optional | String | A collection of free-form tags that may be added to the shipment |
shipmentParameters .tenantId | Optional | String | Either the Shipium Tenant ID or the Tenant ID provided by your organization (Partner Provided ID). When present, this is used to indicate the tenant associated with the shipment. |
shipmentParameters .businessDaysOf Transit | Optional | Integer ($int32) Example: 3 | Indicates the number of business days from the ship time by when the shipment needs to be delivered |
shipmentParameters .carrierName | Optional | String Example: UPS | The carrier that was used for delivering the package |
shipmentParameters .carrierTrackingId | Optional | String | The carrier's tracking identification for the package |
shipmentParameters .deliveryNote | Optional | String | String passed to carriers for a delivery note |
shipmentParameters .deliverySignature Option | Optional | String enumeration Values are: - AdultResidentSignature- AdultSignature- None- ResidentSignature- Signature- Unknown | A delivery signature option passed in the API request; the default value is none. |
shipmentParameters .deliveryWindow .endWindow.hour | Optional, but required when including deliveryWindow | String ($byte) | The end time hour for the delivery timeframe |
shipmentParameters .deliveryWindow .endWindow.minute | Optional, but required when including deliveryWindow | String ($byte) | The end time minute for the delivery timeframe |
shipmentParameters .deliveryWindow .endWindow.nano | Optional, but required when including deliveryWindow | Integer ($int32) | The end time nano for the delivery timeframe |
shipmentParameters .deliveryWindow .endWindow.second | Optional, but required when including deliveryWindow | String ($byte) | The end time second for the delivery timeframe |
shipmentParameters .deliveryWindow .startWindow.hour | Optional, but required when including deliveryWindow | String ($byte) | The start time hour for the delivery timeframe |
shipmentParameters .deliveryWindow .startWindow.minute | Optional, but required when including deliveryWindow | String ($byte) | The start time minute for the delivery timeframe |
shipmentParameters .deliveryWindow .startWindow.nano | Optional, but required when including deliveryWindow | Integer ($int32) | The start time nano for the delivery timeframe |
shipmentParameters .deliveryWindow .startWindow.second | Optional, but required when including deliveryWindow | String ($byte) | The start time second for the delivery timeframe |
shipmentParameters .deliveryWindow .timeZone | Optional | String | The time zone for this delivery window; if no time zone is passed, the time zone will be taken from the destination address. |
shipmentParameters .desiredDeliveryDate | Optional | String Example: 2019-10-31T20:00:00Z | The string representation of either an ISO-8601 date or a local date for desired delivery: yyyy-mm-dd. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. |
shipmentParameters .desiredDeliveryDate Options .exactDateDelivery | Optional | BooleanTrue or False | If true, this instructs the carrier to deliver the package on the date provided in the desiredDeliveryDate field. |
shipmentParameters .desiredDeliveryDate Options .guaranteedDateDelivery | Optional | BooleanTrue or False | If true, this indicates that your organization is willing to accept any applicable carrier date certain surcharge to the estimated label cost. Not all carriers support guaranteed date delivery. This restricts carrier selection to service methods that can support guaranteed date delivery . |
shipmentParameters .desiredDeliveryDate Options .upgradeCostDeltaMax | Optional | String | If set, this is the maximum amount of additional spend that your organization is willing to pay to upgrade a shipment to the desired delivery date (DDD) if the lowest cost carrier service method is unable to safely meet the DDD. |
shipmentParameters .desiredDeliveryDate Options.currencyCode | Optional | String enumeration Ex.: USD | The ISO-4217 currency code of the upgradeCostDeltaMax |
shipmentParameters .preferredCarrier DeliveryDateTime | Optional | String | The string representation of either an ISO-8601 date; the date-time the package is intended to arrive to the customer. This will be passed through to the carrier. |
shipmentParameters .saturdayDelivery | Optional | BooleanTrue or False | If you pass saturdayDelivery, you can specify whether or not you want Saturday delivery to be an option for this package.Note: This does not guarantee a Saturday delivery. |
shipmentParameters .forceThirdParty Billing | Optional | BooleanTrue or False | If true, this indicates that third party billing is a requirement for this shipment. No service method should be selected that does not support third party billing. |
shipmentParameters .thirdPartyBilling SetId | Optional | String | Either the Shipium third party billing set ID or the third party billing set ID provided by your organization. When present, this is used to indicate the third party billing set that should be used for the billing of the shipment. |
shipmentParameters .ignoreUpgradeSpend Limits | Optional | BooleanTrue or False | If true, this indicates that the shipment can ignore all of your organization's configured upgrade limits for the potential upgrade required to deliver the shipment by the desired delivery date. |
The Carrier and Method Selection & Shipment Label response attributes are defined in the following table.
| Response attribute | Description |
|---|---|
shipiumShipmentId | The unique identifier for the shipment |
partnerShipmentId | The optional unique identifier that may be used for the shipment |
orderedDateTime | The timestamp for when the customer placed an order for the product |
shippedDateTime | The timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse |
rawDesiredDeliveryDate | The timestamp passed in by you (or your fulfillment partner) for the intended date the package will arrive to the customer |
desiredDeliveryDate | The timestamp for the adjusted desired delivery date; this date includes all adjustments that Shipium has made to the requested desired delivery date. Shipium will use this date-time for carrier selection. For desiredDeliveryDateOptions details, see Desired and Guaranteed Delivery Dates. |
desiredDeliveryDateLocal | The timestamp for the adjusted desired delivery date, expressed in local time at the destination address; this date includes all adjustments that Shipium has made to the requested desired delivery date. Shipium will use this date-time for carrier selection. For desiredDeliveryDateOptions details, see Desired and Guaranteed Delivery Dates. |
preferredCarrierDeliveryDateTime | The 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. |
returnsLabel | A representation of the return label generated along with the original shipment label; see Return Labels for details. |
businessDaysOfTransit | Indicates the number of business days from the ship time by when the shipment needs to be delivered |
estimatedDeliveryDate | The date and time by when the package is estimated to be delivered to the customer |
estimatedDeliveryDateLocal | The date and time by when the package is estimated to be delivered to the customer, expressed in local time at the destination address |
destinationTimezoneId | An identifier for the destination address timezone |
originTimezoneId | An identifier for the origin address timezone |
ignoreUpgradeSpendLimits | Indicates 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 |
deliveredDateTime | The timestamp for when the package was delivered to the customer |
cancellationDateTime | The 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. |
fulfillmentType | Fulfillment methodology of the shipment |
carrierName | The carrier that was used for delivering the package to your customer |
carrierTrackingId | The carrier's tracking identification for the package |
packages | A list of packages comprising the shipment; this is for multi-parcel shipments only. |
orderItemQuantities | A list of order items comprising the package; see the request fields in the previous table for the complete list of fields and descriptions. |
destinationAddress | See the request fields in the previous table for the complete list of fields and descriptions. |
shipOption | A high-level shipping option shown to or selected by a customer |
shipFromAddress | See the request fields in the previous table for the complete list of fields and descriptions. |
returnToAddress | See the request fields in the previous table for the complete list of fields and descriptions. |
injectionAddress | The 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. |
fulfillmentCenterId | The Shipium identifier for the fulfillment center where the shipment will depart |
fulfillmentContextId | The Shipium identifier for the fulfillment context where the shipment will depart |
partnerFulfillmentContextId | Your organization's alias for the fulfillment context where the shipment will depart |
requestFulfillmentContextIds | A collection of fulfillment context IDs or fulfillment context aliases used in the fulfillment context detail search |
packagingType | Fields describing the physical properties of the package; see the request fields in the previous table for the complete list of fields and descriptions. |
totalWeight | The weight of this type of packaging empty; see the request fields in the previous table for the complete list of fields and descriptions. |
shipmentTags | A collection of free-form tags that may be added to this shipment |
carrierSelection.status | Defines 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.statusDetails | Details explaining the result status; pertinent when the status is no_decision |
carrierSelection.carrierSelectionId | Unique ID of the carrier selection for later reference |
carrierSelection.shipiumShipmentId | The unique identifier for the shipment |
carrierSelection.partnerShipmentId | The optional unique identifier that may be used for the shipment |
carrierSelection.partnerId | Your organization's unique ID |
carrierSelection.carrierAccountId | Unique ID of the carrier account selected for shipping |
carrierSelection.serviceMethodUrn | Specific version of the service level of the shipping carrier selected |
carrierSelection.serviceMethodIdentifier | Identifier of the specific version of the service method of the shipping carrier selected |
carrierSelection.carrier | The carrier that was used for delivering the package to your customer |
carrierSelection.carrierServiceMethodId | Maps 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.serviceMethodName | Name of the carrier service method selected during the carrier selection process |
carrierSelection.totalCost | Cost used for carrier selection |
carrierSelection.carrierCompareCost | Expected cost from the carrier label create |
carrierSelection.carrierInvoiceCost | Expected cost that carrier will charge at billing time |
carrierSelection.operationalCost | Carrier invoice cost plus operational costs such as injection line haul |
carrierSelection.thirdPartyBilling | Indicates if the selected service method will be billed to a third party |
carrierSelection.carrierSelectionDateTime | ISO-8601 formatted date when the carrier selection decision was made |
carrierSelection.injectionDetails | Injection profile and injection site details; see Injection for information about injection sites. |
carrierSelection.carrierZoneId | The carrier zone that is being considered |
carrierSelection.evaluatedServiceMethods | An optional expansion of what carrier service methods were eligible but went unselected |
carrierSelection.evaluatedServiceMethods .carrier | The carrier that was used for delivering the package to your customer |
carrierSelection.evaluatedServiceMethods .serviceMethodName | Name of the carrier service method selected during the carrier selection process |
carrierSelection.evaluatedServiceMethods .carrierAccountId | Unique ID of the carrier account selected for shipping |
carrierSelection.evaluatedServiceMethods .totalCost | Cost used for carrier selection |
carrierSelection.evaluatedServiceMethods .estimatedDeliveryDate | The estimated date that the shipment will arrive at its destination |
carrierSelection.evaluatedServiceMethods .injectionDetails | Injection profile and injection site details; see Injection for information about injection sites. |
carrierLabel | This is populated if a label is generated for the carrier and service determined by carrier selection. |
carrierLabel.shipiumShipmentId | The unique identifier for the shipment |
carrierLabel.partnerShipmentId | The optional unique identifier that may be used for the shipment |
carrierLabel.carrierSelectionId | Unique ID of the carrier selection for later reference |
carrierLabel.shipiumTenantId | The Shipium-generated tenant ID. When present, this is used to indicate the tenant associated with the shipment. |
carrierLabel.partnerTenantId | The tenant ID provided by your organization. When present, this is used to indicate the tenant associated with the shipment. |
carrierLabel.status | Defines the result of the carrier label call; values returned will be success, failure, voided, failover, generated, label_created, manifested, and manifest_failure. |
carrierLabel.statusDetails | Details explaining the result status; pertinent when the status is partial or failed |
carrierLabel.effectiveShipDateTime | Shipium'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. |
estimatedInjectionDateTime | Shipium'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.labelCreationDateTime | The timestamp that the label object was created; this is used primarily for explaining future dated shipments. |
carrierLabel.serviceMethodIdentifier | The URN used to identify the service method for your organization |
carrierLabel.carrier | Unique ID of the carrier |
carrierLabel.carrierServiceName | Name of the carrier for which the label was generated |
carrierLabel.serviceMethodName | Name of the service method for which the label was generated |
carrierLabel.carrierServiceMethodId | Maps 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.carrierShipmentId | Carrier's identification for the shipment |
carrierLabel.carrierTrackingId | Carrier's tracking identification for the package |
carrierLabel.shipiumTrackingId | Shipium's tracking identification for the package |
carrierLabel.carrierTrackingLink | Carrier's direct tracking link (URL) for the package |
carrierLabel.carrierGroupId | Carrier's identification for grouping multiple packages together (for example, Canada Post groups shipments for manifesting) |
carrierLabel.packageScannableId | Identifier provided that matches the scannable barcode on the label |
partnerThirdPartyBillingAccountId | The ID that your organization provided for the third party billing account that was used if the label was billed to a third party |
shipiumThirdPartyBillingAccountId | The Shipium-generated ID of the third party billing account that was used if the label was billed to a third party |
thirdPartyBillingForDutiesAndTaxes | Whether or not the third party paid the taxes and duties |
carrierLabel.carrierLabelCurrencyCode | Currency code of the price of the label |
carrierLabel.carrierLabelPrice | Cost charged by the carrier for shipping the package at the chosen service level |
carrierLabel.billableWeight.weightUnit | The unit in which weight values are provided |
carrierLabel.billableWeight.weight | The value of the weight |
carrierLabel.documents.labelExpiration | Date-time when the label expires and is no longer valid |
carrierLabel.documents.labelFormat | Defines the format the shipment label was generated in by the carrier |
carrierLabel.documents.labelProperties | Metadata describing the label |
carrierLabel.documents.labelProperties .height | Top to bottom measurement of the label |
carrierLabel.documents.labelProperties .width | Right to left measurement of the label |
carrierLabel.documents.labelProperties .linearUnits | The linear units representing the label height and label width |
carrierLabel.documents.labelProperties.dpi | The dpi (dots per inch) used by the label printer |
carrierLabel.documents.labelProperties .labelOrientation | The direction that the label will be printed |
carrierLabel.documents.labelProperties .nonZplLabelDimensions | The dimensions used to print non-ZPL labels, if they need to be different than ZPL dimensions |
carrierLabel.documents.labelImage .imageEncoding | Format in which the imageContents field is encoded (e.g., Base64) |
carrierLabel.documents.labelImage .imageContents | Raw 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.labelUrl | The link to the shipment label file |
carrierLabel.documents.carrierTrackingId | The tracking ID associated with the label |
carrierLabel.documents.carrierTrackingLink | The tracking link associated with the label |
carrierLabel.documents .packageReferenceIdentifier | The 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.packageScannableId | The package scannable ID associated with the label |
carrierLabel.documents.carrierShipmentId | The carrier shipment ID associated with the label |
carrierLabel.internationalDocuments | List of international customs documents generated by the carrier for the shipment; see Customs Info for Shipments for details. |
carrierLabel.labelFailoverOccurred | When true, signifies that label creation failover logic was exercised |
carrierLabel.labelFailoverDetails | Provides legacy and detailed debugging information on the label creation attempts when failover logic is used |
carrierLabel.trackingInfo | Details of the tracking history and status of the package |
carrierLabel.testMode | A flag denoting whether the label is a test label |
carrierLabel.multiParcel | A flag denoting whether the label is for multi-parcel shipments |
customsInfo | Customs information about the package for international shipping; see Customs Info for Shipments for details. |
saturdayDelivery | Indicates that this shipment is marked for Saturday delivery; does not guarantee delivery on Saturday |
deliverySignatureOption | Indicates the delivery signature option selected for the shipment |
deliveryWindow | A preferred delivery window passed to the carrier as a delivery note |
deliveryNote | String passed to carriers for a delivery note |
forceThirdPartyBilling | Indicates that third party billing is forced for this shipment |
requestThirdPartyBillingSetId | Either 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. |
referenceIdentifier | String passed to carriers as a reference |
partnerReferenceIdentifier | String provided by your organization that was passed to carriers as a reference |
partnerReferenceIdentifier2 | String provided by your organization that was passed to carriers as a reference2 |
purchaseOrderIdentifier | String passed to carriers as a purchase order identifier |
carrierProcessingId | Carrier-provided identifier; supplied when it is needed to process the shipment |
fulfillmentContext | When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context. |
requestTenantId | Either the Shipium tenant ID or the tenant ID provided by your organization; when present, this is the tenant ID sent on the request. |
createdWithVersion | The version used when creating the shipment: v1 or v2. |
shipmentProperties | A list of high-level properties about the shipment |
multiParcel | Indicates if the shipment is multi-parcel |
testMode | A flag denoting whether the shipment is a test shipment |
Additional options for calling the Carrier and Method Selection & Shipment Label API
Some cases require additional consideration, such as designating a desired delivery date or specifying a shipment as containing hazardous materials. These use cases are briefly listed here and described in more detail in Carrier and Method Selection & Shipment Labels.
- Shipment timing. Ship options and delivery date specification (ship option, configurable ship option, desired delivery date, guaranteed delivery date, business days of transit)
- Carrier options. Service method specification and FedEx One Rate (carrier service method allow list, supported carriers)
- Configured shipment settings. Fulfillment contexts and tenants (origin, carrier contract, tenant)
- Special processing and accessorial designations. Shipment parameters (delivery signature, Saturday delivery, transportation type, business days of transit, hundredweight)
- Order and package details. Product specifications, packaging planning, and multiparcel shipments (bound printed matter)
- Hazardous materials and perishable items. Hazmat, limited quantity, ORMD, lithium-ion, perishable, dry ice
- Customs specifications. Customs, international, electronic export information, incoterms, US territory, Army Post Office (APO), Fleet Post Office (FPO), Diplomatic Post Office (DPO)
- Analytics. Evaluated service methods (unselected carrier methods, carrier selection, rate selection)
- Account billing. Third party billing and labels without costing
- Carrier failover. Carrier failover is a setting within the Shipium Console that allows you to have a carrier as part of your fulfillment network but with a contingency in place in case there is an issue when calling that carrier for a shipment.
FAQ
Q: Can I include a desired delivery date (DDD) in addition to passing a ship option when using the all-in-one shipment and label method?
A: Yes. For example, shipOption: standard, desiredDeliveryDate: 2023-11-15 limits the carrier selection search to only those methods that are marked as standard and for which the DDD of 2023-11-15 can be met. If the DDD of 2023-11-15 cannot be met, Shipium will return the cheapest service method on 2023-11-16, and so on.
Resources
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
Updated 5 days ago