Shopify Refund XML (GraphQL)

The XML format documented here is used for the import of refunds into Shopify, via the Import Refunds task.

We recommend that the ZynkExternalId field be populated with the unique ID of the refund from the external system. Zynk uses this field to track refunds already imported, to prevent duplicates being created in Shopify. The 'Prevent Reprocessing' setting is enabled by default on this task.

The task always creates a new refund against an existing order. Existing refunds cannot be updated.

XML

Any fields not documented below are ignored by the task. Examples of where in the XML the fields should appear are shown in the samples below.

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund IdempotencyKey="e5a0e56c-8137-f720-8e2a-0b9b8fe7ef29">
    <ZynkExternalId>CN-10523</ZynkExternalId>
    <Currency>GBP</Currency>
    <DiscrepancyReason>OTHER</DiscrepancyReason>
    <Note>Product not fit for purpose</Note>
    <Notify>false</Notify>
    <Order>
      <Id>gid://shopify/Order/6022747717721</Id>
      <Name>#1116</Name>
    </Order>
    <ProcessedAt>2026-01-01T09:00:00</ProcessedAt>
    <RefundDuties>
      <RefundDuty>
        <DutyId>gid://shopify/Duty/123456789</DutyId>
        <RefundType>FULL</RefundType>
      </RefundDuty>
    </RefundDuties>
    <RefundLineItems>
      <Record>
        <LineItem>
          <Sku>TFD0121</Sku>
        </LineItem>
        <Location>
          <Name>Newcastle</Name>
        </Location>
        <Quantity>1</Quantity>
        <RestockType>RETURN</RestockType>
      </Record>
    </RefundLineItems>
    <Shipping>
      <Amount>1.00</Amount>
      <FullRefund>false</FullRefund>
    </Shipping>
    <Transactions>
      <Record>
        <AmountSet>
          <PresentmentMoney>
            <Amount>13.00</Amount>
          </PresentmentMoney>
        </AmountSet>
        <Gateway>shopify_payments</Gateway>
        <Kind>REFUND</Kind>
        <ParentTransaction>
          <PaymentId>rMoy2Y82UMo8vEkYxDsNPLaWq</PaymentId>
        </ParentTransaction>
      </Record>
    </Transactions>
  </Refund>
</Refunds>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the Refunds schema is used above as a reference of where fields should be in the object model.

Refund

The following information can be provided at the refund header level.

Shopify Field	XML Field	Type	Input	Notes
-	ZynkExternalId	string	Optional	Stored in Zynk's internal DB and used in conjunction with the 'Prevent Reprocessing' setting
-	IdempotencyKey (attribute)	string	Optional	Sent to Shopify as the idempotency key for the `refundCreate` mutation, so a retried request cannot create the refund twice. A new GUID is generated if not provided
currency	Currency	string	Optional	Defaults to the presentment currency of the order. If provided, it must match the order's presentment currency, e.g. `GBP`
discrepancyReason	DiscrepancyReason	enum	Optional	Reason for a difference between the refunded amount and the value of the refunded items. Options: `CUSTOMER`, `DAMAGE`, `OTHER`, `RESTOCK`
note	Note	string	Optional
notify	Notify	bool	Optional	Whether Shopify sends a refund notification to the customer
orderId	Order/Id	string	Dependant	Required if `Order/Name` is not provided. Accepts a GraphQL ID (`gid://shopify/Order/123`) or the numeric order ID. Takes precedence over `Order/Name`
orderId	Order/Name	string	Dependant	Required if `Order/Id` is not provided, e.g. `#1001`
processedAt	ProcessedAt	datetime	Optional	The date the refund was processed, e.g. `2026-01-01T09:00:00`

The record fails if no order is found with the given ID or name.

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund IdempotencyKey="e5a0e56c-8137-f720-8e2a-0b9b8fe7ef29">
    <ZynkExternalId>CN-10523</ZynkExternalId>
    <Currency>GBP</Currency>
    <DiscrepancyReason>OTHER</DiscrepancyReason>
    <Note>Product not fit for purpose</Note>
    <Notify>false</Notify>
    <Order>
      <Id>gid://shopify/Order/6022747717721</Id>
      <Name>#1116</Name>
    </Order>
    <ProcessedAt>2026-01-01T09:00:00</ProcessedAt>
  </Refund>
</Refunds>

Refund Duties

Used to refund duties charged on the order. Multiple RefundDuty elements can be provided.

