About making a single call for carrier and method selection and label generation

If your organization doesn't implement Shipium's shipment methods and your physical process doesn't separate carrier/method selection from label generation, you can use this application programming interface (API) to combine the two separate calls into a single call. Using this API can reduce total call time through a reduction in network time versus the individual calls.

For this use case, you can make a single call that:

populates shipment and product details;
provides costs;
selects an appropriate carrier and ship method based on your configured rules; and
returns your shipping label.

📘
API Response Code Standards
As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Request elements

The request object has three major sections:

Each of these major elements appears with the same data that you would find if you made those calls individually, but combined together and grouped by their respective steps. Details about additional special-use elements that can be passed are included in the Handling Special Cases section in this documentation.

📘
Authentication for API Calls
In the cURL examples 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 all contain the testMode flag to err on the side of caution – remove this to make production calls.

Request examples

This example shows the cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/shipment/carrierselection/label \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'
POST /api/v2/shipment/carrierselection/label

This example shows the JSON:

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "testMode": true,
    "currencyCode": "usd",
    "labelFormats": [
      "ZPL"
    ],
    "manifest": true,
    "includeLabelImagesInResponse": true
  },
  "shipmentParameters": {
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "orderedDateTime": "2019-10-29T09:12:33.123456Z",
    "shippedDateTime": "2019-11-01T12:11:33Z",
    "shipOption": "Standard",
    "referenceIdentifier": "yourCustomIdentifier",
    "shipmentTags": [
      "string"
    ],
    "destinationAddress": {
      "addressType": "residential",
      "name": "Wile E. Coyote",
      "company": "ACME",
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121"
    },
    "orderItemQuantities": [
      {
        "productDetails": [
          "ormd",
          "lio"
        ],
        "productId": "PRODUCTID001",
        "quantity": 3
      }
    ],
    "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6
            "height": 3,
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        },
    },
    "shipFromAddress": {
      "addressType": "commercial",
      "city": "Albuquerque",
      "company": "ACME",
      "countryCode": "US",
      "name": "L. Merfudd",
      "postalCode": "87121",
      "state": "NM",
      "street1": "123 Main St.",
      "street2": "Suite 42"
    }
  }
}

Response elements

Like the request object, the response object has three major sections:

Each of these major elements appears with the same data that you would find if you made those calls individually, but combined together and grouped by their respective steps with carrier/method and label responses grouped together. The label response is a superset of the carrier/method response.

More specifically, they're all elements of a completely populated shipment object, which is effectively what is returned from this call with all elements populated.

Response examples

This example shows a JSON response:

