Carrier Shipment Label Custom Label Augmentations

Overview

For some Shipium customers, it may be necessary to add or modify information on the shipping label that is returned from the carrier. In order to make this process as simple as possible, Shipium provides two facilities to make this work.

❗️

Make sure label changes are approved!

There is very little room on most carrier labels and carriers do not like you to modify them.

If you are planning on augmenting a label, you will need to work with the specific carrier to get any changes approved through their process.

Be aware that some carriers require an annual recertification if you are making modifications.

ZPL label injection

First you will need to add an additional piece of ZPL to be inserted at the end of a label before it is returned or rendered for the carrier for which you want to add such an augmentation.

Your Shipium implementation team or customer success team members can help you implement this ZPL based on what changes you are trying to make to a given carrier's label.

Macro values in a configured ZPL

Most importantly for our purposes here, you can add custom data into your augmentation.

Within the ZPL that is to be injected, you can insert one or more pieces of text that will be replaced, based on values passed when requesting a label.

Within the label itself, this looks like a piece of text starting and ending with an underscore and is all caps. For instance, you might want to insert an order id value into your label. Assuming our ZPL is the following:

Text

^FT200,855^A0,23,29^FH^FD_ORDER-ID_^FS

The _ORDER_ID_ text would be replaced with data passed into the call using the customLabelEntries map that is passed as part of the label information in label creation calls.

Passing per-shipment data to the ZPL Label Augmentation

In both the label-generation label call or the mega-shipment-process all-in-one call, you can pass the optional customLabelEntries map with values to be replaced in the custom ZPL Label Augmentation that you have configured. In both cases, this element should be part of the labelParameters entity.

Again, using the above custom ZPL Label Augmentation as an example, in order to replace the ORDER_ID placeholder macro with your value for a particular value, you would pass in the following additional JSON as part of the label data:

JSON

{
  ...
  "labelParameters": {
    "testMode": true,
    ...
    "customLabelEntries": {
        "order-id": "ORD-12345-TEST"
     }
    ...
  }
}

This results in the value "ORD-12345-TEST" replacing the ORDER_ID macro placeholder when the label in question is generated.

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.