Magento V2 Credit Memo XML

The XML format documented here is used for the import of credit memos into Magento, via the Import Credit Memos to Magento V2 task.

There are three ways to raise a credit memo, chosen with the credit_memo_type element:

credit_memo_type	Meaning
RefundOrder	Refund an order. Magento calculates the credit memo totals from the order, so only the items and quantities need to be sent. Recommended
RefundInvoice	Refund an invoice. Magento calculates the credit memo totals from the invoice, so only the items and quantities need to be sent. Recommended
CreateCreditMemo	Create a standalone credit memo against an order. All of the totals must be calculated and sent yourself. This is the default when `credit_memo_type` is not supplied

Whether the refund is processed online through the payment gateway or offline is controlled by the Refund Offline setting on the task.

Refunding an Order

The minimum information required to refund an order.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfCreditMemo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CreditMemo>
    <credit_memo_type>RefundOrder</credit_memo_type>
    <order_id>5</order_id>
    <shipping_amount>5</shipping_amount>
    <items>
      <item>
        <order_item_id>5</order_item_id>
        <qty>1</qty>
      </item>
    </items>
    <comments />
  </CreditMemo>
</ArrayOfCreditMemo>

Refunding an Invoice

The minimum information required to refund an invoice.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfCreditMemo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CreditMemo>
    <credit_memo_type>RefundInvoice</credit_memo_type>
    <invoice_id>5</invoice_id>
    <shipping_amount>5</shipping_amount>
    <items>
      <item>
        <order_item_id>5</order_item_id>
        <qty>1</qty>
      </item>
    </items>
    <comments />
  </CreditMemo>
</ArrayOfCreditMemo>

Creating a Credit Memo

The minimum information required to create a standalone credit memo. Magento does not calculate the totals in this mode, so they must all be supplied and must agree with each other.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfCreditMemo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CreditMemo>
    <order_id>5</order_id>
    <invoice_id>4</invoice_id>
    <subtotal>29</subtotal>
    <subtotal_incl_tax>29</subtotal_incl_tax>
    <tax_amount>0</tax_amount>
    <grand_total>34</grand_total>
    <shipping_amount>5</shipping_amount>
    <base_subtotal>29</base_subtotal>
    <base_subtotal_incl_tax>29</base_subtotal_incl_tax>
    <base_tax_amount>0</base_tax_amount>
    <base_grand_total>34</base_grand_total>
    <base_shipping_amount>5</base_shipping_amount>
    <items>
      <item>
        <order_item_id>5</order_item_id>
        <price>29</price>
        <qty>1</qty>
        <row_total>29</row_total>
        <tax_amount>0</tax_amount>
      </item>
    </items>
    <comments />
  </CreditMemo>
</ArrayOfCreditMemo>

Credit Memo

Magento Field	XML Field	Type	Input	Notes
-	credit_memo_type	string	Optional	`RefundOrder`, `RefundInvoice` or `CreateCreditMemo`, as described above
Order	order_id*	int	Conditional	The Magento entity ID of the order being credited
Order	order/entity_id*	int	Conditional	As `order_id`
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
Invoice	invoice_id*	int	Conditional	The Magento entity ID of the invoice being credited
Invoice	invoice/entity_id*	int	Conditional	As `invoice_id`
Invoice	invoice/increment_id*	string	Conditional	The Magento invoice number
Refund Shipping	shipping_amount	decimal	Optional	The shipping amount to refund
Adjustment Refund	adjustment_positive	decimal	Optional	An amount to add to the refund
Adjustment Fee	adjustment_negative	decimal	Optional	An amount to deduct from the refund
Email Copy of Credit Memo	notify	bool	Optional	Set to true to email the credit memo to the customer
Credit Memo Comments	comments/comment/comment	string	Optional	The comment text. Send an empty `<comments />` element when there are no comments
Visible on Storefront	comments/comment/is_visible_on_front	int	Optional	`0` for false, `1` for true
-	increment_id	string	Optional	The credit memo number to use, where your Magento configuration allows it to be set

order_id*, order/entity_id*, order/increment_id*, order/external_id* - One of these is required for RefundOrder and CreateCreditMemo, to identify the order being credited
invoice_id*, invoice/entity_id*, invoice/increment_id* - One of these is required for RefundInvoice, to identify the invoice being credited

The following totals are only required when credit_memo_type is CreateCreditMemo. For the two refund types Magento calculates them from the order or invoice and returns them in the Success File.

Magento Field	XML Field	Type	Notes
Subtotal	subtotal	decimal	In the order currency
Subtotal (Incl. Tax)	subtotal_incl_tax	decimal
Tax	tax_amount	decimal
Shipping	shipping_amount	decimal
Shipping (Incl. Tax)	shipping_incl_tax	decimal
Discount	discount_amount	decimal
Grand Total	grand_total	decimal
Subtotal	base_subtotal	decimal	In the store's base currency. Each of the fields above has a `base_` equivalent
Subtotal (Incl. Tax)	base_subtotal_incl_tax	decimal
Tax	base_tax_amount	decimal
Shipping	base_shipping_amount	decimal
Grand Total	base_grand_total	decimal

Items

Send one item per order line to credit.

Magento Field	XML Field	Type	Input	Notes
Product	order_item_id*	int	Conditional	The Magento order item ID of the line being credited
Product	sku*	string	Conditional	The SKU of the line being credited
Qty to Refund	qty	decimal	Required
Price	price*	decimal	Conditional
Row Total	row_total*	decimal	Conditional
Tax Amount	tax_amount*	decimal	Conditional
Price (Incl. Tax)	price_incl_tax	decimal	Optional
Row Total (Incl. Tax)	row_total_incl_tax	decimal	Optional
Discount Amount	discount_amount	decimal	Optional
-	name	string	Optional
-	description	string	Optional
-	product_id	int	Optional
-	base_price	decimal	Optional	The `base_` equivalents of the item totals are also supported

order_item_id*, sku* - One of these is required to identify each line being credited
price*, row_total*, tax_amount* - Required for CreateCreditMemo. Magento calculates these for RefundOrder and RefundInvoice

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

<CreditMemo>
  <credit_memo_type>RefundInvoice</credit_memo_type>
  <errors>
    <error>
      <name>Pre-Validation</name>
      <description>The invoice_id, invoice.entity_id, invoice.increment_id or invoice.external_id must be provided when refunding an invoice</description>
    </error>
  </errors>
</CreditMemo>