UPS WorldShip Export – Configuration

Allowed Values

String.

Default

The first Line Item’s vendor.

Example

"Cans of our Beer, Clothing"

When remove_us_phone_country_code is true, a fallback written as +1 plus 10 digits is exported as the bare 10 digits like any other Ship-to phone.

Allowed Values

String.

Default

Absent.

Example

"+1 1234567890"

This is the failed-notification address for UPS Access Point shipments, not a general contact address for the shipment. The recipient email on the shipment comes from the Order, with fallback_shipping_email setting as the fallback.

Allowed Values

Email string.

Default

Absent.

Example

"[email protected]"

Allowed Values

true, false

Default

false

Example

true

• xml_auto_import – the UPS XML Auto Import format (<OpenShipments>). WorldShip watches a folder and processes new files hands-off, printing labels automatically. This is the default. Every setting on this page works in this format.
• xml_batch_import – the UPS XML Batch Import format (<Shipments>). For bringing shipments in through the WorldShip Import-Export tab – imported as a batch, or recalled one at a time with Keyed Import. This format writes a <Good> for every Line Item of the Order (unless include_goods is false) and wraps the references in <ReferenceNumbers>. It writes no <Package> elements, no Quantum View Notify block and no Access Point block. Enable include_shipment_key together with it so each shipment can be recalled by the Order name.

Settings that have no effect in XML Batch Import:

• split_packages_per_unit, package_dimensions_from_variant_metafields, package_weights_from_order_metafield, weight_unit, fail_order_when_package_data_missing, number_of_packages_from_quantity – no <Package> elements are written in this format
• include_quantum_view_notify_block and the other Quantum View Notify keys – XML Auto Import only
• hold_at_access_point_from_address2_marker and Email – Hold at UPS Access Point is XML Auto Import only
• use_shipping_line_mapping – the built-in list is never consulted in this format

If WorldShip prints labels by itself from a watched folder, keep the default. If you open WorldShip and import shipments from the Import-Export tab, you need xml_batch_import.

Allowed Values

xml_auto_import, xml_batch_import

Default

xml_auto_import

Example

xml_batch_import

Allowed Values

String.

Default

Absent.

Example

"A11B22"

Allowed Values

String.

Default

Absent.

Example

"88AE89"

Allowed Values

String.

Default

Absent.

Example

"86E898"

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Object of ElementName: "namespace.key" pairs. Typical element names: Length, Width, Height.

Default

Absent – no dimensions written.

Example

{
  "Length": "custom.length",
  "Width": "custom.width",
  "Height": "custom.height"
}

Does not apply to package_weights_from_order_metafield, whose values are already in the Merchant’s own unit.

Allowed Values

"kg", "lb"

Default

"kg"

Example

"lb"

Allowed Values

Any UPS WorldShip package-type code (string), for example "CP" (customer packaging).

Default

"CP"

Example

"CP"

• With split_packages_per_unit on, a purchased Variant missing any configured dimension or having no weight; the message names the SKU and the missing fields. When disabled, missing dimensions are simply omitted from the package.
• With package_weights_from_order_metafield set, an Order whose packing Metafield is missing, empty, or not a list of positive numbers; the message names the Metafield, and the Order is never split instead. When disabled, the Order is exported without the Metafield packages – split per unit when split_packages_per_unit is on, otherwise without <Package> elements.

The failed Orders appear on the Matrixify Export job and in its results file – they are never sent to WorldShip, so WorldShip has nothing to show for them.

XML Auto Import only – in XML Batch Import there is no package data to check.

Allowed Values

true, false

Default

false

Example

true

Each value becomes its own <Package> with the PackageType, the value as its <Weight>, and the references – the same references on every package of the Order. <NumberOfPackages> is the package count. PackageType, the shipment weight and the references are left out of <ShipmentInformation>, because WorldShip rejects a shipment that has them in both places:

<Package>
  <PackageType>CP</PackageType>
  <Weight>41</Weight>
  <Reference1>1009</Reference1>
  <Reference2>If damaged, return to sender</Reference2>
</Package>
<Package>
  <PackageType>CP</PackageType>
  <Weight>21.5</Weight>
  <Reference1>1009</Reference1>
  <Reference2>If damaged, return to sender</Reference2>
</Package>

This takes precedence over split_packages_per_unit. An Order without valid packing data falls back to splitting per unit, or to a single shipment-level weight when splitting is off – unless fail_order_when_package_data_missing is true, then that Order fails and is never split.

