Pallet and Carton Labels are used to externally identify boxes, packages, and pallets. When receiving goods, businesses and consumers can use Carton and/or Pallet labels to visually understand or capture detail about the contents of a particular shipment and streamline their receiving process. Pallet and Carton Labels can be used for basic or complex labels, like a pallet tag or a customer-specific UCC-128 common label.

ShipHawk supports the customization of pallet and carton labels. Using a variety of provided templates, you can edit existing labels to support your organization’s requirements.

This document is written for advanced users who understand the JSON markup format.

This guide covers the following topics:

Pallet/Carton Label Checklist

To successfully use ShipHawk’s pallet/carton labels, you must complete the prerequisite tasks in the following order:

Determine the references that you want to be included in the label.

Set up field mappings for any order data that you want to be visible on the label.

Contact your account manager to turn on the pallet/carton label feature.

Review the template gallery and select one that you want to customize.

The preceding steps describe a broad overview of the steps that must be finished before customizing your pallet/carton labels.

Pallet/Carton Label Customization

ShipHawk offers two ways to customize your pallet and/or carton labels. The simplest method is by using ShipHawk’s pallet and carton label customization interface, which is found in the Settings menu of ShipHawk’s dashboard. 

If the basic customization options do not meet your organization’s needs, more advanced customization options are available. You can either use ShipHawk’s professional services to create a customized label template or you can use the advanced sections of this document and your ShipHawk support representative as a guide to creating your own template file.

Label customization in ShipHawk

You can access the pallet and carton label template management in the user interface by clicking on the Settings icon in the upper right corner of the screen and selecting Settings > Pallet/Carton Labels from the drop-down menu. The Pallet/Carton Labels screen appears.

Open

From this screen, you can view all of your label templates. To add a new carton label, click on the +Add New Carton Label button.

Open

To add a new pallet label, click on the Action button to the right of the +Add New Carton Label button. Additional menu options appear.

Click on the Add New Pallet Label option.

The Add New [Carton/Pallet] Label screen appears.

From this template customization screen, you can set basic label information, choose the label layout, and select the variables that are displayed in each of the pre-set zones of the label. Each label template has zones that organize shipping data such as: Ship From, Ship To, Carrier Info, and Purchase Order Number. These zones are preset data categories for each available layout and cannot be changed.

In each zone are elements, which represent a space where you can insert a variable of your choice. 

Select a type of element you wish to insert by clicking on the Element drop-down field.

You can choose to delete that element by selecting None from the drop-down field. Selecting one of the other element options makes associated variables available in the Select Field drop-down field to the right. For example, if you select Order elements, then variables associated with an order become available for selection.

To configure the SSCC code for your new template label, click on the Manage SSCC Code Generators menu option from the Action drop-down button.

The Manage SSCC Code Generator screen appears.

On this screen, you can create and manage all your SSCC code generators. You can configure each generator using a combination of extension digits and GS1 company prefixes. ShipHawk also allows you to input your starting serial number, which ShipHawk will increment by 1 for every label thereafter. 

Once you finish, click the Add button to create the new SSCC code generator. You can now select this code generator while creating or editing your label template in the SSC18 section.

Click on the Select SSCC Code Generator button to view a list of your code generators and select one from the list.

As you customize your label,  you can preview its appearance by clicking the Render Sample button. The sample label downloads automatically as a PDF file to your computer. 

Once you are finished, click the Add New Carton Label button to save this new label to your account.

Advanced Customization

This section describes the broad concepts that govern how information is populated into a pallet/carton label. By understanding how a label is built by ShipHawk, you can build your own label templates and have them added to your ShipHawk account.

Template Body Structure

The main body of the template is organized into multiple zones that divide up the label into boxes that contain and organize shipping data. An example of a carton or pallet label appears below.

You can see that this template divides the body of the label into six zones or boxes. (The Example Template JSON code can be found in the appendix of this document.) You can assign any mapped references from your order data in each of these size zones and ShipHawk will automatically populate the label template based on your selections.

By default, templates are 4 x 6 inches. It is possible, however, to specify different sizes using the following JSON syntax.

Every template has basic required attributes that must be described using JSON syntax to correctly render the label:

In addition to zones, there are optional attributes that are helpful to include:

• width: The width of the label in inches (by default width equals 4)

• height: The height of the label in inches (by default height equals 6)

• dpi: The DPI (dots per inch) of your printer (by default dpi equals 203)

• print_speed: The print speed of your printer (by default print_speed equals 4)

• print_density: The print density of your printer (by default  print_density equals 6)

Zone Attributes

To create a zone on your new label template, you must describe its most basic attributes using JSON syntax. Specifically, you must specify how big the zone (box) is and where that zone is located on the label.

The appropriate syntax for the zone attributes is shown below.

In addition to size and position attributes, the following are optional attributes that are helpful to include:

• title: This attribute displays the title you want to display in this zone. For example, “Ships From:” “Ships To,” etc

• description: This attribute assigns a name to this zone. ShipHawk generally refers to zones as “Zone A,” “Zone B,” etc

• border_width:  This attribute assigns the width of a zone’s border in inches (by default  border_width equals 0.02)

• fields: The order data that you want to print in the current zone. These are the mapped references that you set up before creating a label

• font_size: The font size of the text in this zone

