Shipping Labels

Shipping labels are printable address labels used on packages. Meloncart supports two types of shipping labels: template labels that you design and print yourself, and carrier labels generated by shipping carriers (such as USPS) that include barcodes and postage.

Template Labels

Template labels are customizable HTML-based labels that display sender and recipient address information. They are available for all orders regardless of the shipping method used.

Printing a Shipping Label

Open an order and click the Print Shipping Label button in the toolbar. A popup displays the rendered label with a Print button that opens your browser's print dialog.

The label is rendered using the default shipping label template. If no default template exists, you will see an error prompting you to create one in Settings.

Shipping Label Templates

Navigate to Settings → Shipping Label Templates to manage your templates. A default template is created during installation.

Creating a Template

Click New Shipping Label Template to create one. Each template has:

Name — A descriptive name for the template (e.g., "Standard 4x6 Label").
Code — A unique identifier.
Is Default — Whether this template is used when printing labels from order pages.

Editing Template Content

Templates have two content tabs:

HTML — The template markup, combining syntax fields and Twig variables.
CSS — Print-friendly styles that control label dimensions and layout.

After saving a template, any syntax fields defined in the HTML appear as editable form fields in the Label tab. This lets you customize your sender information without editing the HTML directly.

Syntax Fields

Syntax fields let you embed editable values directly in the template. When saved, these fields are extracted and presented as form fields.

html

{text name="sender_name" label="Sender Name"}Company Name{/text}
{textarea name="sender_address" label="Sender Address" size="small"}
123 Sender Street
City, State 12345
{/textarea}

Common syntax field types:

Type	Description
`{text}`	Single-line text input
`{textarea}`	Multi-line text input

Twig Variables

Recipient address data is populated from the order's shipping details:

Variable	Description
`{{ order.shipping_first_name }}`	First name
`{{ order.shipping_last_name }}`	Last name
`{{ order.shipping_company }}`	Company name
`{{ order.shipping_street_address }}`	Street address
`{{ order.shipping_city }}`	City
`{{ order.shipping_zip }}`	ZIP/postal code
`{{ order.shipping_state.code }}`	State/province code
`{{ order.shipping_country.name }}`	Country name
`{{ css }}`	The template's CSS content

Default Template

The default template includes:

FROM section — Sender name and address (editable via syntax fields).
TO section — Recipient name, company, and address from the order's shipping details.

The default CSS is designed for 4-inch-wide label stock with a print-friendly layout.

Example Template

html

<html>
    <head>
        <style type="text/css" media="screen, print">
            {{ css }}
        </style>
    </head>
    <body>
        <div class="shipping-label">
            <div class="label-sender">
                <strong>FROM:</strong><br>
                {text name="sender_name" label="Sender Name"}My Store{/text}<br>
                {textarea name="sender_address" label="Sender Address" size="small"}
123 Main St, City, State 12345
                {/textarea}
            </div>
            <div class="label-recipient">
                <strong>TO:</strong><br>
                {{ order.shipping_first_name }} {{ order.shipping_last_name }}<br>
                {{ order.shipping_street_address }}<br>
                {{ order.shipping_city }}, {{ order.shipping_state.code }} {{ order.shipping_zip }}<br>
                {{ order.shipping_country.name }}
            </div>
        </div>
    </body>
</html>

Carrier Labels

Some shipping types support generating carrier labels directly from the carrier's API. Carrier labels include barcodes, postage, and tracking numbers — they are ready to affix to packages without additional postage.

Supported Carriers

Carrier label generation is currently supported by the following built-in shipping types:

Carrier	Requirements
USPS	Enterprise Payment Account (EPS), CRID, and Mailer ID. Enable under Label Generation in the shipping method config.
Australia Post	eParcel or StarTrack contract. Requires separate Shipping & Tracking API credentials. Enable under Label Generation in the shipping method config.

Label generation is opt-in — it must be enabled in the shipping method's configuration. This is because generating a carrier label purchases postage, and not all merchants have the required carrier accounts.

