UPS Unlock

UPS Unlock enables you to generate Zonos-compliant shipments from your own shipping platform, instead of using Zonos Dashboard. By adding a specific reference number when processing UPS shipments, UPS automatically validates and updates shipment data through Zonos, including customs descriptions, HS codes, duty account numbers, tax IDs, and commodity values. This eliminates the need to configure complex rules or integrations to pass this information to your shipping platform. Instead, UPS retrieves the data directly from Zonos, reducing the risk of discrepancies or missing information while minimizing manual setup and maintenance time.

Set up UPS Unlock 

1. Contact Zonos support - Before enabling UPS Unlock, reach out to Zonos Support to ensure your UPS account is configured correctly. This process typically takes 24-48 hours to complete.
2. Enable UPS Unlock in Dashboard - Go to Zonos Dashboard → Settings → Rates → UPS and toggle UPS Unlock to Enable
3. Configure your reference numbers - At least one reference number must start with zx or zx-. As long as at least one reference starts with zx (even if the value is only zx), Zonos will scan all reference numbers to find a matching Zonos order ID or account order number.
   • Examples:
     • zxORDER123 or zx-ORDER123 (combined format with merchant order number)
     • zxorder_0jy1vh6gygcks or zx-order_0jy1vh6gygcks (combined format with Zonos order ID)
     • Reference 1: zx, Reference 2: ORDER123 (split across two reference fields)

How it works 

Once you have UPS Unlock set up, UPS shipments will reference Zonos order data. Here's how that process works:

1. UPS automatically calls Zonos to validate the order with the reference fields provided
2. Zonos validates and returns updated customs details to UPS - Zonos validates that the shipment matches the original quote by checking:
   1. Items in the shipment match those in the quote
   2. Quantities are less than or equal to the quoted amounts
   3. Part numbers match product IDs or SKUs from the quote
   4. Destination details (country/province) match the quote
3. UPS processes your shipment with compliance information
4. UPS calls Zonos to create shipment record with tracking number
5. Zonos records the shipment on the order

Reference matching 

When UPS calls Zonos with a reference like zx-ORDER123, Zonos strips the prefix and searches for the order. The value after the prefix (ORDER123 in this example) is matched against three fields on the Zonos order:

Zonos returns the most recent matching order. If no match is found, an error is returned.

Requirements

For UPS Unlock to succeed, the order must meet these requirements:

• Landed Cost Guarantee (LCG) - The order must have been created through the Zonos checkout flow with a guaranteed landed cost. Orders created outside of Zonos cannot be used with UPS Unlock.
• Matching origin/destination - The ship-from and ship-to countries must match the original quote. For shipments to Canada or Brazil, the province must also match.
• Matching products - Part numbers must match the product IDs or SKUs from the quote, and quantities cannot exceed the quoted amounts.

Error codes 

If validation fails, UPS receives an error response from Zonos. Common error codes include:

ShipStation integration 

ShipStation users can configure UPS Unlock by adding the zx prefix either upstream (via API before orders reach ShipStation) or within ShipStation using Label Messages and Automation Rules configurations. This allows the zx prefix and order ID to be included in UPS shipments processed through ShipStation, triggering UPS Unlock. After completing the initial setup steps, you can begin configuring ShipStation to work with UPS Unlock.

Adding zx upstream

If you can add the zx prefix upstream (before orders reach ShipStation), you only need to configure your Label Messages to display the zx order number:

Label Messages configuration

1. Access Label Messages settings: Navigate to Settings → Printing → Printing Setup, then click Document Options for Label
2. Configure Label Messages: In the Label Messages section, you can define up to 3 custom messages that will appear as reference numbers on UPS labels. Label Messages only accept preset values like "Custom Field 1", "Order #", etc.
3. Set your Messages to use Order Number: Set Message #1 to [Order #]. If you already have a #1, add a #2 or #3
4. Save Settings to apply your configuration

Once complete, ShipStation will automatically put your order number on your label, which includes your configured zx prefix.

Adding zx in ShipStation

If you can't add the zx prefix upstream (before orders reach ShipStation), you'll need to configure your Label Messages and Automation Rules to display the zx prefix and order number using two separate Label Messages:

Step 1: Label Messages configuration

Configure your Label Messages to display both the prefix and order number:

1. Access Label Messages settings: Navigate to Settings → Printing → Printing Setup, then click Document Options for Label
2. Configure Label Messages: In the Label Messages section, you can define up to 3 custom messages that will appear as reference numbers on UPS labels.
3. Set your Messages:
   • Set Message #1 to [Custom Field 1] (this will be populated with "zx" by automation rule)
   • Set Message #2 to [Order #] (select from dropdown)
4. Save Settings to apply your configuration

Step 2: Automation Rules configuration

After setting up your Label Messages, create an automation rule to populate Custom Field 1 with the zx prefix. Navigate to Settings → Automation → Automation Rules then click Create a Rule.

Rule for Zonos UPS orders:

1. Name: "Zonos UPS Unlock"
2. Ensure Active Rule is toggled on
3. Select Orders match these specific criteria
4. Set criteria: "International Order" = "True" AND "Carrier" + "Includes" + "UPS"

Note: Your trigger criteria may vary based on your ShipStation configuration. This is a recommended starting point - customize the conditions based on your specific workflow and preferences to ensure UPS Unlock is applied only to the appropriate orders.

1. Set actions:
   • Action Type: Select "Set Custom Field 1..."
   • Custom Field 1: zx (this sets the prefix)
2. Click Save Rule

Once complete, ShipStation will automatically populate Custom Field 1 with zx and Message #2 with the order number for international UPS orders. These will appear on your UPS labels as two separate reference lines.

Important: The Label Message configuration in ShipStation is a global change that impacts all carriers. The automation rules approach allows UPS Unlock to work seamlessly for Zonos orders while maintaining your preferred Label Messages for other shipments.