The Metafield holds the list of weights in either of two forms:

• a JSON array – [41.0, 21.5], or Shopify’s list.number_decimal form ["41.0", "21.5"];
• text split on every comma – 41.0, 21.5 or 41.0,21.5. An empty entry between or after commas is skipped, so 41.0, 21.5, and 41,,5 are fine.

Each entry is read as the one number it contains, with a dot as the decimal separator – the same reading a list.number_decimal Metafield gets when imported from a file. Text around the number is ignored (41 kg is 41). The rules that follow from this:

• A comma always separates entries. 41,5 is two packages of 41 and 5, not one of 41.5; 1,234.5 is two packages of 1 and 234.5. Write 1234.5.
• Write a leading zero: .5 is read as 5, not 0.5. Write 0.5.
• An entry with no number, or with more than one (4_1, 0x1A, 1e400, 4.1.5), is invalid packing data.
• A weight is positive: 0, a negative, and one that rounds to 0 at 2 decimals (0.004) are invalid.
• In the JSON form every element must be a weight: [41.0, null] and [41.0, ""] are invalid, rather than shipping one label short.
• More than 200 packages is invalid.

The weights keep the Metafield’s own unit – weight_unit does not apply – are rounded to 2 decimal places, and drop trailing zeros (41.0 is written as 41).

An Order whose Metafield is missing, empty, or holds anything that is not a positive number never gets a partial set of packages. When fail_order_when_package_data_missing is true, it is excluded from the file and reported as a failed item. The failure message tells the two cases apart: an unfilled Metafield reads “is not filled in … Fill it on the Order”, while one holding something unreadable quotes the value back – “holds [41 and 21.5], which is not a list of positive package weights … Correct it on the Order”.

The namespace cannot be an app-owned one (app--...): Shopify reserves those for the app that owns them, so such a key resolves to nothing on every Order. A key not spelled namespace.key (a bare package_weights) cannot address a Metafield either, and every Order then reads as unfilled – check this value first when every Order fails.

Confirm that the first file imports into WorldShip before relying on it.

Allowed Values

A string in the form namespace.key naming an Order Metafield.

Default

Absent – no packages from the Order.

Examples

"custom.package_weights"

Set as a single source string, or as a JSON object joining several sources into one value.

Allowed Values

Single source – one of:

