Get started

To use the Shipment Label API, you can follow the instructions on this page. To establish preferred label settings, you can refer to the Label Configuration documentation, which provides guidance for setting up label preferences and any desired label augmentations in the Shipium Console.

👍

Test mode for label generation

Including testMode = "true" in your call to the Shipment Label API enables generation of labels for testing purposes, so that your account will not be charged.

Information about carrier and method selection and shipment labels within the Shipium platform can be found in the Carrier and Method Selection & Shipment Labels and Shipment Labels documentation.

Manage labels with the Shipment Label API

The Shipium Shipment Label API assumes you're using one of the authentication mechanisms detailed in our authentication documentation.

📘

Authentication for API Calls

In the cURL example 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.

The following table provides required and optional fields for calling the Shipment Label API. Path elements are described for each use case in the sections that follow.

Generate a shipment label

Path

POST https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label

Required path element: shipiumShipmentId | partnerShipmentId (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

Required path element: carrierSelectionId

Example cURL call

This example shows a request to generate a label for an existing shipment:

curl --request POST \
  --url https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

This example shows the JSON request:

{
  "currencyCode": "usd",
  "labelFormats": [
    "ZPL"
  ],
  "manifest": true,
  "includeLabelImagesInResponse": true,
  "customLabelEntries": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "testMode": true
}

Example response body

{
  "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"
}

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

Path

POST
https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label

Required path element: shipiumShipmentId | partnerShipmentId (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

Optional path element: carrierSelectionId (Replace this with the ID that was returned in a prior carrier selection call 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.

Path

GET
https://api.shipium.com/api/v1/deliveryexperience/shipment/carrierselection/label/{shipiumLabelId}?includeLabelImagesInResponse=true

Required parameter: shipiumLabelId (Replace this with the ID returned in a previous label response.)

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

Retrieve 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. For any format, you'll provide the required shipiumLabelId parameter in the request.

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.

Void a label

Shipium recommends calling the cancellation endpoint in the cURL example below to void a shipment label. This example uses the shipiumLabelId. You can include only one of the unique IDs associated with your cancellation request: either the shipmentId, carrierSelectionId, shipiumLabelId, or carrierTrackingId.

curl --request POST \
     --url https://api.shipium.com/api/v1/deliveryexperience/cancel \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
        "cancellationDateTime": "2024-08-21T18:30:55.558Z"
      }'

For details on canceling a shipment and the associated carrier selection while voiding a label, you can refer to Cancel a Shipment.

Alternatively, you can use the following path to void a label.

POST
https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}/void

Required path element: shipiumShipmentId | partnerShipmentId (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

Optional path element: carrierSelectionId (Replace this with the ID that was returned in a prior carrier selection call response.)

Required path element: shipiumLabelId (Replace this with the ID that was returned in a prior Carrier Label Service call response.)

You also can call the endpoint in the table below with a JSON request like the sample included.

{
  "shipiumLabelId": "5fb3c758-034c-45c9-bf99-d60ca472f75e",
  "carrierTrackingId": "f3c3982e-35d6-4027-9393-eba4469139c7"
}

Manifest a label

Path

POST
api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}/manifest

Required path element: shipiumShipmentId | partnerShipmentId (Replace this with either Shipium's shipment identifier or your own, if provided when the shipment was created.)

Optional path element: carrierSelectionId (Replace this with the ID that was returned in a prior carrier selection call response.)

Required path element: shipiumLabelId (Replace this with the ID that was returned in a prior Carrier Label Service call response.)

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support