About label customization

Your organization may need 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.

To find guidance on configuring your organization's preferred label settings within the Shipium Console, see Label Configuration.

ZPL label injection

First you will need to add an additional piece of Zebra Programming Language (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 or Customer Success team members can help you implement this ZPL based on what changes you're trying to make to a given carrier's label.

Macro values in a configured ZPL

Most importantly, you can add custom data into your label 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:

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

Keys in customLabelEntries are normalized before being matched against macros in your ZPL. Each key is converted to uppercase and wrapped in underscores. For example, a key of driverName matches the macro _DRIVERNAME_, and a key of order-id matches the macro _ORDER-ID_. Make sure your ZPL macros use this uppercase-and-underscores format so that your values are inserted correctly.

Pass per-shipment data to the ZPL label augmentation

In both the Shipment Label API call or the all-in-one Carrier and Method Selection & Shipment Label API 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:

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

Details on common label augmentations

To get more details about common use cases and examples for creating label augmentations, see the document Common Label Augmentations.

📘

More information on the API responses

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

Update custom label entries after label creation

In some workflows, the metadata you want on a label isn't available at the time of carrier selection. For example, route numbers, stop numbers, and driver assignments may be finalized later in the day. You can update the customLabelEntries on a previously generated label by sending a PATCH request to the Update a label endpoint, which regenerates the label with the new values.

How updates work

When you include customLabelEntries in a PATCH request, Shipium automatically regenerates the label using your updated values. You don't need to pass a separate flag to trigger regeneration.

All formats of the label are refreshed as part of this process, including ZPL, PDF, and PNG. The same key normalization rules apply to updates as to label creation: each key is converted to uppercase and wrapped in underscores before being matched against your configured ZPL macros.

Request and response example

The following PATCH request updates the route, stop, driver, and delivery instructions on a label:

{
  "customLabelEntries": {
    "routeNumber": "3",
    "stopNumber": "40",
    "driverName": "Brandon L",
    "deliveryInstructions": "Leave at front door",
    "sortCode": "TOR"
  }
}

The response returns the updated label. Two fields reflect the changes:

• documents[].labelImage.imageContents. The label image is regenerated to include the new values.
• customLabelEntries. The values you supplied in the request are echoed back in the response.

Each PATCH replaces all custom label entries

🚧

Include every entry you want to keep on every PATCH request

Each PATCH request replaces the entire set of custom label entries stored on the label. Partial updates are not supported.

If you send a PATCH with only some of the entries currently on the label, the entries you leave out are removed.

For example, suppose a label has the following entries stored on it:

{
  "routeNumber": "3",
  "driverName": "Brandon L",
  "deliveryInstructions": "Leave at front door"
}

If you then send a PATCH request with only a new route number:

{
  "customLabelEntries": {
    "routeNumber": "4"
  }
}

The label will be regenerated with only routeNumber: "4". The driver name and delivery instructions will be removed.

To update only the route number while keeping the other values, include all three entries in the request:

{
  "customLabelEntries": {
    "routeNumber": "4",
    "driverName": "Brandon L",
    "deliveryInstructions": "Leave at front door"
  }
}

Behavior for Shipium-generated and carrier-generated labels

Both label types support updates to customLabelEntries, with one difference in how regeneration works.

• Shipium-generated labels. The label is regenerated directly with the new values.
• Carrier-generated labels. The original carrier label is retained and re-augmented locally with the new values. No new call is made to the carrier, so the update does not consume additional carrier API quota or incur carrier charges.

Behavior by label state

A label's current state affects how Shipium handles a PATCH request containing customLabelEntries. The following table describes the behavior for each state.

If expected values don't appear on your label

Updates to customLabelEntries are stored even if the values cannot be rendered on the label. If you update entries and don't see your expected values on the printed label, check the following:

• Key names match your ZPL macros. Remember that keys are normalized to uppercase and wrapped in underscores before matching. A key of routeNumber matches the macro _ROUTENUMBER_, not _routeNumber_ or _route-number_. A mismatched key stores successfully but has no effect on the printed label.
• A ZPL augmentation is configured for the carrier and service method in use. If no augmentation is configured, customLabelEntries values are stored on the label record but have nowhere to render on the printed label. Work with your Shipium Implementation or Customer Success team to confirm your augmentation setup.

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

• Common Label Augmentations