• "order_name" – the Order name (for example #EZ1019),
• "order_id" – the Shopify Order ID,
• "sku" – the SKU; at package level the package’s own Line Item SKU, at shipment level the first Line Item’s SKU,
• "text:<text>" – a fixed text written on every shipment, for example "text:If damaged, return to sender". A leading # is stripped from it too when remove_number_sign_from_references is true,
• "customer_metafield:namespace.key" – the value of that Customer Metafield,
• "blank" – no value at all. The element is still written, but empty, so a WorldShip import map that expects to find the field keeps finding it. This is how a shop switches off the Reference 1 (Order name) and Reference 2 (Order ID) defaults without leaving those values in the feed. Use "blank" for an intentionally empty Reference, not "text:" with nothing after it.

Combined sources – a JSON object with:

• parts – array of the same source values, written in the order listed,
• separator – string written between the parts. Optional; if not specified, defaults to " / " (forward slash with spaces on both sides),
• max_length – integer. The parts are joined first, then the whole value is cut to this many characters. Optional; if not specified, defaults to 35.

Default

Order name.

Examples

"customer_metafield:custom.customer_number"

{ "parts": ["order_name", "customer_metafield:custom.customer_number"], "separator": " | ", "max_length": 20 }

Set as a single source string, or as a JSON object joining several sources into one value.

Allowed Values

Single source – one of:

• "order_name" – the Order name (for example #EZ1019),
• "order_id" – the Shopify Order ID,
• "sku" – the SKU; at package level the package’s own Line Item SKU, at shipment level the first Line Item’s SKU,
• "text:<text>" – a fixed text written on every shipment, for example "text:If damaged, return to sender". A leading # is stripped from it too when remove_number_sign_from_references is true,
• "customer_metafield:namespace.key" – the value of that Customer Metafield,
• "blank" – no value at all. The element is still written, but empty, so a WorldShip import map that expects to find the field keeps finding it. This is how a shop switches off the Reference 1 (Order name) and Reference 2 (Order ID) defaults without leaving those values in the feed. Use "blank" for an intentionally empty Reference, not "text:" with nothing after it.

Combined sources – a JSON object with:

• parts – array of the same source values, written in the order listed,
• separator – string written between the parts. Optional; if not specified, defaults to " / " (forward slash with spaces on both sides),
• max_length – integer. The parts are joined first, then the whole value is cut to this many characters. Optional; if not specified, defaults to 35.

Default

Order ID.

Examples

"sku"

"text:If damaged, return to sender"

{ "parts": ["sku", "order_name"], "separator": ",", "max_length": 20 }

Set as a single source string, or as a JSON object joining several sources into one value.

Allowed Values

Single source – one of:

• "order_name" – the Order name (for example #EZ1019),
• "order_id" – the Shopify Order ID,
• "sku" – the SKU; at package level the package’s own Line Item SKU, at shipment level the first Line Item’s SKU,
• "text:<text>" – a fixed text written on every shipment, for example "text:If damaged, return to sender". A leading # is stripped from it too when remove_number_sign_from_references is true,
• "customer_metafield:namespace.key" – the value of that Customer Metafield,
• "blank" – no value at all. The element is still written, but empty, so a WorldShip import map that expects to find the field keeps finding it. This is how a shop switches off the Reference 1 (Order name) and Reference 2 (Order ID) defaults without leaving those values in the feed. Use "blank" for an intentionally empty Reference, not "text:" with nothing after it.

Combined sources – a JSON object with:

• parts – array of the same source values, written in the order listed,
• separator – string written between the parts. Optional; if not specified, defaults to " / " (forward slash with spaces on both sides),
• max_length – integer. The parts are joined first, then the whole value is cut to this many characters. Optional; if not specified, defaults to 35.

Default

Not written. <Reference3> appears only when this key is configured.

Examples

"order_name"

{ "parts": ["order_id", "order_name"], "separator": " , ", "max_length": 10 }

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Object of ElementName: "namespace.key" pairs. Typical element names: CustomerID, LocationID.

Default

Absent – no CustomerID / LocationID written.

Example

{
  "CustomerID": "custom.customer_number",
  "LocationID": "custom.customer_number"
}

The UPS service is chosen in this order:

• ServiceType, when set – forces one service for every Order
• service_type_by_shipping_line, when the Order’s rate name is in the map
• the built-in UPS rate name list, unless use_shipping_line_mapping is false
• the regional default

Allowed Values

Any UPS Service Type – see UPS Service Codes, UPS Service Codes for Freight Shipments, UPS Service Codes for UPS Mail Innovations Shipments and UPS Service Codes and Weight Limits for UPS SurePost Shipments.

Default

Derived automatically from destination and shipping line.

Example

"GND"

This map is consulted BEFORE the built-in UPS rate name list, so a shop can override a built-in name with its own meaning. It is NOT switched off by use_shipping_line_mapping: false – that setting only affects the built-in list.

Matching ignores letter case, punctuation and the (R) symbol, so “Ground”, “GROUND” and “Ground(R)” all match the same entry.

Example

"service_type_by_shipping_line": {"Ground": "GND","3 Day Air": "3DS"}

Allowed Values

Region object with string values for keys GB, DE_FR_NL, EU, WW.

Default

Absent – derived for EU B2C.

Example

{
  "GB": "GB_Youemp",
  "DE_FR_NL": "EU_Youemp",
  "EU": "EU_Einzelsendung",
  "WW": "WW_Youemp"
}

Allowed Values

true, false

Default

true

Example

false

Allowed Values

true, false

Default

false

Example

true

Allowed Values

UPS unit-of-measure code (string), for example "PC" (pieces) or "CS" (cases).

Default

"PC"

Example

"CS"

A Canadian store selling in USD to the United States then exports USD on those shipments and CAD on Canadian ones. The currency code and the amounts always come from the same source, so the declared customs value is never mixed up. When an Order has no separate paid currency — a store that prices every Market in its store currency — the whole file stays in the store currency, exactly as before.

Do not combine with item_substitutions_by_sku unless the substitution prices are given in the currency the file declares.

Allowed Values

true, false

Default

false

Example

true

Allowed Values

"SHP" (shipper), "REC" (receiver), "TP" (third party). For "TP", also set ThirdPartyIntermediary.

Default

"SHP"

Example

"TP"

Allowed Values

"REC" (receiver), "SHP" (shipper), "TP" (third party).

Default

"REC"

Example

"SHP"

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Array of any of "Ship", "Exception", "Delivery", "InTransit".

Default

["Ship"]

Example

["Exception", "Delivery"]

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Email string.

Default

Absent.

Example

"[email protected]"

Allowed Values

true, false

Default

true

Example

false

Each key is the element name — PartNumber or DescriptionOfGood — and each value points at the Metafield to read: product_metafield:<namespace.key> for a Product Metafield, or variant_metafield:<namespace.key> for a Variant Metafield.

A mapped element is written from the Metafield only: when the Metafield is empty, the element is written empty instead of falling back to the SKU or the title. The value is written exactly as entered, with accented characters converted to plain letters, because WorldShip expects plain text. Elements that are not mapped keep their normal source.

Allowed Values

JSON object consisting of PartNumber and DescriptionOfGood keys.

Default

Part Number is the Variant SKU, Description of Goods is the Line Item title.

Example

{
  "PartNumber": "product_metafield:ups.part_number",
  "DescriptionOfGood": "product_metafield:ups.description_of_goods"
}

How the lines are combined:

• Lines combine only when every exported customs element except the quantity and the unit price is exactly the same: Part Number, Description of Good, Tariff Code (Harmonized System code), Country of Origin, the unit of measure and currency, and any values mapped from Metafields via goods_elements_from_metafields.
• A line without a Tariff Code never combines – an unclassified item always keeps its own line.
• The combined line carries the summed quantity and a unit price of total value divided by total units, written with up to 6 decimal places – UPS WorldShip’s own Unit Price field format – so quantity times unit price still equals the original line values added together. Whenever the averaged price fits in 2 decimals (always the case when the combined lines share one price), the plain 2-decimal price is written. For example, 1 unit at 29.82 + 2 units at 31.24 becomes one line: 3 units at 30.766667 = 92.30.
• The line order is kept – the combined line takes the position of its first item.
• A group whose summed quantity would not fit WorldShip’s 4-digit Units field (over 9999), or whose quantities sum to zero, is left uncombined.
• Combining runs after SKU substitutions (item_substitutions_by_sku), VAT removal and the paid-currency selection (use_presentment_currency), so lines are always grouped by the final exported values. Works the same in both XML formats.

Note: with the default SKU-based PartNumber, different Variants keep their own lines. Sizes of one product combine when PartNumber and DescriptionOfGood come from Product Metafields via goods_elements_from_metafields (or when their SKUs are equal or blank).

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

true

Example

false

Allowed Values

String, typically "0" or "".

Default

"0"

Example

""

Allowed Values

String (for example "", "SC"), or a region object with keys GB, DE_FR_NL, EU, WW.

Default

"SC" for B2C EU shipments, empty otherwise.

Example

{
  "GB": "",
  "DE_FR_NL": "SC",
  "EU": "",
  "WW": ""
}

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

By default Address 2 is written only when the address has a second line, and Address 3 is not written at all. Shopify collects only two address lines, so Address 3 is always empty — it exists as the placeholder that some WorldShip import maps expect to find.

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

The Customer gets the UPS “ready for pickup” email at the Order email, or at fallback_shipping_email when the Order has none. If that email cannot be delivered, UPS sends a notice to the Email address.

Use it together with remove_access_point_marker_from_address2, and map the Access Point shipping rate name in service_type_by_shipping_line. XML Auto Import only.

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Any email string.

Default

Absent.

Example

"[email protected]"

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

Allowed Values

true, false

Default

false

Example

true

Allowed Values

Object; see the sub-fields table.

Default

Absent.

Example

{
  "CompanyOrName": "Company Name",
  "Attention": "Contact Person",
  "Address1": "123 Main St",
  "CountryTerritory": "US",
  "PostalCode": "12345",
  "CityOrTown": "City Name",
  "StateProvinceCounty": "FL",
  "Telephone": "5551234567",
  "UpsAccountNumber": "ABC123"
}

Allowed Values

Object mapping "OriginalSKU" to an array of substitute item objects.

Default

Absent.

Example

{
  "ORIGINAL_SKU": [
    {
      "sku": "REPLACEMENT_SKU",
      "price": 10.0,
      "quantity": 1,
      "title": "Replacement Item",
      "harmonized_system_code": "650500",
      "country_code_of_origin": "US"
    }
  ]
}