Shopify order settings

Every setting on the Shopify Orders Configuration, from which orders are imported to customer matching, metafields, tags, tax codes, currency and order splitting.

These settings live on the Orders Configuration of a Shopify Integration. They decide which Shopify orders are imported and how each one is turned into a Supply Lens Document. setupDate and importDelay are inherited from the base Shopify configuration, so they also appear on the other Shopify Configurations. For the other Document types, see Shopify shipment settings, Shopify inventory settings and Shopify product update settings.

Which orders are imported

An order is imported only if it passes every one of these filters.

Setting	What it does	Values / default	When to change it
Setup date `setupDate`	Only orders created on or after this date are imported, so historical orders aren't pulled in at go-live.	Date. Set automatically when the Integration is first configured.	Not normally changed afterwards.
Last import date `lastImportDate`	The import watermark. Each run only fetches orders modified after it, and it moves forward after every run.	Date and time. Managed by the system.	Don't edit it by hand.
Financial statuses `financialStatuses`	The Shopify payment statuses an order must have to be imported.	List. Default `["paid", "partially_refunded", "refunded"]`. See the values below.	Add `authorized` if you capture payment after picking; add `pending` or `partially_paid` only if you're happy to ship before full payment.
Fulfilment statuses `fulfillmentStatuses`	The Shopify fulfilment statuses an order must have to be imported.	List. Default `["unfulfilled"]`. See the values below.	Add `partially_fulfilled` if part of an order may be fulfilled elsewhere and the rest should still come through.
Fulfilment order statuses `fulfillmentOrderStatuses`	Shopify splits each order into one or more fulfilment orders, one per fulfilment location. Only fulfilment orders with a status in this list are imported, each as a separate Document.	List. Default `["open", "in_progress", "scheduled", "on_hold"]`.	Rarely; narrow it if some fulfilment order states shouldn't reach the warehouse.
Include POS orders `includePos`	Includes orders placed through Shopify POS (point of sale, the in-person till) alongside online orders.	`true` or `false`. Default `false`: POS orders are excluded.	Turn on when your back-office system should see shop and pop-up sales too.
Customer country filter `customerCountryFilter`	When it has values, only orders from customers in those countries are imported.	List of country codes or names as they appear in Shopify. Empty (the default) means every country.	Use it when one set-up should only handle some countries.
Import delay `importDelay`	A wait before an order is imported after it arrives.	Duration, for example `00:05:00` for five minutes.	Set it when another Shopify app (a 3PL or fulfilment app, for example) needs time to update the order first.

Financial status values

Value	Meaning
`authorized`	Payment has been authorised but not captured
`expired`	An authorisation has expired
`paid`	The order has been fully paid
`partially_paid`	Part of the order has been paid
`partially_refunded`	Part of the payment has been refunded
`pending`	Payment is pending
`refunded`	The full payment has been refunded
`voided`	The payment has been voided

Fulfilment status values

Value	Meaning
`unfulfilled`	No items have been fulfilled
`partially_fulfilled`	Some items have been fulfilled
`fulfilled`	All items have been fulfilled
`in_progress`	Fulfilment is in progress
`on_hold`	Fulfilment is on hold
`scheduled`	Fulfilment is scheduled
`pending_fulfillment`	Fulfilment is pending
`restocked`	Items have been restocked (typically after cancellation)

Customers

Setting	What it does	Values / default	When to change it
Default customer `defaultCustomerId`	The Party used when an order has no identifiable customer: a fallback "guest" or "anonymous" customer.	A Party ID.	Set it as a safety net for orders without a matched customer.
Always use the default customer `alwaysSetDefaultCustomerId`	Uses `defaultCustomerId` for every order, whether or not a customer could be identified.	`true` or `false`.	Turn on when all orders should go to one generic customer account, such as a consumer web shop.
POS customer `posCustomerId`	The Party used for Shopify POS orders that have no customer.	A Party ID.	Set it to a walk-in or counter-sales customer if you import POS orders.
Always use the POS customer `alwaysSetPosCustomerId`	Uses `posCustomerId` for every POS order, even ones with a customer attached in Shopify.	`true` or `false`.	Turn on when every POS sale should land on the POS customer.
Identify the customer from a metafield `metafieldCustomerIdentification`	A list of rules that read the customer's identifier from a Shopify metafield on the order. Rules are tried in order and the first successful match is used.	List of rules; fields below.	Use it when the customer's code or other identifier is stored in an order metafield.
Identify the customer from a custom attribute `customAttributeCustomerIdentification`	A list of rules that read the customer's identifier from a Shopify custom attribute (order note attribute).	List of rules; fields below.	Use it when a checkout field or app stores the identifier as a note attribute.
Use the purchasing company location `usePurchasingCompanyLocation`	Takes the address and contact details from the Shopify B2B purchasing company's location, not the company itself.	`true` or `false`.	Turn on for Shopify B2B where a company has several ship-to locations.
Use the company external ID `useCompanyExternalIdForIdentification`	Matches the customer on the Shopify company's external ID field instead of the Shopify global ID (GID).	`true` or `false`.	Turn on when your customer records are keyed on a reference stored in Shopify's external ID field.

