Carry extra order data
Lesson 8 of 18 8 min read
Bring ship dates, PO numbers, salespeople, warehouses and tags across from Shopify metafields, custom attributes and order sources.
A Shopify order often carries more than products and an address: a requested ship date, a customer PO number, the rep who took the order, or a note saying which warehouse should pick it. In this lesson you'll learn how to bring that information across so your back-office system and warehouse can act on it.
Metafields and custom attributes, again
Shopify can hold extra information in two places:
- Metafields: extra fields on the order, usually added by apps or by your Shopify admin.
- Custom attributes: name-and-value pairs on the order or on a line, often captured at checkout (for example a "Delivery date" box on the cart page).
Each of the settings below names a metafield key. If Supply Lens doesn't find that metafield, it checks the order's custom attributes for the same key instead, so the same setting works whichever way your store captures the data.
Key fields from metafields
| earliestShipDateMetafieldKey | The metafield (of type date) holding the earliest date the order may ship. Use it for pre-orders or customers who choose a delivery date. |
|---|---|
| purchaseOrderNumberMetafieldKey | The metafield holding the customer’s purchase order number. Useful for trade customers whose invoices must quote their PO. |
| salesPersonMetafieldKey | The metafield holding the salesperson’s name or identifier, for commission or reporting. |
| fulfillmentLocationMetafieldKey | The metafield saying which fulfilment location, such as a warehouse, should handle the order. |
| fulfillmentLocationMetafieldIdentifierType | How to read the fulfilment location value. Defaults to warehouse-code if not set. |
| customAttributeDateFormat | The date format used when reading dates from custom attributes, for example yyyy-MM-dd. If not set, standard date formats are tried. |
Check the date format
If customers type a delivery date into a cart box as 30/10/2026, set
customAttributeDateFormat to match (dd/MM/yyyy). Otherwise the date may not be read the
way you expect.
Turning values into tags
Tags are labels on a Document, made of a key and a value. They're useful for finding and reporting on orders, and for passing information on to other systems.
| customAttributeMaps | Reads a custom attribute on the order and turns it into a tag, using a tag map. The first pattern that matches decides the tag. Use it to turn free-text values into a standard set of tags. |
|---|---|
| customAttributeLineTags | Applies a tag to an order line when that line has a matching custom attribute. Use it to carry line-level details, such as engraving text, through as tags. |
| documentLevelTagGeneration | Rules that create a tag on the order from any field in the source data, using a simple path to the field. |
| documentLevelAdvancedTagGeneration | The same, but using JSON Path or JSON Pointer expressions, for values buried deep in nested data. Usually set up by an implementer. |
| sourceNameMap | Maps the Shopify order source name (for example web, pos or app) to an internal tag or value. The first matching entry applies. Use it to tag or route orders by the channel they came from. |
Choosing the right tool
| You want to… | Use |
|---|---|
| Pass on the earliest date an order may ship | earliestShipDateMetafieldKey |
| Print the customer's PO on the invoice | purchaseOrderNumberMetafieldKey |
| Say which warehouse should handle an order | fulfillmentLocationMetafieldKey |
| Tag orders by the channel they came from | sourceNameMap |
| Tag gift orders from a "Gift wrap: Yes" checkout box | customAttributeMaps |
| Keep personalisation text with the line it belongs to | customAttributeLineTags |
| Tag orders with any other field from Shopify | documentLevelTagGeneration (or the advanced version) |
Hilltop Coffee's wholesale orders
Hilltop also sells to cafés through a draft-order process, and café owners give a PO
number that must appear on the Unleashed order. Hilltop's Shopify admin stores it in a
metafield called custom.po_number. Priya sets
purchaseOrderNumberMetafieldKey to that key.
They also want web and wholesale orders easy to tell apart in Supply Lens, so she adds a
sourceNameMap entry that tags orders by their Shopify source name. Wholesale orders now
carry a tag that tells the team where they came from.
Good to know
The exact shape of a sourceNameMap or tag map entry depends on your tags. If you're not
sure how to write one, ask your Supply Lens contact for an example that fits your store.
Recap
- Metafield-based settings fall back to custom attributes with the same key.
- Use the dedicated keys for earliest ship date, PO number, salesperson and fulfilment location.
- Set
customAttributeDateFormatwhen dates come from checkout boxes. - Turn values into tags with custom attribute maps, line tags, tag generation rules and
sourceNameMap. - Tags make orders easy to find and carry extra information on to other systems.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.