Refund/Return Download

The refund download retrieves refunds (with related payments) and line items from Shopify for processing into your ERP/Accounting/fulfillment processing package.

Shopify API

https://help.shopify.com/en/api/reference/shipping-and-fulfillment/fulfillment

Options Tab

This section describes the options and setup on the Option (File Layout) tab.

Shopify System Selector

As per all Connector Readers the Shopify reader allows you to query multiple Shopify stores. When downloading refunds this allows you to query multiple Shopify stores.

See Pull Connectors for further information.

Parameters

Each parameter listed below relates to the originating order document. This is due to the way Shopify saves the refund as a nested record to the order.

Fulfilment Status

The fulfilment status of orders to be retrieved:

• unshipped
  • Will download any orders with no shipped quantities. This is the default value.
• shipped
  • Any orders which are fully shipped.
• partial
  • Any partially shipped orders.
• any
  • All orders regardless of status.

Order Status

The order status of orders to be retrieved:

• any
  • All orders regardless of status. This is the default value.
• closed
  • Only closed orders.
• cancelled
  • Only cancelled orders.
• open
  • Only open orders.

Timespan

When working in the designer this specifies which range of orders to download.

This parameter is ignored when an integration is scheduled and instead the order create date/time is used (see below).

Created/Updated

It is highly recommended to set this parameter to 'updated'. This is because the order's updated date is updated when a fulfillment is created, using the order created date will likely skip refunds.

Field Mapping Tab

The fulfillment download includes the fields from the header (which include shipping details, payments, discounts and taxes) and the line items.

Fulfillment Header

The fulfillment header includes all fields you would find in the header such as customer, address details, but also flattens out the child relationships of Discounts, Discount Codes, Notes, Payments, Shipping, Taxes.

For each of the flattened sets of fields we return the first X number of child records. For example, for discounts we return the first 5 discounts applied to an order. We assumed that no more than 5 discounts would ever be applied to an order.

This flattened approach was taken as it typically streamlines order processing, reduces downstream transformation and consequently simplifies your integrations.

• BillTo_ Fields
  • Any field prefixed with the BillTo refer to the bill to address details for the order.
• ShipTo_
  • Any field prefixed with the ShipTo refer to the ship to address details for the order.
• Client_
  • Any field prefixed with the Client refer to the client (browser) used to complete the order.
• Customer_
  • Any field prefixed with the Customer are referring to the customer details for the order including address.
• Discount(1-5)_
  • These set of fields refer to the first 5 discounts applied to the order.
• DiscountCode(1-5)_
  • These set of fields refer to the first 5 discount codes applied to the order.
• Note(1-5)_
  • These are the first 5 notes added to the order.
• Shipping(1-3)_
  • These are the first three methods added to the order. Each set of shipping fields include the first 3 taxes applied to the shipping line.
• Taxes(1-3)_
  • These fields are the first three taxes applied to the order.
• total_line_items, total_discounts, total_shipping_price, subtotal_price, total_price, total_tax
  • Each of these fields provide both the shop (base/home) and presentment amounts and currencies. See the following Shopify page for more information on multi-currency.
    
• Refund(1-3)_
  • These fields are the first three refund (or Transactions) made.
    The fields provided in the Refund entity include everything except for those within the 'Receipt' object. If you need to access these we recommend doing a Shopify Lookups lookup in a Map transform (or wherever those fields are required).
    

Line Items

The Line Items entity includes the traditional fields such as item, description, quantity and pricing, but also the flattened set of discounts, taxes and properties.

• Discount(1-3)_ Fields
  • These set of fields refer to the first 3 discounts applied to the line.
• Tax(1-3)_ Fields
  • These set of fields refer to the first 3 taxes applied to the line.
• Property(1-5)_ Fields
  • These set of fields refer to the first 5 custom set of properties added to the line.
• price, total_discount
  • Each of these fields provide both the shop (base/home) and presentment amounts and currencies. See the following Shopify page for more information on multi-currency.

Running from a Schedule

IMan maintains a lookup table to keep track of the last date/time an refund download is performed. Each time the refund download is run, the records in this table are updated. A record is maintained for each Shopify Reader which downloads refunds.

The reason a date/time is used is due to Shopify's lack of ability to mark refunds as downloaded/prcoessed i.e. there is no facility to add a download status.

Resetting the Last Date/Time

From time-to-time there the Shopify refund download will successfully connect, but there is an error preventing a fulfillment or all refunds being integrated.

To allow the orders to be re-processed the last run date can be reset to a value in the past, which will download all the refunds matching the parameters (per above) modified after that date/time.

It is important that a filter is included in any integration to prevent duplicates (see below).

Filtering Duplicate refunds

Since the last date/time is being used to query Shopify, it can mean orders which have been already integrated with your ERP/Accounting solution are included in subsequent Read requests.