---
title: orderCreate line items support custom IDs - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/ordercreate-line-items-support-custom-ids
  md: >-
    https://shopify.dev/changelog/posts/ordercreate-line-items-support-custom-ids.md
metadata:
  effectiveApiVersion: 2027-01
  affectedApi:
    - displayName: GraphQL Admin API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2026-11-03T17:30:47-05:00'
  postedAt: '2026-11-06T00:00:00-05:00'
  updatedAt: '2026-11-10T15:30:20-05:00'
  effectiveAt: '2026-12-01T00:00:00-05:00'
---

November 6, 2026

# orderCreate line items support custom IDs

DateNovember 6, 2026

Version[2027-01](https://shopify.dev/changelog?api_version=2027-01)

FlagsUpdate

Tags[GraphQL Admin API](https://shopify.dev/changelog?api_type=admin-graphql)

The `variantIdentifier` field on [`orderCreate`](https://shopify.dev/docs/api/admin-graphql/2027-01/mutations/orderCreate) 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, [`OrderCreateLineItemInput`](https://shopify.dev/docs/api/admin-graphql/2027-01/input-objects/OrderCreateLineItemInput) includes the `variantIdentifier` field. Provide exactly one of the following:

* `id`: the global ID of the product variant.
* `customId`: the `namespace`, `key` and `value` of an `id` metafield on the product variant. If you omit `namespace`, your app-reserved namespace is used.

Use `variantIdentifier` instead of `variantId` and `productId`. If a line item sets `variantIdentifier` together with either of those fields, then `orderCreate` 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 `orderCreate` returns an `INVALID` user error saying that the definition is required.

If no variant in the store matches an identifier, then `orderCreate` 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 `variantId` work as before.

## Who's affected

The change applies to apps that create orders with `orderCreate`. 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 `variantIdentifier`.
* API version 2026-10 and earlier don't include it.
* Apps that already use `variantIdentifier` on `unstable` can move to 2027-01 without changing their requests.

`variantIdentifier` needs no access scopes beyond those that `orderCreate` 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:

1. Check that the store has a metafield definition of type `id` for product variants, and that each variant stores its external ID in that metafield.
2. Update your app to API version 2027-01.
3. Pass `variantIdentifier` on each line item that you identify by custom ID:

```graphql
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 `custom.listing_id` 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.

1. 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 `userErrors` returns `VARIANT_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 `productVariantByIdentifier` before calling `orderCreate`. Now you can pass the external ID in the same request that creates the order.

## Related docs

* [Working with custom IDs](https://shopify.dev/docs/apps/build/metafields/working-with-custom-ids)
* [`orderCreate` mutation](https://shopify.dev/docs/api/admin-graphql/2027-01/mutations/orderCreate)
* [`OrderCreateLineItemInput` reference](https://shopify.dev/docs/api/admin-graphql/2027-01/input-objects/OrderCreateLineItemInput)