Enabling Carrier Labels

To enable carrier label generation for a shipping method:

Navigate to Shop → Shipping Options and edit the shipping method.
Open the Label Generation tab.
Check Enable Carrier Label Generation.
Enter the required credentials for your carrier (these are separate from the rate quoting credentials).
Save the shipping method.

Once enabled, the Generate Carrier Label button appears on order preview pages that use this shipping method.

Generating a Label

Open an order preview and click the Generate Carrier Label button in the toolbar. A popup appears with:

Carrier-specific options — such as label format (PDF/ZPL), label size, and package weight. These fields vary by carrier.
A warning — reminding you that generating a label will purchase postage from the carrier and charge your account.

Review the options and click Generate Label. The system calls the carrier's API, purchases postage, and stores the label. A tracking number is automatically created for the order.

WARNING

Generating a carrier label purchases postage. The charge is applied to your carrier account (e.g., USPS Enterprise Payment Account or Australia Post eParcel account). Labels are stored so they can be reprinted without re-purchasing.

Viewing and Reprinting Labels

After a label has been generated, a View Carrier Labels button appears in the order toolbar. Click it to open a popup showing all labels generated for that order.

Each label displays:

Tracking number — the carrier-assigned tracking number.
Format and date — when the label was generated and in what format.
Postage amount — the cost charged for the label (if available).
Label preview — PDF labels are previewed inline; image labels are shown directly.
Download button — download the label file for printing or archival.

Labels are stored permanently and can be viewed or reprinted at any time without calling the carrier API again or incurring additional charges.

USPS Configuration

The USPS shipping type uses the USPS REST API v3 with OAuth 2.0. To enable label generation:

Client ID and Client Secret — from the USPS Developer Portal (also used for rate quoting).
Account Type — EPS (Enterprise Payment System) or PERMIT.
Account Number — your USPS account number.
CRID — Customer Registration ID, required for label payment authorization.
MID — Mailer ID, required for label payment authorization.

USPS labels support PDF and ZPL (thermal printer) formats in 4×6 or 6×4 sizes. For international shipments, you will be prompted for customs content type and non-delivery instructions.

Australia Post Configuration

The Australia Post shipping type uses the Shipping & Tracking API for labels, which is separate from the PAC API used for rate quoting. To enable label generation:

Shipping API Key — a UUID-format API key from Australia Post (different from the PAC API key).
Shipping API Password — the password for the Shipping API key.
Account Number — your 10-digit eParcel account number (left-padded with zeros).

Australia Post labels are generated as PDF in configurable layouts: A4 with 1 or 4 labels per page, or thermal A6 for label printers. You can also choose whether to include Australia Post branding on the label.

Template Labels vs Carrier Labels

Aspect	Template Labels	Carrier Labels
Availability	All orders, always	Only when enabled and the shipping type supports it
Content	Sender/recipient addresses	Barcode, postage, tracking number
Cost	Free	Postage is purchased from the carrier
Output	HTML rendered in browser	PDF or ZPL from carrier API
Customization	Fully editable templates	Carrier-defined format
Tracking	Not included	Tracking number automatically created

Both types can be used for the same order — for example, you might use carrier labels for domestic shipments and template labels for international orders where your carrier doesn't provide label generation.

TIP

Template labels do not include postage. If you need prepaid labels with barcodes and tracking, use a shipping type that supports carrier label generation, or purchase postage separately.

For developers building custom shipping types with carrier label support, see the Shipping Types developer documentation.

Shipping Labels ​

Template Labels ​

Printing a Shipping Label ​

Shipping Label Templates ​

Creating a Template ​

Editing Template Content ​

Syntax Fields ​

Twig Variables ​

Default Template ​

Example Template ​

Carrier Labels ​

Supported Carriers ​

Enabling Carrier Labels ​

Generating a Label ​

Viewing and Reprinting Labels ​

USPS Configuration ​

Australia Post Configuration ​

Template Labels vs Carrier Labels ​