Metafield rule fields

Each rule in metafieldCustomerIdentification has these fields.

Field	What it does
`metafieldKey`	The Shopify metafield key to read the identifier from
`partyIdentifierType`	The type of identifier the value represents (for example `customer-code` or `email`)
`jsonPath`	Optional. A JSON Path expression to pick a value out of a JSON-formatted metafield
`pattern`	Optional. A regular expression applied to the metafield value
`replacement`	A replacement string used with the regular expression match
`groupNumber`	The numbered capture group to take from the match
`groupName`	The named capture group to take from the match

Custom attribute rule fields

Each rule in customAttributeCustomerIdentification has these fields.

Field	What it does
`customAttributeKey`	The custom attribute key to read
`partyIdentifierType`	The type of identifier the value represents

Metafields and custom attributes

The four metafield keys below fall back to the order's custom attributes with the same key when the metafield isn't found.

Setting	What it does	Values / default	When to change it
Earliest ship date metafield `earliestShipDateMetafieldKey`	The metafield (of type `date`) to read the earliest ship date from.	A metafield key.	Set it when orders carry a "don't ship before" date.
Salesperson metafield `salesPersonMetafieldKey`	The metafield to read the salesperson's name or identifier from.	A metafield key.	Set it when orders record a sales rep.
Fulfilment location metafield `fulfillmentLocationMetafieldKey`	The metafield that says which fulfilment Location (warehouse) should handle the order.	A metafield key.	Set it when the warehouse is chosen per order in Shopify.
Fulfilment location identifier type `fulfillmentLocationMetafieldIdentifierType`	How the fulfilment location value is interpreted.	Default `warehouse-code`. Other identifier types may be supported depending on your configuration.	Change it if the metafield holds a different kind of Location identifier.
Purchase order number metafield `purchaseOrderNumberMetafieldKey`	The metafield holding the customer's purchase order number.	A metafield key.	Set it when B2B customers give a PO number at checkout.
Custom attribute tag maps `customAttributeMaps`	Reads a custom attribute value from the order and produces tags from a tag map. Each entry has a `key` (the custom attribute to read) and a `tagMap` (a list of partial tag patterns; the first match decides the tag applied).	List of entries.	Use it to turn free-form checkout values into standard tags.
Custom attribute line tags `customAttributeLineTags`	A dictionary of custom attribute keys to tag definitions. When a line item has a matching custom attribute, the tag is applied to that line.	Dictionary.	Use it to carry line-level data, such as personalisation text, through as tags.
Custom attribute date format `customAttributeDateFormat`	The format used to read dates from custom attributes.	A format string such as `"yyyy-MM-dd"`. If not set, standard formats are tried.	Set it when a custom attribute date doesn't parse.

Setting	What it does	Values / default	When to change it
Document tag generation `documentLevelTagGeneration`	Rules that create tags on the imported Document from values in the source data, using a simple path.	List of rules; fields below.	Use it to tag orders with any field from the Shopify order.
Advanced document tag generation `documentLevelAdvancedTagGeneration`	The same, but using JSON Path or JSON Pointer expressions for nested or complex data.	List of rules; fields below.	Use it when a simple path can't reach the value.
Source name map `sourceNameMap`	Maps the Shopify order source name (for example `web`, `pos` or `app`, the channel the order came through) to an internal tag or value. The first matching entry is applied.	List of entries.	Use it to tag or route orders by channel.

Field	What it does
`source`	Optional. The source document or payload to read from. Defaults to the order.
`key`	The tag key to create
`path`	A simple path to the field whose value becomes the tag value

Field	What it does
`source`	Optional. The source document or payload to read from
`key`	The tag key to create
`jsonPath`	A JSON Path expression to extract the value
`jsonPointer`	A JSON Pointer expression to extract the value (an alternative to JSON Path)

Tax codes

The force settings put a specific tax code from your tax configuration onto part of the order, overriding the tax code that would normally be worked out.

