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
idblank 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_idalone links the order to that customer and leaves the customer unchanged.Customer_idwith otherCustomer_fields links the order and updates the customer with them.Customer_emailwithoutCustomer_idfinds 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_numberstakes one tracking number, or several separated by|.fulfillment_shipment_statusis a status such asin_transit,out_for_deliveryordelivered.- Any origin address field needs
fulfillment_origin_country_codetoo.
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:
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.