Shopify just made a game‑changing tweak to the orderCreate mutation. Starting with API version 2027-01, the line‑item input now includes a variantIdentifier field that accepts either the global variant ID or a custom ID stored in a metafield. For developers building sales channels, marketplaces, or any integration that tracks products by an external system ID, this means you can skip the extra lookup step and send the custom ID straight to orderCreate. In this post we’ll break down the update, who needs to care, and the exact steps to start leveraging custom IDs in your apps.
What Changed
In the 2027-01 release candidate, OrderCreateLineItemInput gained a new field called variantIdentifier. Instead of providing both variantId and productId (or just variantId), you now supply a single object that contains either an id (the global GraphQL ID) or a customId. The customId is composed of a metafield namespace, key, and value that points to an ID type metafield on the product variant. If you send both variantIdentifier and the old fields, Shopify returns a userError with the INVALID code, enforcing the new pattern.
The customId lookup only works when the store has a metafield definition of type id for product variants, and your app has permission to read that metafield. If the definition is missing, orderCreate will fail with an INVALID error stating the definition is required. If no variant matches the supplied custom ID, Shopify returns VARIANT_IDENTIFIER_NOT_FOUND and aborts the entire order creation.
Who Is Affected
The change is relevant to any app that uses the orderCreate mutation—primarily sales channels, fulfillment apps, and third‑party integrations that generate orders on behalf of merchants. If you’re already using the unstable version of variantIdentifier, you can simply upgrade to the stable 2027-01 version with no code changes. Apps that still rely on variantId continue to work as before, but they miss out on the convenience of custom IDs.
Developers on API versions 2026-10 and earlier won’t see this field at all, so they must either stay on those versions or upgrade. No additional access scopes are required beyond what orderCreate already needs; the only new prerequisite is that your app can read the id‑type metafield used for the custom identifier.
How to Implement Custom IDs Today
mutation {\n orderCreate(order: {\n lineItems: [{\n variantIdentifier: {\n customId: { namespace: \"custom\", key: \"listing_id\", value: \"LST-10045\" }\n }\n quantity: 1\n }]\n }) {\n order { id lineItems(first: 1) { nodes { variant { id } } } }\n userErrors { field message code }\n }\n}
Swap out the namespace, key, and value with whatever metafield you defined. If a variant matches, the order is created and the line item points to that variant. If the value is unknown, you’ll get a VARIANT_IDENTIFIER_NOT_FOUND error in the userErrors array.
Testing and Error Handling
Create a development store, add the metafield definition, and assign a known external ID to a test variant. Run the mutation above with that ID and confirm the order appears in the admin UI with the correct product. Then try a bogus value and verify that the response includes a userError with code VARIANT_IDENTIFIER_NOT_FOUND. This two‑step test ensures both the happy path and the failure path are covered before you ship to live merchants.
Why This Matters for Your Business
Before this release, apps had to maintain a mapping table between their external IDs and Shopify variant IDs, or perform a separate productVariantByIdentifier query before creating the order. Both approaches add latency, increase complexity, and create potential sync issues. With variantIdentifier, you can collapse those steps into a single orderCreate call, reducing API round‑trips and making your integration faster and more reliable. For high‑volume sales channels, that performance gain can translate into smoother checkout experiences and lower failure rates.
Additionally, because the custom ID is read directly from a metafield, merchants retain full control over the data model. If they ever need to change the external ID format, they only update the metafield values—your app continues to work without code changes.
Conclusion & Next Steps
The variantIdentifier addition to orderCreate is a small but powerful improvement that eliminates a common integration pain point. To start reaping the benefits, confirm the required metafield definition, bump your app to API version 2027-01, and swap your line‑item payloads to use variantIdentifier where appropriate. As always, test thoroughly in a sandbox store before rolling out to live merchants.
Got questions or need help updating your integration? Drop a comment below or reach out to our developer support team. Happy building!
