Carrier and Method Selection with Label Single Call

Overview

If your organization is not implementing Shipium's shipment methods and your physical process is such that it does not make sense for you to separate out Carrier/Method selection from label generation, we provide an API that enables you to combine the calls into a single call.

For this use case, you can make a single call that populates shipment and product details, costs and selects an appropriate carrier and ship method based on your configured rules and returns a label all in one shot. This can reduce total call time through a reduction in network time vs. the individual calls.

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.

There are additional special-use elements that can be passed, and you can find more details about them below under Handling Special Cases below.

📘

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.

📘

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 example

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 '{"currencyCode": "usd", "generateLabel": true, "labelParameters": {"testMode": true,"currencyCode": "usd", "labelFormats": ["ZPL"], "manifest": true, "includeLabelImagesInResponse": true  }, "shipmentParameters": {"partnerShipmentId": "myCustomPartnerShipmentId123", "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde", "orderedDateTime": "2019-10-29T09:12:33.123456Z", "shippedDateTime": "2019-11-01T12:11:33Z", "shipOption": "Standard", "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": {"packagingTypeId": "cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4"}, "totalWeight": {"weight": 6.58, "weightUnit": "lb"}, "shipFromAddress": {"addressType": "commercial", "city": "Albuquerque", "company": "ACME", "countryCode": "US", "name": "Wile E. Coyote", "postalCode": "87121", "state": "NM", "street1": "123 Main St.", "street2": "Suite 42"}}}'
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",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "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 since the label response is a superset of the carrier/method response.

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

Response example

This example shows a 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",
  "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": {
    "carrier": "ups",
    "carrierLabelCurrency": "usd",
    "carrierLabelPrice": 7.53,
    "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"
  }
}

Retrieving 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'

Handling special cases

There are three types of case:

  • 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, TwoDay, etc. You can do this by specifying a shipOption value. See the documentation for more details.

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

  • Forcing a Particular Carrier Method *

📘

More information on the API responses

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


Did this page help you?