Shopify shipment settings

Every setting on the Shopify Shipments Configuration, for sending fulfilments and tracking to Shopify and for receiving fulfilments from it.

These settings live on the Shipments Configuration of a Shopify Integration. Tick Send to send fulfilments and tracking from your warehouse or back-office system to Shopify, and Receive to import fulfilments made in Shopify. Some settings apply to one direction only, as the headings below show.

Dates and timing

Setting	What it does	Values / default	When to change it
Setup date `setupDate`	Only shipments on or after this date are processed, so historical shipments aren't processed at go-live.	Date. Set automatically when the Integration is first configured.	Not normally changed afterwards.
Import delay `importDelay`	A wait before a shipment is imported from Shopify, so other systems can make their changes first.	Duration, for example `00:05:00` for five minutes.	Set it when another app updates fulfilments just after they're made.

Sending shipments to Shopify

Setting	What it does	Values / default	When to change it
Notify the customer `notifyCustomer`	Has Shopify send its fulfilment email to the customer when the shipment is created or updated.	`true` or `false`. Default `false`: no email.	Turn on if Shopify should send the shipping confirmation. Leave off if another system emails customers.
Message `message`	An optional message sent with the fulfilment request, typically special instructions. Only applies when the fulfilment order is assigned to a third-party fulfilment service that manages fulfilment orders.	Text.	Set it when a third-party fulfilment service needs instructions.
Split pickup fulfilment orders `splitPickupFulfillmentOrders`	For collect-in-store orders only. Splits the picked lines into their own fulfilment order and marks only that one ready for collection; unpicked lines move to a second fulfilment order that stays open.	`true` or `false`. Default `false`.	Turn on when partial pickups are possible (see below).
Create a fulfilment event `createFulfillmentEvent`	Creates a Shopify fulfilment event alongside the fulfilment, for more detailed tracking status on the order.	`true` or `false`.	Turn on to give customers richer tracking information.
Fulfilment event status `fulfillmentEventStatus`	The status used when creating the fulfilment event.	Default `CONFIRMED`. One of `ATTEMPTED_DELIVERY`, `CONFIRMED`, `DELIVERED`, `FAILURE`, `IN_TRANSIT`, `LABEL_PRINTED`, `LABEL_PURCHASED`, `OUT_FOR_DELIVERY`, `READY_FOR_PICKUP`.	Change it when a different status better describes the shipment at the point it's sent.
Order metafield mappings `orderMetafieldMappings`	Metafields written back to the original Shopify order once the fulfilment is created, so a source system can reconcile its own reference against the order.	List of mappings (below). Empty by default: nothing is written.	Set it when Shopify needs a reference from your ERP or warehouse on the order.

Collect-in-store orders

Collect-in-store orders are marked ready for collection rather than fulfilled. Shopify's ready-for-collection call names a whole fulfilment order, so a shipment covering only part of one marks the rest ready too, and tells the customer the whole order is waiting. splitPickupFulfillmentOrders fixes that.

The fulfilment order is only split when the shipment covers less than all of it, so a complete shipment, or a repeat send, behaves as before.
Leave it off where the unpicked lines were never going to ship separately (personalisation or other option lines sold alongside a product, for example). Splitting would leave a fulfilment order open on every such order.
The Shopify app needs the write_merchant_managed_fulfillment_orders (or write_third_party_fulfillment_orders) access scope.

Order metafield mappings

Each mapping names the metafield to write (metafieldNamespace and metafieldKey) and, through its type, where the value comes from.

`type`	Value comes from	Extra field
`tag`	A tag on the shipment Document	`tag`: a partial tag matched on `source` (the integration key that stamped it), `key` and `value`. Each supports `*` wildcards and `^…$` regular expressions. Set `source` to stop another integration's tag with the same key matching.
`identifier`	An identifier on the shipment's customer	`identifierType`: the identifier type ID to read
`jsonPath`	Any field on the shipment Document	`jsonPath`: a JSONPath expression run against the stored shipment

A mapping whose value resolves to nothing is skipped, not written empty.
If you leave out metafieldNamespace, Shopify uses the app-reserved namespace.
The metafield must already have a definition in Shopify to be typed and visible in the admin.
A jsonPath can reach any field on the Document: $.documentReferences.shipment.number for the shipment's own reference, $.tracking[0].trackingNumber for the consignment number, $.customer.name and so on. Use a tag where the value has no home on the Document.

For example, writing the ERP despatch reference (stored as the shipment's own Document reference) to custom.erpordserid:

"orderMetafieldMappings": [
  {
    "type": "jsonPath",
    "metafieldNamespace": "custom",
    "metafieldKey": "erpordserid",
    "jsonPath": "$.documentReferences.shipment.number"
  }
]

Any mapping can also carry a valueMap that translates the value before it's written. Use it when the source system's codes aren't values the metafield accepts: a metafield whose definition lists fixed choices rejects anything else.

"orderMetafieldMappings": [
  {
    "type": "tag",
    "metafieldNamespace": "custom",
    "metafieldKey": "account_type",
    "tag": { "source": "customer-bata", "key": "account_status" },
    "valueMap": { "O": "Account", "S": "*** ON STOP ***" }
  }
]

A value with no entry in the map is written unchanged, so list only the codes that differ.
Map a code to "" to drop it, since an empty value is skipped.
Keys match exactly. Add "valueMapIgnoreCase": true to match ignoring case and surrounding whitespace.

Receiving shipments from Shopify

Setting	What it does	Values / default	When to change it
Last import date `lastImportDate`	The import watermark. Each run only fetches shipments modified after it.	Date and time. Managed by the system.	Don't edit it by hand.
Include fulfilment statuses `includeFulfillmentStatuses`	When it has values, only Shopify fulfilments with one of these statuses are imported.	List, such as `FULFILLED` or `PENDING`. Empty means all statuses.	Use it to import only fulfilments in a particular state.
Exclude fulfilment statuses `excludeFulfillmentStatuses`	Fulfilments with one of these statuses are skipped, even if they'd otherwise be imported.	List.	Use it to drop specific states.
Include fulfilment display statuses `includeFulfillmentDisplayStatus`	When it has values, only fulfilments whose display status (the customer-facing state) matches are imported.	List. Empty means all.	Use it to filter on what the customer sees.
Exclude fulfilment display statuses `excludeFulfillmentDisplayStatus`	Fulfilments with one of these display statuses are skipped.	List.	Use it to drop specific customer-facing states.
Use presentment money `usePresentmentMoney`	Takes amounts from Shopify's presentment (customer-facing) currency instead of the store's base currency.	`true` or `false`.	Turn on when you sell in several currencies and want the currency the customer saw.
Tax code identifiers by country `taxCodeIdentifiersByCountry`	Per country, which identifiers are offered when matching shipment line tax to a tax code.	Same shape as on the order Configuration. Default `["shopify-tax-code-title", "uncl5305-code"]` for every country.	Keep it in step with the order Configuration's setting.
Shipping tax code identifiers by country `shippingTaxCodeIdentifiersByCountry`	The equivalent selection for shipping lines.	Same default.	No effect today: a fulfilment carries goods lines only. Present for consistency with the order Configuration.

A fulfilled line is physical goods by definition, so for tax the country comes from the fulfilled order's delivery address, falling back to its billing address. For the available identifier values, the configuration shape and the code list prerequisites, see Shopify order settings.