Magento V2 Shipment XML

The XML format documented here is used for the import of shipments into Magento, via the Import Shipments to Magento V2 task.

A shipment is always raised against an existing order in Magento, so the only data required is enough to identify the order, and optionally the items and quantities to ship. If no items collection is sent, all items on the order are shipped.

To add tracking information to a shipment which already exists in Magento, use Magento V2 Tracking XML instead.

Sample XML

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfShipment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Shipment>
    <external_id>9814</external_id>
    <order>
      <!-- At least one of the following must be provided to identify the order to ship -->
      <entity_id>4</entity_id>
      <increment_id>000000004</increment_id>
      <external_id>1</external_id>
    </order>
    <!-- If no items collection is provided, all items on the order will be shipped -->
    <items>
      <item>
        <sku>WSH12-32-Purple</sku>
        <qty>1</qty>
      </item>
    </items>
    <tracks>
      <track>
        <track_number>abcd-1234</track_number>
        <title>DHL Next Day Shipping</title>
        <carrier_code>DHL</carrier_code>
      </track>
    </tracks>
    <comment>
      <comment>Leave by the door</comment>
      <is_visible_on_front>1</is_visible_on_front>
    </comment>
    <notify>false</notify>
    <append_comment>false</append_comment>
  </Shipment>
</ArrayOfShipment>

Shipment

Magento Field	XML Field	Type	Input	Notes
Order	order/entity_id*	int	Conditional	The Magento entity ID of the order to ship
Order	order/increment_id*	string	Conditional	The Magento order number, e.g. `000000004`
Order	order/external_id*	string	Conditional	The `external_id` the order was exported with. Zynk looks the order up in its internal DB
Order	order_id*	int	Conditional	As `order/entity_id`, at the top level of the shipment
Email Copy of Shipment	notify	bool	Optional	Set to true to email the shipment to the customer
-	append_comment	bool	Optional	Set to true to include the comment in the email sent to the customer
Shipment Comments	comment/comment	string	Optional	The comment text
Visible on Storefront	comment/is_visible_on_front	int	Optional	`0` for false, `1` for true
-	increment_id	string	Optional	The shipment number to use, where your Magento configuration allows it to be set
Total Quantity	total_qty	decimal	Optional
Total Weight	total_weight	decimal	Optional
-	shipping_label	string	Optional

order/entity_id*, order/increment_id*, order/external_id*, order_id* - One of these is required to identify the order being shipped

Items

Send one item per order line to ship. Omit the whole items collection to ship everything on the order.

Magento Field	XML Field	Type	Input	Notes
Product	sku*	string	Conditional	The SKU of the order line to ship
Product	order_item_id*	int	Conditional	The Magento order item ID of the line to ship
Qty to Ship	qty	decimal	Required
-	name	string	Optional
-	description	string	Optional
-	price	decimal	Optional
-	row_total	decimal	Optional
-	weight	decimal	Optional
-	product_id	int	Optional
-	additional_data	string	Optional

sku*, order_item_id* - One of these is required to identify each line being shipped

Tracks

Tracking numbers to add to the shipment, sent in a tracks collection.

Magento Field	XML Field	Type	Input	Notes
Number	track_number	string	Required	The tracking number from the carrier
Title	title	string	Required	The description shown to the customer, e.g. `DHL Next Day Shipping`
Carrier	carrier_code	string	Required	The Magento carrier code, e.g. `dhl`, `fedex`, `ups`, or `custom`
-	description	string	Optional
-	qty	decimal	Optional
-	weight	decimal	Optional

<Shipment>
  <tracks>
    <track>
      <track_number>abcd-1234</track_number>
      <title>DHL Next Day Shipping</title>
      <carrier_code>dhl</carrier_code>
    </track>
  </tracks>
</Shipment>

Common Fields

The following fields are supported on every record we import into Magento. They are used by Zynk rather than sent to Magento.

XML Field	Type	Input	Notes
external_id	string	Optional	The unique ID of the record in the external system. Stored in Zynk's internal DB and used to track records already imported. Required when the Prevent Reprocessing setting is enabled on the task
store_code	string	Optional	The store view code to send this record to, overriding the Store View Code setting on the task for this record only
match	element	Optional	Match an existing record on a `field` and `value` other than the default. See Matching Records in Magento v2
matches	element	Optional	As `match`, but matching on more than one field. See Matching Records in Magento v2

Errors

Records which fail to import are written to the Fail File in the same format as the input file, with the reason for the failure added in an errors element. There is no need to send this element yourself.

The name of each error tells you at which stage the record failed:

Name	Meaning
Pre-Validation	Zynk checked the record before sending it and found a problem, e.g. a required field is missing or a related record could not be found. The record was not sent to Magento
Prevent Reprocessing	A record with the same `external_id` has already been imported, and the Prevent Reprocessing setting is enabled on the task
Error	Magento rejected the record, or Zynk could not match the record to the data already in Magento. The `description` contains the message returned by Magento
Upload Error	An unexpected error occurred while sending the record to Magento

<Shipment>
  <order>
    <increment_id>000000004</increment_id>
  </order>
  <items>
    <item>
      <sku>24-MB01</sku>
      <qty>2</qty>
    </item>
  </items>
  <errors>
    <error>
      <name>Error</name>
      <description>The qty specified for the order item with sku 24-MB01 exceeds the quantity that can be shipped: 1</description>
    </error>
  </errors>
</Shipment>