Send fulfilments to Shopify

Lesson 11 of 18 8 min read

Turn despatches into Shopify fulfilments with tracking, and decide on customer emails, tracking events, collect-in-store orders and metafields written back to the order.

When the warehouse ships an order, your customer wants to know. In this lesson you'll set up the Shipments Configuration so that a despatch in your back-office system or warehouse becomes a fulfilment in Shopify, with tracking, and you'll decide whether Shopify should email the customer.

The flow

Rendering diagram...

To make this work you need a Shipments Configuration with Send ticked on the Shopify Integration, and a Shipments Mapping from your back-office Integration to Shopify.

Telling the customer

notifyCustomer	When true, Shopify sends its fulfilment notification email to the customer when the fulfilment is created or updated. Default: false, so no email is sent.
createFulfillmentEvent	When true, a Shopify fulfilment event is created alongside the fulfilment, giving customers richer tracking status on the order.
fulfillmentEventStatus	The status used for that event. Defaults to CONFIRMED. Other values: ATTEMPTED_DELIVERY, DELIVERED, FAILURE, IN_TRANSIT, LABEL_PRINTED, LABEL_PURCHASED, OUT_FOR_DELIVERY, READY_FOR_PICKUP.

When to choose which. Turn on notifyCustomer if Shopify's shipping confirmation email is how your customers hear their order is on its way. Leave it off if another tool (a carrier, a marketing platform or your warehouse) already emails them, so customers don't get two messages.

It's off by default

Out of the box, notifyCustomer is false. If customers expect a shipping email from Shopify, you must turn it on.

Third-party fulfilment services

message	An optional message sent with the fulfilment request. Only used when the fulfilment order is assigned to a third-party fulfilment service that manages fulfilment orders, typically to pass on special instructions.

Collect-in-store orders

Collect-in-store orders aren't fulfilled outright; Shopify marks them ready for collection. Shopify's ready-for-collection step works on a whole fulfilment order. So if a shipment covers only part of one, Shopify marks the rest ready too, and tells the customer the whole order is waiting.

splitPickupFulfillmentOrders	When true, the lines actually picked are split into a fulfilment order of their own first, and only that one is marked ready. The unpicked lines move to a second fulfilment order that stays open. Default: false.

When to choose it. Turn it on if you offer collect in store and sometimes have only part of an order ready. Leave it off where unpicked lines were never going to ship separately, such as personalisation or option lines sold alongside a product: splitting would leave a fulfilment order open on every such order. When it's on, the split only happens if the shipment covers less than the whole fulfilment order.

Good to know

This setting needs the Supply Lens app to hold extra Shopify permissions (the write_merchant_managed_fulfillment_orders or write_third_party_fulfillment_orders access scope). Check with Support before you turn it on.

Writing references back to the Shopify order

Sometimes another system needs to find "its" reference on the Shopify order, for example your ERP's despatch number.

orderMetafieldMappings	Metafields written back to the original Shopify order once the fulfilment has been created. Each entry names the metafield (namespace and key) and where the value comes from. Leave empty to write nothing.

The value can come from three places, set by the entry's type:

`type`	Value comes from
`tag`	A tag on the shipment Document
`identifier`	An identifier on the shipment's customer
`jsonPath`	Any field on the shipment Document, such as `$.documentReferences.shipment.number` for the shipment's own reference or `$.tracking[0].trackingNumber` for the consignment number

For example, to write the ERP despatch reference to a metafield called custom.erpordserid:

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

A few rules:

The metafield must already have a definition in Shopify to be typed and visible in the admin.
An entry whose value turns out empty is skipped, not written blank.
If you leave out metafieldNamespace, Shopify uses the app's reserved namespace.
Add a valueMap to translate values before they're written, for example "O": "Account". Values with no entry pass through unchanged; mapping a value to "" drops it. Add "valueMapIgnoreCase": true to ignore case and surrounding spaces.

Hilltop Coffee's shipping emails

Hilltop doesn't use any other shipping email tool, so Priya turns on notifyCustomer. She also turns on createFulfillmentEvent, leaving fulfillmentEventStatus on CONFIRMED. Hilltop doesn't offer collect in store, so splitPickupFulfillmentOrders stays off. When Unleashed completes a shipment, the Shopify order shows as fulfilled with tracking and the customer gets Shopify's email.

Recap

A Shipments Configuration with Send ticked turns despatches into Shopify fulfilments with tracking.
notifyCustomer is off by default; turn it on for Shopify's shipping email.
createFulfillmentEvent and fulfillmentEventStatus add tracking events.
splitPickupFulfillmentOrders stops part-ready collect-in-store orders being marked fully ready.
orderMetafieldMappings writes references back to the Shopify order.

Quick guides for this topic

How do I add Shopify?

Complete and continue

Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.

Currency, order splitting and discounts Receive fulfilments from Shopify