Order mapping

Order display name (e.g. #1042). Customers and merchants see this.

"name": "#" & $string(increment_id)

Order contact email — used for notifications. Falls back to the customer’s email if omitted.

Order contact phone, and the phone on the customer the order upserts. Shopify only accepts E.164 (+15555550123); a local number is converted for you using billing_country (falling back to shipping_country). Placeholders that hold no number (0, -, blank) are treated as no phone; anything else that can’t be resolved fails validation with INVALID_FORMAT rather than at load time.

The customer’s id in the source store. Graftport swaps it for the migrated customer, attaching the order to a customer record that already exists.

"customerId": customer_id

Prefer this over the email / firstName / lastName fields wherever the source knows which customer placed the order. Without it, loading an order writes a customer built from whatever the order carries, which overwrites fields the order doesn’t know about. Leave it unmapped for guest checkouts — the order then arrives with no customer attached, which is what a guest checkout is.

Migrate customers before orders, which is the order Graftport runs them in by default. If an order loads before the customer it points at, the order still arrives complete — with its own lines, totals and addresses — but with no customer attached, and re-running won’t attach one later: Shopify lets you change an existing order’s note, tags and shipping address, not who placed it. Include customers in the same migration as orders and this resolves on its own.

The discount code the customer actually typed. Without it, an order that carries a discount amount gets a generated placeholder code, which is what shows on the order in the admin.

"discountCodeText": coupon_code

When the order was placed on the source platform. Always emit this on historical orders so the timeline is preserved.

"processedAt": created_at

When the order was closed (typically equal to processedAt for fully-fulfilled historical orders).

One of PENDING, AUTHORIZED, PARTIALLY_PAID, PAID, PARTIALLY_REFUNDED, REFUNDED, VOIDED.

"financialStatus": is_paid ? "PAID" : "PENDING"

One of FULFILLED, PARTIALLY_FULFILLED, RESTOCKED. Omit for unfulfilled orders.

true if line item prices already include tax (common in EU merchants), false if tax is added on top (common in US).

The original platform’s order ID — preserves cross-system traceability. Often the same as original_id for orders.

Where the order originated (e.g. web, pos, magento).

ISO 4217 currency code for the shop’s base currency on this order. Used inside priceSet.shopMoney.currencyCode of every line item.

"currency": order_currency

The currency the customer saw at checkout, if multi-currency. Often equal to currency for single-currency orders.

Used on the order’s customer record AND on shipping/billing addresses.

Note attached to the customer on this order. Different from note (below), which is the order-level admin note.

Tags attached to the customer (not the order).

State / province.

Country code (ISO 3166-1 alpha-2 preferred).

Recipient’s first name. A gift often ships to someone other than the account holder, so map this when the source keeps a separate delivery name. Left unmapped, the customer’s own name is used.

Contact number for the delivery, used by carriers. Normalized against shipping_country.

Name the invoice is addressed to — accounts payable, rather than the person who placed the order. Falls back to the customer’s name.

Array of order line items. Each entry has the same shape Shopify’s OrderCreateLineItemInput accepts:

Anything else on a line item is rejected — map it as an order custom attribute instead.

"lineItems": items.{
  "title": name,
  "sku": sku,
  "quantity": qty_ordered,
  "priceSet": {
    "shopMoney": {
      "amount": $string(price),
      "currencyCode": $$.order_currency
    }
  }
}

Percentage off as a number 0-100 (25 = 25%). Applied to qualifying items.

"itemPercentageDiscount": discount_percent

Fixed money amount off (in the order’s currency). Rounded to 2 decimals.

true if the order had a free-shipping discount.

The Shopify location GID this order ships from. Required to create a fulfillment.

"locationId": $$.config.default_location_gid

Whether to send a fulfillment notification email when the load creates the fulfillment. Default behavior is Shopify’s (no email for migrated orders is usually right).

Carrier name (e.g. UPS, DHL).

One of Shopify’s shipment statuses (e.g. DELIVERED, IN_TRANSIT).

Array of payment transactions. Each entry follows Shopify’s OrderCreateOrderTransactionInput shape:

"transactions": [{
  "kind": "SALE",
  "status": "SUCCESS",
  "gateway": payment_method,
  "processedAt": created_at,
  "amountSet": {
    "shopMoney": { "amount": $string(grand_total), "currencyCode": order_currency }
  }
}]

Order-level tax breakdown. Each entry is { title, rate, priceSet }. Order-level tax is only honoured when no line item carries its own, so pick one level and stay there — mixing the two loses tax. If your source breaks tax down per line, put it on the lines (and on the shipping lines) and leave this field out.

Shipping methods used on the order. Each entry is { title, code, source, priceSet, taxLines }.

code is the carrier’s rate code and source the rate provider, both shown on the order in the admin. taxLines is the tax charged on the delivery itself — it belongs here rather than on the order whenever the line items carry their own tax.

"shippingLines": [{
  "title": shipping_method,
  "code": shipping_code,
  "priceSet": {
    "shopMoney": { "amount": $string(shipping_amount), "currencyCode": order_currency }
  },
  "taxLines": [{
    "title": "VAT",
    "rate": tax_rate,
    "priceSet": {
      "shopMoney": { "amount": $string(shipping_tax), "currencyCode": order_currency }
    }
  }]
}]

Free-form { key, value } map of order-level custom attributes (notes from checkout, gift options, custom forms). Each entry becomes one Shopify custom attribute.

"dict_customAttributes": {
  "gift_message": gift_message,
  "preferred_delivery": delivery_window
}

Order-level admin note (separate from customerNote).

Order-level tags.