Order number in Graphql API

GraphQL Admin API Troubleshooting
1

Hi team, I need help with admin → GQL migration. We run an invoicing application. We want to know the number of the order.

We want to migrate to the Graphql API but order.order_number is not available in Graphql API. Shopify shows a migration help text that order_number is mapped to number in Graphql but that links to nowhere and number does not exist in graphql.

We cannot use Order name because it can contain prefix and suffix. We need a number format so we can do invoice numbering. Order name won’t work because it can be a string with a prefix and suffix and the app would need to figure out a way to extract number from it. Prefix and suffix can also contain numbers making it extra difficult

image
image1726×1132 170 KB

image
image2528×1332 199 KB

Another Post in the community for this: Order_number GraphQL Admin API - #5 by Michael_Agra

3 Likes
2

I don’t see a way to get the numeric number for the order in GraphQL, but you can retrieve the configured prefix and suffix from the shop object with this GraphQL query:

{
  shop {
    orderNumberFormatPrefix
    orderNumberFormatSuffix
  }
}

Then you can remove the suffix and prefix from the Order.name value to get the numeric ID.

One edge case to keep in mind is that these settings could be changed over time so you might need to account for that.

Best,
Daniel

3

Hi @Daniel_Ablestar Thanks, That edge case is huge for us. In India people change their prefix and suffix every year with the financial year in the prefix. This solution is not enough for us

4

I believe you can use the legacyResourceId field

image
image889×140 11.2 KB

5

@geon

Actually yes you can detect the current store’s order prefix in the number using the Shop object:

There’s a specific shop. orderNumberFormatPrefix and shop.orderNumberFormatSuffix property, so you can use that to remove the suffix/prefix from the order number before storing it.

You may need to set up a webhook on shop settings changes to make sure your caching is in sync, or just look up the current prefix/suffix synchronously - just to make sure you’re up to date.

@Dev_Team

I believe you can use the legacyResourceId field

Not quite. The legacyOrderId field is the internal Shopify order ID. It is not the same as the external order number which is consecutive for each order per store.

The legacyResourceId is a unique ID across all stores, and doesn’t increment across a single store’s orders.

6

@Dylan Thank you. But I still think this issue needs to reach the eyes of Shopify team.

I’d like to highlight an important API functionality gap that needs attention:

  1. The REST API provides order_number as a clean numerical identifier
  2. The GraphQL API migration documentation suggests number as the equivalent field, but this field doesn’t actually exist
  3. While name is available, it’s not a reliable solution because:
  • It can contain custom prefixes/suffixes
  • These affixes may include numbers
  • Historical orders might use different prefix/suffix patterns. And when someone installs our app there is no way to know what the previous suffixes or prefixes were. In our case (India) people change this every financial year (eg: FY/24-25/1001/OnlineOrder)

For invoice numbering systems, we need a consistent numerical identifier. The current workarounds using name parsing are fragile and could break when:

  • Merchants change their order number format
  • Processing historical orders with different naming patterns
  • Handling edge cases where prefixes/suffixes contain numbers

Could the Shopify team please:

  1. Either implement the documented number field in GraphQL
  2. Or add orderNumber as a dedicated numerical field
  3. Update the migration documentation to accurately reflect the current state
3 Likes
7

That’s a great description of the difference between order.order_number and order.name and why the current prefix and suffix isn’t enough for your needs.

Just to summarize for anyone else confused on the details between these very similar fields:

  • order.name is the external customer facing invoice number, but it includes the customizable prefix/suffix (#1001)
  • order.number is the external customer facing invoice number, without any prefix or suffix
  • order.id or order.legacyResourceId is the internal order ID used to identify the order within the Admin API. It is not incremental with other orders in the same store.
1 Like
8

This description explains perfectlythe problem.
Shopify please fix.

9

+1 , we are facing the very same problem described above.

10

Ok, wow, another reason not to migrate just yet

11

I am running into this problem too. How does someone write docs to refer to a field that does not exist?
I wonder how Shopify will fix this though, do they still make changes to the old versions?

12

How do we get Shopify’s attention on this? This will break our app and I don’t think they are planning on implementing this because they removed the link from docs

13

Hey folks,

Appreciate the descriptions of how the name field on Order is insufficient and is a blocker for migrating. I’m connecting with the product teams internally on this.

3 Likes
14

This is also a key feature we’re missing in the GraphQL API. So here’s my +1.

15

Hi Liam, do you have any updates on this?

16

No update to share on this just yet, but our team internally is exploring how to support migration where order numbers are required.

17

Tagging on in hopes of getting answers on this. 3rd party apps like Returns and Exchange apps often set their own alphanumeric value for the order Name. This removes the ability to parse the order number out of the Name field. I’d imagine this is going to wreck integrations for quite a lot of folks as we get closer to the forced migration deadline.

18

At present, the GraphQL API does not support order_numbers. I discovered this issue when migrating orders for my clients a year ago. I also researched existing Shopify apps on the Shopify Store and found that some apps cannot migrate the same order number, and they also use the GraphQL API