Shipment Label API

Purchase postage and retrieve a label image with Shipium's Shipment Label API.

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.

Request fieldRequired/OptionalField propertiesDescription
currencyCodeRequiredString
Example: USD
Currency in which all the rates for shipping carrier selection costs will be calculated
labelFormatsRequiredString
Supported formats are:

- PDF
- PNG
- ZPL
List of formats to generate the package label in
manifestRequiredBoolean
True or False
When true, a manifest for the label is generated. While manifesting is optional, this field value must be provided.
includeLabelImagesInResponseOptionalBoolean
True or False
When true, the response will include the raw image data of the labels that were requested to be generated by the carrier.
customLabelEntries .additionalProp1OptionalStringAdditional properties to be associated with the label, beginning with number 1
testModeOptionalBoolean
True or False
When true, calls to generate the labels will be made to the carrier sandbox servers. No actual labels are created, only a representation of the label. No money is charged to the underlying account.

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

Path

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

Alternatively, you can call the endpoint in the table below with a JSON request like the following sample.

API typeAPI endpoint
POSTapi/v1/deliveryexperience/shipment/carrierSelection/voidLabel
{
  "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:


What’s Next