The field on line items is now available in GraphQL Admin API version 2027-01 and later. Previously, it was only available in the unstable version. You can use it to identify a product variant by its ID or by a custom ID, such as a listing ID from another system that you store in a metafield. This is an additive change to the 2027-01 release candidate, so no action is required.
What changed
In version 2027-01, includes the field. Provide exactly one of the following:
id: the global ID of the product variant.: thenamespace,keyandvalueof anidmetafield on the product variant. If you omitnamespace, your app-reserved namespace is used.
Use instead of and . If a line item sets together with either of those fields, then returns a user error with the INVALID code.
To look up variants by custom ID, the store needs a metafield definition of type id for product variants, and your app must be able to read it. If the definition doesn't exist, then returns an INVALID user error saying that the definition is required.
If no variant in the store matches an identifier, then returns a user error with the VARIANT_IDENTIFIER_NOT_FOUND code for that line item, and doesn't create the order. Line items that use work as before.
Who's affected
The change applies to apps that create orders with . It's most useful for sales channels and integrations that identify products by an ID from an external system.
- API version 2027-01 and later include
. - API version 2026-10 and earlier don't include it.
- Apps that already use
onunstablecan move to 2027-01 without changing their requests.
needs no access scopes beyond those that already requires. Custom ID lookups only find metafields that your app can read.
What to do
No action is required. To start using custom IDs on order line items:
- Check that the store has a metafield definition of type
idfor product variants, and that each variant stores its external ID in that metafield. - Update your app to API version 2027-01.
- Pass
on each line item that you identify by custom ID:
mutation {
orderCreate(order: {
lineItems: [{
variantIdentifier: {
customId: { namespace: "custom", key: "listing_id", value: "LST-10045" }
}
quantity: 1
}]
}) {
order { id lineItems(first: 1) { nodes { variant { id } } } }
userErrors { field message code }
}
}This example creates an order for the variant whose metafield is LST-10045. Replace the namespace, key and value with your own metafield definition and external ID, and add the other order fields that your app normally sends.
- Test in a development store. Create an order with a known custom ID and check that the line item refers to the expected variant. Then send an unknown value and check that
returnsVARIANT_IDENTIFIER_NOT_FOUND.
Why this matters
Until now, an app that knew a variant only by an external ID had two options. It could keep its own mapping from external IDs to Shopify variant IDs, or it could look up each variant with before calling . Now you can pass the external ID in the same request that creates the order.