{
  "carrierSelection": {
    "carrier": "ups",
    "carrierAccountId": "4be237e4-eeb2-4e8a-94ea-6db695313ca6",
    "carrierSelectionDateTime": "2020-11-19T21:08:54.305Z",
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "partnerId": "96ddb56a-18ba-4034-a14e-3fab072478f4",
    "serviceMethodName": "ground",
    "serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1",
    "totalCost": 7.53
  },
  "carrierName": "ups",
  "carrierTrackingId": "1Z999AA10123456784",
  "deliveredDateTime": "2020-10-31T10:50:11.123456Z",
  "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
  "destinationAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "company": "ACME",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "fulfillmentCenterId": "74065136-85c2-499b-b893-bd812ac0c00f",
  "carrierLabel": {
    "effectiveShipDateTime": "2022-11-28T03:00:00Z",
    "carrier": "ups",
    "carrierLabelCurrency": "usd",
    "carrierLabelPrice": 7.53,
    "billableWeight": {
      "weight": 6.0,
      "weightUnit": "lb"
    },
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "carrierServiceName": "ground",
    "carrierTrackingId": "1Z999AA10123456784",
    "carrierTrackingLink": "https://www.ups.com/track?tracknum=%2B1Z999AA10123456784",
    "documents": [
      {
        "labelExpiration": "2020-11-19T21:08:54.305Z",
        "labelFormat": "ZPL",
        "labelImage": {
          "imageContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC",
          "imageEncoding": "base64"
        },
        "labelUrl": "string"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "string"
      ],
      "productId": "PRODUCTID001",
      "quantity": 3,
    }
  ],
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6
            "height": 3,
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }          
  },
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "shipFromAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "L. Merfudd",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Main St.",
    "street2": "Suite 42"
    "countryCode": "US"
  },
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipiumShipmentId": "0840c7a2-e6ab-4755-8aa2-9a986297ad6d",
  "shipmentTags": [
    "string"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

Retrieve a prior response

This is no different to retrieving a response from other carrier shipment methods. Here is the cURL request:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/49cf130d-b297-4c12-aa7d-82ea80208fde/carrierselection/5b0514bc-3cae-4311-af44-a95e64003631/label/5b37704e-130e-4893-82e7-600843475bbb \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

{
  "carrierSelection": {
    "carrier": "ups",
    "carrierAccountId": "4be237e4-eeb2-4e8a-94ea-6db695313ca6",
    "carrierSelectionDateTime": "2020-11-19T21:08:54.305Z",
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "partnerId": "96ddb56a-18ba-4034-a14e-3fab072478f4",
    "serviceMethodName": "ground",
    "serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1",
    "totalCost": 7.53,
    "evaluatedServiceMethods": [
      {
        "carrier": "usps",
        "serviceMethodName": "usps-ground-advantage",
        "carrierAccountId": "5db5b0cd-b965-41e2-b7a9-dd275e9825be",
        "totalCost": 8.01,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z"
      },
      {
        "carrier": "ups",
        "serviceMethodName": "ups-ground",
        "carrierAccountId": "21032683-9ae9-46d0-830c-498b6c2b99b4",
        "totalCost": 8.04,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z"
      },
      {
        "carrier": "cdl",
        "serviceMethodName": "cdl-standard",
        "carrierAccountId": "494a7a1f-50ff-4c82-bbdd-7b29230ca84b",
        "injectionDetails": {
              "requestInjectionProfileId": "cdl-injection",
              "partnerInjectionProfileId": "cdl-injection",
              "shipiumInjectionProfileId": "5aj8748a-eb35-40c1-9b3c-a9eb52fd9jjf2",
              "requestInjectionSiteId": "cdl-injection-pheonix",
              "partnerInjectionSiteId": "cdl-injection-pheonix",
              "shipiumInjectionSiteId": "9v38748a-eb35-40c1-9b3c-a9eb52fd9d12",
        },
        "totalCost": 8.12,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z"
      }
  ],
  },
  "carrierName": "ups",
  "carrierTrackingId": "1Z999AA10123456784",
  "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
  "destinationAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "company": "ACME",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "fulfillmentCenterId": "74065136-85c2-499b-b893-bd812ac0c00f",
  "carrierLabel": {
    "effectiveShipDateTime": "2022-11-28T03:00:00Z",
    "carrier": "ups",
    "carrierLabelCurrency": "usd",
    "carrierLabelPrice": 7.53,
    "billableWeight": {
      "weight": 6.0,
      "weightUnit": "lb"
    },
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "carrierServiceName": "ground",
    "carrierTrackingId": "1Z999AA10123456784",
    "carrierTrackingLink": "https://www.ups.com/track?tracknum=%2B1Z999AA10123456784",
    "documents": [
      {
        "labelExpiration": "2020-11-19T21:08:54.305Z",
        "labelFormat": "ZPL",
        "labelImage": {
          "imageContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC",
          "imageEncoding": "base64"
        },
        "labelUrl": "string"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "string"
      ],
      "productId": "PRODUCTID001",
      "quantity": 3,
    }
  ],
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6
            "height": 3,
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }          
  },
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "shipFromAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "L. Merfudd",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Main St.",
    "street2": "Suite 42"
    "countryCode": "US"
  },
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipiumShipmentId": "0840c7a2-e6ab-4755-8aa2-9a986297ad6d",
  "shipmentTags": [
    "string"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

Handle special cases

Some cases require additional consideration, including the ones described here. For use cases that exceed the guidance provided in this documentation, please reach out to your Implementation or Customer Success team member.

Special processing and accessorial options

Several optional special processing elements can be included as part of the shipmentParameters element. You can find more details about them in Shipment Special Processing Properties.

Ship options

You may want to specify a particular class of shipment, such as NextDay or TwoDay. You can do this by specifying a shipOption value. You can find specific information in Configurable Ship Options and Shipium Default Ship Options.

Hazardous materials or limited quantity/ORMD

Where one or more items requires either a limited quantity or hazardous materials designation, you must specify several additional details for the shipment. You can find the details in Hazardous Materials Support.

Force a particular carrier method

To force a specific carrier method, you can use the carrierServiceMethodAllowList in your API call. However, this should be used as a last resort as it can limit your options and potentially impact delivery performance or cost. You can find additional information in Specifying Carrier Service and Method.

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.

Carrier and Method Selection with Label Single Call

About making a single call for carrier and method selection and label generation

📘
API Response Code Standards

Request elements

📘
Authentication for API Calls

🚧
Test Mode

Request examples

Response elements

Response examples

Retrieve a prior response

Handle special cases

Special processing and accessorial options

Ship options

Hazardous materials or limited quantity/ORMD

Force a particular carrier method

FAQ

About making a single call for carrier and method selection and label generation

📘API Response Code Standards

Request elements

📘Authentication for API Calls

🚧Test Mode

Request examples

Response elements

Response examples

Retrieve a prior response

Handle special cases

Special processing and accessorial options

Ship options

Hazardous materials or limited quantity/ORMD

Force a particular carrier method

FAQ

📘
API Response Code Standards

📘
Authentication for API Calls

🚧
Test Mode