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, and the format the Export has always produced.
  Settings that have no effect in XML Auto Import:
  • package_weights_from_order_metafield – the auto-import format keeps its split_packages_per_unit behaviour and ignores this key
• 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>. Per-package weights can be added to each shipment from an Order Metafield with package_weights_from_order_metafield – this is the only way <Package> elements appear in this format. 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 – there is no per-unit splitting in this format; <Package> elements come only from package_weights_from_order_metafield
  • weight_unit – Line Item weight is written or converted; weights from package_weights_from_order_metafield are written in the Metafield’s own unit
  • fail_order_when_package_data_missing – has effect only together with package_weights_from_order_metafield; without that key there is no package data to check
  • include_quantum_view_notify_block – the QVN block is XML Auto Import only
  • Email – only the Access Point notification address, 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. When disabled, such an Order is exported without a Packages element.
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.

Allowed Values

true, false

Default

false

Example

true

<Packages>
  <Package>
    <Weight>41</Weight>
  </Package>
  <Package>
    <Weight>21.5</Weight>
  </Package>
</Packages>

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 gets no Packages element at all – never a partial one – or, when fail_order_when_package_data_missing is true, 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.

Unlike split_packages_per_unit, this does not move PackageType or the references out of <ShipmentInformation>: the <Package> elements carry only <Weight>. UPS documents a “conflicting fields” rule for XML Auto Import when per-package and shipment-level data appear together; whether XML Batch Import applies it to a weight-only <Package> is unverified. Confirm that the first file imports into WorldShip with the references still on the label before relying on it.

Allowed Values

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

Default

Absent – no Packages element is written.

Example

"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,
• "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.

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,
• "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.

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"

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

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

"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

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

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"
    }
  ]
}