Carrier Shipment Label Flow

Suggest Edits

Overview

Use the Shipium Shipment Label 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.
  • 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 PNG 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.

General form for 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 which 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,
  "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

This example shows the general form:

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

Replace the following elements which 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.

Specific example:

The following request retrieves exactly the same contents as shown above.

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 \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

If you need to retrieve a previously-generated label, they 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 are 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. This is shown below:

Text
curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId} \
  --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:

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 4 months ago