Skip to content

Orders

The Orders push creates orders in Shopify, such as orders taken in another channel, at a trade counter or in a system the store is moving from. Each order can carry its lines, customer, addresses, discount code, shipping, taxes, payments and metafields, and can be fulfilled as Shopify creates it. The push also updates a few fields on existing orders.

On a push connector, select Orders as the Shopify Import Type. The push creates an order through Shopify's orderCreate mutation and updates one through orderUpdate.

The Designer lists most of this import's fields by their id, such as financial_status and BillTo_city. This page names them the same way.

Records

Record Under One for each
Order order
LineItems Order line
LineItemProperties LineItems custom property on the line, as a name and a value
LineItemTaxLines LineItems tax on the line
Transactions Order payment recorded with the order
TaxLines Order tax on the order
ShippingLines Order shipping charge
ShippingLineTaxLines ShippingLines tax on the shipping charge
CustomAttributes Order note attribute, as a key and a value
Metafields Order metafield on the order

Creating and Updating

id decides between creating an order and updating one:

  • Leave id blank to create the order. IMan writes the new order's id back.
  • Map an order's id to update it. An update changes only the email, phone, note, tags, PO number, shipping address, custom attributes and metafields. Shopify keeps the lines, prices and payments as they were.

The push's Update Operation limits this further. Under Insert, a record with an id fails. Under Update, a record without one fails.

The Order

Field Effect
name The order name, such as #1001. Blank lets Shopify number the order
currency The store currency every amount is in. Blank is the store's currency. presentment_currency is the currency the customer saw
financial_status pending, authorized, partially_paid, paid, partially_refunded, refunded, voided or expired. Blank lets Shopify work it out from the transactions
fulfillment_status fulfilled, partial or restocked. Blank is unfulfilled
inventory_behaviour bypass, the default, leaves stock alone. decrement_ignoring_policy or decrement_obeying_policy takes the lines' stock
send_receipt, send_fulfillment_receipt True emails the customer the order or shipping confirmation. Blank sends none
processed_at When the customer placed the order, for an order brought in from elsewhere
tags Tags, separated by commas. On an update they replace the order's tags. A blank tags leaves them as they are

A field that takes a value from a list accepts it in any case, with spaces or underscores: partially paid, partially_paid and PARTIALLY_PAID all work. A value not on the list fails the record before IMan sends it.

BillTo_ and ShipTo_ fields hold the billing and shipping addresses. Where the transform maps both a code and a name, the country code wins over the country name, and the province code over the province name.

The Customer

The Customer_ fields decide which customer the order belongs to:

  • Customer_id alone links the order to that customer and leaves the customer unchanged.
  • Customer_id with other Customer_ fields links the order and updates the customer with them.
  • Customer_email without Customer_id finds the customer with that email, or creates one, links the order and updates the customer.
  • No Customer_ fields leaves the order without a customer.

IMan writes the customer's id back into Customer_id when it was blank.

Discount Code

discount_code applies a discount code to the order. discount_code_type is fixed_amount, percentage or shipping, with the value in discount_code_amount or discount_code_percentage. A blank type is percentage when discount_code_percentage has a value, and fixed_amount otherwise. A shipping code makes the shipping free and ignores the amount and percentage.

Fulfilling the Order as Shopify Creates It

fulfillment_location_id fulfils every line from that location as Shopify creates the order. The other fulfillment_ fields set the carrier, tracking, shipment status and origin:

  • fulfillment_tracking_numbers takes one tracking number, or several separated by |.
  • fulfillment_shipment_status is a status such as in_transit, out_for_delivery or delivered.
  • Any origin address field needs fulfillment_origin_country_code too.

Any other fulfillment field without fulfillment_location_id fails the record. To fulfil an order after Shopify creates it, use the Fulfillments push.

Lines, Taxes, Shipping and Payments

Each child record needs certain values, and a record without them fails before IMan sends it:

Record Needs
LineItems quantity, and title when the line has no variant_id. A variant_id sells that variant, with its title, SKU and weight from Shopify
LineItemTaxLines, TaxLines, ShippingLineTaxLines title and rate, the rate as a fraction: 0.2 is 20%
ShippingLines title and price
LineItemProperties name and value
CustomAttributes key and value
Transactions amount. kind is sale, capture, authorization, void, refund, change, emv_authorization or suggested_refund, and status is success, failure, pending, error, awaiting_response or unknown

price on a line is the unit price before discounts.

To record a payment, capture or refund against an order after Shopify creates it, use the Transactions (Payment) push.

Metafields

Metafield 1 to Metafield 10 on the Order record, and Metafields records under it, set metafields on the order. They follow the same rules as on the Products push. IMan sends them after the order, and a metafield Shopify refuses fails its record with a message that says IMan wrote the order.

Write-Back

After a create, IMan writes back the order's id, name and number, and its subtotal_price, total_discounts, total_line_items_price, total_price, total_tax and total_weight. It also writes back each line's id, by position. Write-back skips fields the transform does not map.

Development and Trial Stores

Shopify accepts only five new orders a minute on a development or trial store. When Shopify refuses an order for that reason, IMan logs the wait once, and sends the order again every 15 seconds for up to three minutes. The record fails if Shopify still refuses it.

Speed and Bulk Operations

The push sends one order at a time, in record order. MaxConcurrentRequests in the connection string speeds up only the orders' metafield requests.

With Use Bulk Operations on, IMan sends the run through Shopify bulk operations. New orders go in the first round. Records that update the same order go in successive rounds, and the last update wins. Each round sends its creates, then its updates, then the metafields.

Errors

A record that fails a check fails before IMan sends anything for it. Shopify's refusals fail the record with Shopify's message:

Shopify did not create the order:
...

Action on Transform Error decides whether the run goes on.

Access Scopes

The push needs write_orders. See Access Scopes.

Shopify Reference

orderCreate and orderUpdate in Shopify's GraphQL Admin API reference.