Carrier Shipment Label Flow
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.
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