Order Download

The order download retrieves orders (with related payments) and line items from Shopify for processing into your ERP/Accounting/Order processing package.

Shopify API

https://shopify.dev/docs/admin-api/rest/reference/orders/order

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 orders this allows you to query multiple Shopify stores.

See Pull Connectors for further information.

Parameters

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).

Field Mapping Tab

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

Order Header

The order 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.
  • Payment(1-3)_
    • These fields are the first three payments (or Transactions) made against the order.
      The fields provided in the Payments 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 order download is performed. Each time the order download is run, the records in this table are updated. A record is maintained for each Shopify Reader which downloads orders.

The reason a date/time is used is due to Shopify's lack of ability to mark orders 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 order download will successfully connect, but there is an error preventing an order or all orders 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 orders 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 Orders

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.

It is therefore imperative a filter is used to remove any orders previously integrated.

Filter Transform

The Filter transform's expression uses the id field to query the ERP/Accounting solution. The expression relies on the id being recorded with the order in an optional field, analysis code or new custom field. If the lookup returns an empty value it is assumed the order has not beein processed.

Lookup("SHOPORDS300", "SHOPORD", %id, False) = ""

Duplicate Order Setup

The lookup (from Sage300) checks an Optional Field for the value.