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 field | Required/Optional | Field properties | Description |
---|---|---|---|
currencyCode | Required | String Example: USD | Currency in which all the rates for shipping carrier selection costs will be calculated |
labelFormats | Required | String Supported formats are: - PNG - ZPL | List of formats to generate the package label in |
manifest | Required | BooleanTrue or False | When true , a manifest for the label is generated. While manifesting is optional, this field value must be provided. |
includeLabelImagesInResponse | Optional | BooleanTrue 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 .additionalProp1 | Optional | String | Additional properties to be associated with the label, beginning with number 1 |
testMode | Optional | BooleanTrue 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
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.
API type | API endpoint |
---|---|
POST | api/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:
Updated 11 days ago