Carrier Shipment Label Flow

Suggest Edits

About the Shipment Label API

Use the Shipium Shipment Label application programming interface (API) to purchase postage and retrieve a label image for a given carrier and ship method context of the Shipium Carrier Selection API.

You must pass two elements to this method:

  • whether or not to perform a carrier manifest when retrieving the label; and
  • the format of the label(s) to be returned. This value is an array, so multiple formats can be retrieved. Currently you can pass either ZPL for Zebra Printer Language labels or PNG for Portable Network Graphic format labels.

Optionally, you can also pass includeLabelImagesInResponse: "true" to get back a BASE64-encoded version of the PNG if requested, or the ZPL code if ZPL was requested.

Creating a new label (and optionally manifesting)

Here is the general form:

<<api_url>>/api/v1/deliveryexperience/shipment/{shipiumShipmentId | partnerShipmentId}/carrierselection/{carrierSelectionId}/label

Replace the following elements that are shown above enclosed in {}:

  • {shipiumShipmentId | partnerShipmentId} - with either our shipment identifier or your own, if you provided this when the shipment was created
  • {carrierSelectionId} - the ID that was returned in a prior Carrier Selection call response

📘

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 it to make production calls.

Creating a label

This example shows the cURL request. Note the use of includeLabelImagesInResponse: true.

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/a69be08c-f3f5-4c26-ab16-46cbfdf9004e/carrierselection/2dc48065-89cf-4cd2-88be-ba6c69b3768e/label \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"labelFormats": ["ZPL"], "manifest": true, "includeLabelImagesInResponse": true, "testMode": true}'

This example shows the JSON equivalent:

{
  "currencyCode": "usd",
  "labelFormats": ["ZPL"],
  "manifest": true,
  "includeLabelImagesInResponse": true,
  "testMode": true
}

This example shows the response:

{
  "shipiumLabelId": "3049babf-f766-4490-be89-fa781168b8f8",
  "effectiveShipDateTime": "2022-11-28T03:00:00Z",
  "carrier": "usps",
  "carrierServiceName": "ground",
  "carrierLabelCurrency": "usd",
  "carrierLabelPrice": 7.45,
  "billableWeight": {
    "weight": 6.0,
    "weightUnit": "lb"
  },
  "carrierSelectionId": "2dc48065-89cf-4cd2-88be-ba6c69b3768e",
  "carrierTrackingId": "92612999916518543481369406",
  "carrierTrackingLink": "https://tools.usps.com/go/TrackConfirmAction?tLabels=92612999916518543481369406",
  "documents": [
    {
      "labelExpiration": "2020-11-19T21:11:42.628Z",
      "labelFormat": "ZPL",
      "labelImage": {
        "imageEncoding": "base64",
        "imageContents": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACPTkDJAAACJElEQVRYCe1Vz0sbURCe2XWbiNZKRaxgEipIKYVSqFR7SuJRCipSDz1JD1Io4j/goe2l9xYPxYu9FLoRz/aUaCmUYKFee4hiKSg0ovVHY0x2nCe85e3GmM2Kl3bf5c3Mm/fN976ZZQGCFSgQKPC/K4AXEeDu6qemP9uHRi2M9eTITrUcXwS6l+Z7SmSZRHCvGrAzjnnQ6PnP+NhHZxxAcwe8+MdkvfFeXCBSGxLMda+Y19z4De6A8GPp1DQBdLVfvTm5s5eLFRFeslStMhcRZwHxrfTV3SJ6B0RdakzYTDhMh3CLzax6VkFAsDzeh1d8A3/v595zoUdsP2FC9tLDV56u9Q9t2QHFiKbNAzVXOQIq6xWKVxDI9Y7tRjOpKS7c+SBO2W9f6JdVQn492QpQoTgYWzKPVHBpM+8W8Vyvy9cQ8is3uUSH1yIyTwf94Xpy9Kv0xe6Q5AWRw1cTL8u2FYik53tZ5kVEWNhIPJ6IZFIz7D8DcpIURBoaQzfUGYh+Nu9TCVZqkTxXAUTrNhdsI6B+AYRAibOK1ypS77k9hH1x+JBd1vIhw1oVIHo4NEB/i0nSKttSKhRfRzJmSBajMlyXdr273YJ6Ll7aEHomwf3xnKskol62FPfU9DX1/JmftskNdp7Pw12gsvHDneOLgKFpkwz43Q1W3cc8IYyf9Vf0NQOy0J202XwAhj3IMu7e1xLDu/z/8NU2N1bgBwoECvx7CpwAEhquciKZh7kAAAAASUVORK5CYII="
      },
      "labelUrl": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
    }
  ],
  "status": "success",
  "statusDetails": "Label created successfully"
}

Retrieving details of a previously created label

Your organization can retrieve details of a label you've previously created by calling the API and passing the elements required to retrieve the label details, as described in this section.

This example shows the general form:

<<api_url>>/api/v1/deliveryexperience/shipment/{shipiumShipmentId | partnerShipmentId}/carrierselection/{carrierSelectionId}/label/{shipiumLabelId}?includeLabelImagesInResponse={true|false}

Replace the following elements that are shown above enclosed in {}:

  • {shipiumShipmentId | partnerShipmentId} - with either our shipment identifier or your own, if provided when the shipment was created
  • {carrierSelectionId} - with the ID that was returned in a prior Carrier Selection call response
  • {shipiumLabelId} - with the ID returned in a previous label response
  • {true | false} - with your preferred selection, either true or false, depending on if you want the label images included in your response

Specific example

The following request retrieves exactly the same contents as shown above. The sample request includes a true value for the includeLabelImagesInResponse query. To not include the label images in your response, you'll need to change this value from true to false.

Shell
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/a69be08c-f3f5-4c26-ab16-46cbfdf9004e/carrierselection/2dc48065-89cf-4cd2-88be-ba6c69b3768e/label/d838f2a6-4abd-499a-a5d1-186ea7f90184?includeLabelImagesInResponse=true
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

Previously generated labels are available for 72 hours after initial creation via the documents.shippingLabel.labelUrl field. The documents.shippingLabel.labelExpiration field has the specific time after which the label is no longer accessible.

Short form call

If you're performing an integration with Shipium without storing the order and shipment information, you can make a shorter call using only the shipiumLabelId to retrieve a previously created label. The sample request includes a true value for the includeLabelImagesInResponse query. To not include the label images in your response, you'll need to change this value from true to false. This is shown below:

Text
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}?includeLabelImagesInResponse=true
  --header 'accept: application/json' \
  --header $AUTHSTRING

As described above, you will replace the {shipiumLabelId} with the ID returned in a previous label response.

Retrieving a label image only

If you need to retrieve just a label image in a particular form, you can make a call to retrieve only the stream of data for that format.

PNG
This cURL request gets the image as a PNG file:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/png \
  --header 'accept: application/json' \
  --header 'content-type: image/png' \
  --header $AUTHSTRING

ZPL
This cURL request gets the image as ZPL code:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/zpl \
  --header 'accept: application/json' \
  --header 'content-type: application/octet-stream' \
  --header $AUTHSTRING

PDF
This cURL request gets the image as a PDF file:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}/pdf \
  --header 'accept: application/json' \
  --header 'content-type: application/pdf' \
  --header $AUTHSTRING

📘

More information on the API responses

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

Updated 5 months ago