Orders¶
The Orders pull reads orders from Shopify for an ERP, accounting or order processing system. Each order record carries its customer, addresses, discounts, shipping, taxes and payments, and each order has its line items beneath it.
On a reader, select the Shopify System Connectors to read and select Orders as the Shopify Entity. A reader can read several stores at once.
Reader Options¶
The options under the entity choose which orders the pull reads. Each one is a text box. Leave a box empty to use its default. Where an option takes several values, separate them with commas, such as shipped,partial.
| Option | Values | Default |
|---|---|---|
| Fulfillment Status | unshipped, shipped, partial, any |
unshipped |
| Order Status | open, closed, cancelled, any |
open |
| Financial Status | authorized, pending, paid, partially_paid, partially_refunded, refunded, voided, unpaid, any |
any |
| Orders placed in the last | A time span: a number and d, h, m or s, such as 1d, .5d or 30m |
None. A preview needs it |
| Use created date/time or updated date/time | Empty or created_at_min for the created date, updated or updated_at_min for the updated date |
Created |
| Shopify Ids to download | Shopify order ids | Every order |
| Payment Status | pending, failure, success, error |
Every payment |
| Payment Kind | authorization, capture, sale, void, refund |
Every payment |
| API | GraphQL, REST |
GraphQL |
| Timestamps | Machine local, Shop local, UTC |
Machine local |
The pull ignores Payout Status. That option belongs to the Payouts pull.
Which Orders the Pull Reads¶
The pull reads the orders that match the status options and fall inside its time window:
- A preview or refresh in the Designer reads the orders created in the span that Orders placed in the last gives, up to now. The Designer needs a span, and reports an error without one.
- A run outside the Designer reads the orders created since its last run. The first run reads every order that matches.
Set Use created date/time or updated date/time to updated to compare the window with the order's last update instead. Shopify updates an order when it is paid, fulfilled, refunded or edited. An updated-date pull therefore reads an order again after each change.
Shopify Ids to download limits the pull to the orders named, still within the window and the status options.
Payment Status and Payment Kind¶
These two options choose which of an order's transactions fill its Payment1_ to Payment6_ fields. For example, set Payment Kind to sale,capture and Payment Status to success to leave out authorisations and failed attempts. With both empty, the fields hold the order's first six transactions.
API¶
The pull reads through Shopify's GraphQL Admin API. Set API to REST only as a fallback, for an integration that misbehaves after an upgrade, and raise the problem with Realisable support. Shopify has made the REST Admin API a legacy API.
The field names are the same on both APIs. A few fields exist on one API only, and the field list marks them (REST API only) or (GraphQL API only). A field marked for the other API stays empty.
Timestamps¶
Choose how the pull presents the order's dates and times:
Machine local: the IMan server's time zone. This matches what the pull returned before GraphQL.Shop local: the store's time zone, as set in the Shopify admin.UTC: Coordinated Universal Time.
Records¶
The pull returns an Order record for each order, with a LineItems record for each of its lines.
Order¶
The Order record holds the order's own fields, such as id, name, order_number, created_at, financial_status, fulfillment_status, tags and note. The id is Shopify's numeric order id, the same on both APIs. Record it with the order in the target system. A later run can then recognise the order. See Filtering Duplicate Orders.
IMan flattens an order's child data into numbered sets of fields, and one record carries the whole order. A set beyond what the order has stays empty.
| Fields | What they hold |
|---|---|
BillTo_, ShipTo_ |
The billing and shipping addresses |
Customer_ |
The customer and the customer's default address |
Client_ |
The browser the customer ordered with |
Discount1_ to Discount5_ |
The first five discounts applied to the order |
DiscountCode1_ to DiscountCode5_ |
The first five discount codes |
Note1_ to Note15_ |
The first fifteen note attributes |
Shipping1_ to Shipping3_ |
The first three shipping lines, each with the first three taxes on it |
Tax1_ to Tax3_ |
The first three tax lines |
Payment1_ to Payment6_ |
Six of the order's payments. See Payments |
The totals, such as total_price, subtotal_price, total_tax, total_discounts and total_shipping_price, come in the store's currency and in the currency the customer paid in. total_price_shop_money_amount is in the store's currency, and total_price_presentment_money_amount is in the customer's. Each has a matching _currency_code field.
Payments¶
The Payment1_ to Payment6_ fields hold the order's transactions, such as an authorisation, a capture or a sale. The Payment Status and Payment Kind options choose which transactions fill them. Each set includes the transaction's kind, status, gateway, amount and currency, and the date Shopify processed it.
LineItems¶
Each LineItems record holds a line's product, variant, SKU, title, quantity and price. IMan flattens its child data in the same way:
| Fields | What they hold |
|---|---|
Discount1_ to Discount3_ |
The first three discounts on the line |
Tax1_ to Tax3_ |
The first three taxes on the line |
property1_ to property20_ |
The first twenty custom properties on the line |
The line's price and total_discount come in both currencies, as the order totals do.
Running from a Schedule¶
Shopify has no flag to mark an order as downloaded. IMan keeps the time of each pull's last run instead. A run outside the Designer reads from the last run time, and records a new one when it has read the final page. The new time is the start of the run less 15 minutes. That overlap means a run can read an order the previous run read too. A run that fails part way keeps the old time, and the next run reads the same orders again.
IMan keeps the times in the lookup table SHOPIFY Last Run Date/Time, one record for each reader, store and import. The record's ID is the reader's transform hash, the store's ID and the import, such as JXGT-realisable-test-Orders. Its description names all three.
Resetting the Last Run¶
To read orders again, for example after an error stopped some of them reaching the target system:
- Open Setup > Lookup Table Maint and select SHOPIFY Last Run Date/Time. See Lookup Table Maintenance.
- Edit the reader's record and set its time to a point before the orders you need.
The next run reads every matching order from that time on. Make sure the integration filters out the orders it has already processed.
Filtering Duplicate Orders¶
The overlap, a reset, or an updated-date window can each bring an order into a run more than once. Filter out the orders the target system already holds before they reach it.
Record each order's id in the target system, such as in an optional field or a reference, and look it up from a Filter transform before the writer. For example, with a lookup SHOPORD that reads the Shopify order id from Sage 300:
The expression is True for an order the target does not hold yet. Preventing Duplicate Transactions builds this filter step by step.
Access Scopes¶
The pull needs read_orders, read_customers, read_products and read_locations. Add read_all_orders to read orders created more than 60 days ago. See Access Scopes.
Shopify Reference¶
Order in Shopify's GraphQL Admin API reference.