How can I look up an order by name, using GraphQL?

A quick clarification, first: the order name is the order number plus any configured prefix/suffix. An order's number might be 123, but its order name might be "#CS123-A".

Oddly, there isn't a really good way to look up orders by their name. If the name is all you have, you'll have to query for all orders that match the exact order name you have, and then filter for the single order that actually has an exact match for its name. The filter is important: you might get more than one result back, because of other matches in order data.

Use something like this (and see notes below):

{% assign order_name = "#1234" %}

{% capture query %}
  query {
    orders(first: 250, query: {{ order_name | json | json }}) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
{% endcapture %}

{% assign result = query | shopify %}

{% if event.preview %}
  {% capture result_json %}
    {
      "data": {
        "orders": {
          "edges": [
            {
              "node": {
                "id": "gid://shopify/Order/1234567890",
                "name": {{ order_name | json }}
              }
            }
          ]
        }
      }
    }
  {% endcapture %}

  {% assign result = result_json | parse_json %}
{% endif %}

{% assign order_node = result.data.orders.edges | map: "node" | where: "name", order_name | first %}
{% assign order_id = order_node.id %}

A couple notes about this:

• This example uses stub data, to behave well during preview mode. This technique is useful when generating preview actions (see Preview actions).
• That double "json" filter? It's important! It results in something like query: "\"#1234\"", which means Shopify will query for "#1234", which means Shopify will search for an exact match of the order name.
• We use first: 250 here because it'll probably return the order we need. There's a non-zero chance we'd need to look through more than 250 results for a match, but it's (usually) very unlikely.
• The requested cost for this query, as written, is 252 – but, for a single matching order, the actual query cost (i.e. the cost that ultimately counts against your rate limit) is only 3. You could trim the query down to only first: 5 or something, but it wouldn't make a practical difference in query cost, and it would increase the odds of missing the order you need to find. (For more information on GraphQL query costs, see Shopify's article: GraphQL Admin API rate limits.)