Magento V2 Invoice XML

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

An invoice 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 invoice. If no items collection is sent, all outstanding items on the order are invoiced.

Sample XML

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Invoice>
    <external_id>98353</external_id>
    <order>
      <!-- At least one of the following must be provided to identify the order to invoice -->
      <entity_id>4</entity_id>
      <increment_id>000000004</increment_id>
      <external_id>185754</external_id>
    </order>
    <capture>false</capture>
    <items>
      <item>
        <sku>WSH12-32-Purple</sku>
        <qty>1</qty>
      </item>
    </items>
    <notify>false</notify>
    <appendComment>false</appendComment>
    <comments>
      <comment>
        <comment>Invoiced by Zynk</comment>
        <is_visible_on_front>1</is_visible_on_front>
      </comment>
    </comments>
  </Invoice>
</ArrayOfInvoice>

Invoice

Magento Field	XML Field	Type	Input	Notes
Order	order/entity_id*	int	Conditional	The Magento entity ID of the order to invoice
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 invoice
Amount	capture	bool	Optional	Set to true to capture the payment as well as raising the invoice. Only applies to payment methods which support online capture
Email Copy of Invoice	notify	bool	Optional	Set to true to email the invoice to the customer
-	appendComment	bool	Optional	Set to true to include the comment in the email sent to the customer
Invoice Comments	comments/comment/comment	string	Optional	The comment text. Note that invoices take a `comments` collection, unlike shipments which take a single `comment` element
Visible on Storefront	comments/comment/is_visible_on_front	int	Optional	`0` for false, `1` for true
Notify Customer by Email	comments/comment/is_customer_notified	int	Optional	`0` for false, `1` for true
-	increment_id	string	Optional	The invoice number to use, where your Magento configuration allows it to be set

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

Items

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

Magento Field	XML Field	Type	Input	Notes
Product	sku*	string	Conditional	The SKU of the order line to invoice
Product	order_item_id*	int	Conditional	The Magento order item ID of the line to invoice
Qty to Invoice	qty	decimal	Required

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

<Invoice>
  <items>
    <item>
      <sku>WSH12-32-Purple</sku>
      <qty>1</qty>
    </item>
  </items>
</Invoice>

The remaining fields on the invoice and its items - subtotal, grand_total, tax_amount, shipping_amount, the base_* equivalents and the currency and rate fields - are populated by Magento when the invoice is raised and returned in the Success File. There is no need to send them, as Magento calculates the invoice totals from the order.

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

<Invoice>
  <order>
    <increment_id>000000004</increment_id>
  </order>
  <items>
    <item>
      <sku>24-MB01</sku>
      <qty>1</qty>
    </item>
  </items>
  <errors>
    <error>
      <name>Error</name>
      <description>No item with sku 24-MB01 was found on order 000000004</description>
    </error>
  </errors>
</Invoice>