Based on the preceding  example, you will produce the following result when editing the label template in the ShipHawk User Interface:

Field Options

In each zone, you can add any field that you have already mapped beforehand. Once configured, the field will automatically populate with the correct values for each order. Examples of fields that you can include in a zone are: purchase order numbers, shipping address, sales price, etc. 

You can see an example of the correct JSON syntax below.

To add a field to a zone

Each field you want to add to a zone must contain certain attributes that control how that field is displayed. The required attributes are:

An example of the correct JSON syntax is shown below.

You can find a comprehensive list of supported variables in Appendix B.

To add a reference number

To print a reference number on your label, use the following syntax: “SOME TEXT ${ref=REFNUM_ID}”.

An example of the correct JSON syntax is shown below.

You may need to write your reference numbers using snake case. To do this, you use the format: “SOME TEXT ${ref=REFNUM#other_id#CUSTOMID}”.

The following example of the correct JSON syntax for a snake case uses a reference number called “CUSTOM_REFERENCE_NUMBER”. For ShipHawk, all custom reference numbers must be preceded by the prefix #other_id.

In addition to basic field attributes, the following are optional attributes that are helpful to include:

• position: When the position attribute is used to configure a field, it provides the coordinates of the text on the label. If you do not specify a position, the text will be automatically inserted in a single column for the zone, as below:

• font_type: The font_type attribute allows you to print bold text.  If you do not specify the font_type, all text renders normally.

• font_size: The font_size attribute controls the size of the displayed field text. Available font sizes are: 12, 17, 22, 28, 33, 44, 67, 100, 111, 133, 150, 170, 190, 220. The default font_size equals 22.

• justification: The justification attribute controls text alignment. The options are left, center, or right corner of the label. The syntax for the justification attribute options are  “L”, “C” and “R,” respectively. This option is ignored if the current field has a position specified.

Once fields are configured using the correct JSON syntax, the result looks like the example below.

Barcode Options

In addition to fields, you can print different types of barcodes on a pallet/carton label. Like any other pallet/carton label element, you can style or control how the barcode appears in zones on your template. Barcodes also have the following required attributes:

An example of the correct JSON syntax for barcodes is below.

In addition to basic barcode attributes, the following are optional attributes that are helpful to include:

• type: This attribute specifies the type of barcode you want to display. Supported barcode types are: code39, code93, code128, Codabar, code_aztec, code_aztec_params, code_ups_maxicode, code_qr, sscc18. By default the barcode type equals code128.

• print_text: This attribute prints a human-readable barcode number printed near the barcode. You can specify the position (above, below) of this text. If you don’t specify this attribute, the human-readable text will not be displayed.

Special Cases

This section discusses a few advanced or special formats that you can use in your JSON template.

Blocks

Entering fields one by one can take time. Blocks allow users to create a set of fields and enter them as a single element into the zone of choice. An example of a block that a user might create is an entire origin address rather than inserting individual fields for the street address, state and zip code.

The correct JSON syntax for blocks nests groups of fields underneath. Each block, which is considered an object, is given a name with the list of variables inside. Once the block is created, you can reference the entire block in the zone as its own field.

An example of the correct JSON syntax for blocks is below.

You can use multiple blocks. Each block you want to use is added into the "blocks": { ... } object.

SSCC18 Barcode

If you want to print a barcode in the sscc18 format (for more info visit https://www.gs1-128.info/sscc-18/ ),  you need to perform additional steps.

The SSCC18 format requires you to specify a few variables in the template body before you enter the main barcode syntax. The required attribute variables to create an SSCC18 format are:

Enter the SSCC18 attributes using the format shown below.

In addition to basic SSCC18 attributes, the following are optional attributes that are helpful to include:

• extension_digit: Visit https://www.gs1-128.info/sscc-18/ for more details. By default extension_digit equals 0.

After specifying the SSCC18 attributes, you can print SSCC18 barcode using the following JSON syntax:

The main difference between the SSCC18 barcode format and other barcode formats is that SSCC18 barcodes do not need to specify the text attribute. This is because the SSCC18 barcode value will be generated using the serial_reference, gs1_company_prefix, and extension_digit variables (visit https://www.gs1-128.info/sscc-18/ for more details).

Add Pallet/Carton Template to Account

This section discusses how you can work with ShipHawk to add new pallet or carton labels to your account.  You can either engage ShipHawk professional services or build your own using this guide. When building your own, you do not have the option to test or render it without working with your ShipHawk Customer Success Manager.

Request to add JSON template to Account via Support

Once you complete the desired carton label, contact a Technical Customer Success Manager (TCSM) at ShipHawk to add the JSON template to our system.  Once the JSON template is in our system, the TCSM will quickly review the JSON and correct any obvious flaws or reach out to you if any clarifications are needed.

Schedule a time to test and review the JSON

Once the JSON template has been reviewed by the TCSM and tested locally on our end, we will schedule a meeting to test the carton label with a live/test order in your ShipHawk account.

Appendix A

Pallet/Carton Label Template JSON example

Below is a complete example of a basic pallet/carton label rendered in the JSON format. If you have questions after reviewing this document, contact your ShipHawk implementation engineer.

Appendix B

Supported variables

Listed below is a complete list of supported variables. If you require a variable that is not included in this list, contact your ShipHawk implementation engineer.