Shopify Field	XML Field	Type	Input	Notes
dutyId	DutyId	string	Required	GraphQL ID of the duty, e.g. `gid://shopify/Duty/123`
refundType	RefundType	enum	Optional	Options: `FULL`, `PROPORTIONAL`

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund>
    <RefundDuties>
      <RefundDuty>
        <DutyId>gid://shopify/Duty/123456789</DutyId>
        <RefundType>FULL</RefundType>
      </RefundDuty>
    </RefundDuties>
  </Refund>
</Refunds>

Refund Line Items

The order lines being refunded. Each line must be matched to an order line using LineItem/Id or LineItem/Sku. Only the first 100 lines of the order are checked.

Shopify Field	XML Field	Type	Input	Notes
lineItemId	LineItem/Id	string	Dependant	Order line item ID, e.g. `gid://shopify/LineItem/123`. Required if `LineItem/Sku` is not provided. Takes precedence over `LineItem/Sku`, and must belong to the order
lineItemId	LineItem/Sku	string	Dependant	Required if `LineItem/Id` is not provided. Matched to the first order line with the same SKU
locationId	Location/Id	string	Optional	The location to restock the items to. Must be a GraphQL ID (`gid://shopify/Location/123`)
locationId	Location/Name	string	Optional	Used to look up the location ID if `Location/Id` is not provided. The record fails if no location is found
quantity	Quantity	int	Required
restockType	RestockType	enum	Optional	Options: `CANCEL`, `LEGACY_RESTOCK`, `NO_RESTOCK`, `RETURN`

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund>
    <RefundLineItems>
      <Record>
        <LineItem>
          <Id>gid://shopify/LineItem/14582187720793</Id>
        </LineItem>
        <Location>
          <Id>gid://shopify/Location/16144367705</Id>
        </Location>
        <Quantity>1</Quantity>
        <RestockType>RETURN</RestockType>
      </Record>
      <Record>
        <LineItem>
          <Sku>TFD0121</Sku>
        </LineItem>
        <Location>
          <Name>Newcastle</Name>
        </Location>
        <Quantity>2</Quantity>
        <RestockType>NO_RESTOCK</RestockType>
      </Record>
    </RefundLineItems>
  </Refund>
</Refunds>

Shipping

The shipping amount to refund. Provide either Amount or FullRefund.

Shopify Field	XML Field	Type	Input	Notes
shipping.amount	Amount	decimal	Optional	The amount of shipping to refund
shipping.fullRefund	FullRefund	bool	Optional	Set to `true` to refund the full shipping amount

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund>
    <Shipping>
      <Amount>1.00</Amount>
      <FullRefund>false</FullRefund>
    </Shipping>
  </Refund>
</Refunds>

Transactions

The money movements for the refund. Without a transaction the refund is recorded against the order but no money is returned to the customer.

Shopify Field	XML Field	Type	Input	Notes
amount	AmountSet/PresentmentMoney/Amount	decimal	Required	Amount in the order's presentment currency
gateway	Gateway	string	Required	The payment gateway, e.g. `shopify_payments` or `manual`
kind	Kind	enum	Required	Usually `REFUND`. Options: `AUTHORIZATION`, `CAPTURE`, `CHANGE`, `EMV_AUTHORIZATION`, `REFUND`, `SALE`, `SUGGESTED_REFUND`, `VOID`
orderId	Order/Id	string	Optional	Defaults to the order of the refund
parentId	ParentTransaction/Id	string	Dependant	GraphQL ID of the original order transaction being refunded, e.g. `gid://shopify/OrderTransaction/123`. Required if `ParentTransaction` is provided without `PaymentId`
parentId	ParentTransaction/PaymentId	string	Dependant	Used to find the parent transaction on the order (first 100 transactions) if `ParentTransaction/Id` is not provided. The record fails if no match is found

<?xml version="1.0" encoding="utf-8"?>
<Refunds>
  <Refund>
    <Transactions>
      <Record>
        <AmountSet>
          <PresentmentMoney>
            <Amount>13.00</Amount>
          </PresentmentMoney>
        </AmountSet>
        <Gateway>shopify_payments</Gateway>
        <Kind>REFUND</Kind>
        <ParentTransaction>
          <Id>gid://shopify/OrderTransaction/7696928014425</Id>
        </ParentTransaction>
      </Record>
    </Transactions>
  </Refund>
</Refunds>