Setting	What it does	Values / default	When to change it
Force tax code `forceTaxCode`	Applies one tax code to the whole order.	A tax code ID.	When every order should carry one tax code.
Force line tax code `forceLineTaxCode`	Applies one tax code to every product line.	A tax code ID.	When product lines should always use one tax code.
Force adjustment tax code `forceAdjustmentTaxCode`	Applies one tax code to every discount and charge adjustment.	A tax code ID.	When adjustments need a fixed tax code.
Force shipping tax code `forceShippingTaxCode`	Applies one tax code to every shipping line.	A tax code ID.	When shipping needs a fixed tax code.
Tax code identifiers by country `taxCodeIdentifiersByCountry`	Per country, which identifiers are offered when matching a goods line's tax to a tax code.	Map with a `default` list and per-country `values`. Default `["shopify-tax-code-title", "uncl5305-code"]` for every country.	Add rate-qualified forms for a country with reduced rates (such as the UK) so a 5% line doesn't resolve to the standard-rate code.
Shipping tax code identifiers by country `shippingTaxCodeIdentifiersByCountry`	The same selection for shipping lines.	Same shape and default.	Normally leave on the default (see below).

Why rate-qualified identifiers matter

Shopify gives every tax line for a country the same title whatever the rate: a UK order labels both a 20% line and a 5% line GB VAT. On the default selection, both match the same tax code and the reduced-rate line is treated as standard rate. The rate-qualified forms let each rate resolve to its own tax code. For each country, choose any combination of:

Value	Example
`uncl5305-code`	`S` for a line with tax, `Z` for one without
`shopify-tax-rate`	`5%`
`shopify-tax-country-rate`	`GB 5%`
`shopify-tax-code-title`	`GB VAT`
`shopify-tax-code-title-rate`	`GB VAT 5%`

Percentages are shown to at most four decimal places (17.5%, 8.25%).

{
  "default": ["shopify-tax-code-title", "uncl5305-code"],
  "values": { "GB": ["shopify-tax-code-title-rate", "shopify-tax-country-rate"] }
}

How matching works:

A code list entry is a candidate if it matches any identifier provided, so each extra form widens the match. Where several entries match, the more specifically scoped one wins: organisation-specific before shared, country-specific before country-agnostic, then the entry's order. A tie raises no error, so point all the forms you configure at the same tax code.
That's why uncl5305-code is normally dropped when you add a rate-qualified form: it matches the shared standard-rate entry, which would then compete on every line.
An identifier that can't be built is skipped (a country form on an order with no address, or a title form on a tax line with no title). If that leaves nothing, uncl5305-code is used so there's always something to resolve on.
Zero-rated lines are unaffected: a line with no tax always resolves on the UNCL5305 code Z.
Keep the default for countries that charge several taxes per line. A US order carries separate state, county, city and special district tax lines, and you'd need a code list entry for every combination.

Place of supply. For goods lines the country is taken per line: physical goods (requiresShipping) use the delivery address, falling back to billing; digital goods use the billing address, falling back to delivery. A line with no requiresShipping flag counts as physical. Order-level tax such as discounts and duties uses the delivery address. For shipping lines, the country is the delivery address, falling back to billing.

Shipping lines. Shopify charges shipping tax at a blended rate based on the mix of goods, so the rate on a shipping line is nominal: it can read 0.2 while the amount charged is zero. Qualifying by that rate would match a tax code the order never used, which is why shippingTaxCodeIdentifiersByCountry normally stays on the title and the S / Z distinction even when goods lines are rate-qualified.

Add the code list entries first

Before configuring a rate-qualified form for a country, the code list must have an entry for every combination it will produce. A combination with no entry leaves the tax code unresolved, and any map that reads a value from it (such as the BATA vat_code column) writes an empty value rather than failing. shopify-tax-country-rate (GB 20%, GB 5% and so on) is the lower-maintenance option where tax line titles are inconsistent.

Currency

Setting	What it does	Values / default	When to change it
Use presentment money `usePresentmentMoney`	Takes prices from Shopify's presentment amounts (the currency shown to the customer at checkout) instead of the shop's base currency.	`true` or `false`.	Turn on when you sell in several currencies and need the currency the customer paid in.

Order splitting and lines

Shopify orders are split by fulfilment order automatically, so one Shopify order can produce several Documents, one per fulfilment location.

Setting	What it does	Values / default	When to change it
Process lines without fulfilment orders `processLineItemsWithoutFulfillmentOrders`	Includes line items that aren't on any fulfilment order (gift cards or custom items Shopify doesn't fulfil).	`true` or `false`. When off or not set, those lines are skipped.	Turn on when those lines must reach the target system, for example for invoicing.
Apply line discounts at order level `applyLineDiscountsAtOrderLevel`	Applies Shopify per-line discounts as order-level adjustments instead of building them into each line's unit price.	`true` or `false`.	Turn on when the target system handles order-level discounts differently from line discounts.