Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 55 ยท Admin GraphQL API

Orders, Customers and Protected Data

Query Shopify orders, line items, fulfillment orders and customers with the Admin GraphQL API, and understand protected customer data, scopes and money fields.

Products are the catalog; orders and customers are the business. Almost every useful app eventually reads them: a shipping tool lists orders waiting to be fulfilled, an accounting app copies totals into a ledger, a loyalty app looks at how much a customer has spent. This is also where the API gets stricter, because orders and customers hold personal data. Shopify gates that data behind extra scopes and an approval process, and an app that ignores this will see empty fields or access errors that are hard to understand.

In this lesson you will read orders with their line items and money, see what a fulfillment order is and why it is separate from the order, read customer fields, and learn how protected customer data works. The requests target Admin API version 2026-07 and are read-only here (they would need a real shop). The runnable pieces are stand-ins: an order-total calculator that works in integer cents, and a small gate that shows what an app sees at different data-access levels. They are not Shopify code. For the business ideas behind orders, see The Order Lifecycle and State Machines and Money as Integers.

Scopes for orders and customers

Reading orders needs read_orders; reading customers needs read_customers. Writing needs the matching write_ scope. Fulfillment has its own scopes (for example read_merchant_managed_fulfillment_orders, and assigned or third-party variants depending on who runs the fulfillment). Declare what you need in your configuration, as described in Managed Installation and Access Scopes, and ask for nothing more.

There is one more rule that surprises people: by default an app can read only about the last 60 days of orders. To read older orders, the app needs the read_all_orders scope, which Shopify grants only after review. If your first import "loses" old orders, this is almost always why.

Querying orders

The orders connection works like products (Querying Products and Variants): you pick a page size, a search query, and a sort. This request lists recent paid orders:

GRAPHQL
query RecentPaidOrders($first: Int!, $after: String) {
  orders(
    first: $first
    after: $after
    query: "financial_status:paid AND created_at:>=2026-09-01"
    sortKey: CREATED_AT
    reverse: true
  ) {
    nodes {
      id
      name
      createdAt
      displayFinancialStatus
      displayFulfillmentStatus
      currentTotalPriceSet {
        shopMoney { amount currencyCode }
        presentmentMoney { amount currencyCode }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Points to notice:

  • name is the human order number the merchant and customer see (such as #1042). The id is the global ID (gid://shopify/Order/...) you store and use in later calls. Never parse the number out of name as an identifier.
  • The two status fields are display strings for the two independent tracks of an order: payment (displayFinancialStatus) and shipping (displayFulfillmentStatus). They are separate on purpose; see the lifecycle lesson linked above.
  • Search fields such as financial_status, fulfillment_status, created_at and tag are filters inside the query string, with the same syntax as product search. Check the documented filter list for the version you target.
  • Page through results with a cursor loop (Pagination with Cursors). For thousands of orders, a bulk operation is cheaper (Bulk Operations).

Money comes in bags

Prices are not plain numbers. A field such as currentTotalPriceSet is a money bag with two values:

  • shopMoney is the amount in the shop's own currency.
  • presentmentMoney is the amount in the currency the buyer saw at checkout.

Each value has an amount and a currencyCode. The amount is a decimal string like "49.00", not a number, so that no precision is lost on the wire. Convert it to integer minor units before doing arithmetic, as in Money as Integers. For accounting, use shopMoney; to show the buyer what they paid, use presentmentMoney.

Also note the word current in currentTotalPriceSet. An order's total can change after it is placed (edits, refunds), and the current... fields reflect the order as it stands now, while the original total... fields describe it at placement. Pick the one that matches your purpose and write that choice down; mixing them is a classic source of "the numbers do not match" bugs.

Line items

Each order has line items: the products bought, with quantity and price. Ask for them as a nested connection and keep the inner page small, because nested pages multiply query cost (Rate Limits and Query Cost):

GRAPHQL
query OrderLines($id: ID!) {
  order(id: $id) {
    name
    subtotalPriceSet { shopMoney { amount currencyCode } }
    totalDiscountsSet { shopMoney { amount currencyCode } }
    totalShippingPriceSet { shopMoney { amount currencyCode } }
    totalTaxSet { shopMoney { amount currencyCode } }
    currentTotalPriceSet { shopMoney { amount currencyCode } }
    lineItems(first: 20) {
      nodes {
        title
        sku
        quantity
        originalUnitPriceSet { shopMoney { amount } }
        discountedUnitPriceSet { shopMoney { amount } }
        variant { id }
      }
    }
  }
}

originalUnitPriceSet is the price before discounts; discountedUnitPriceSet is the unit price after discounts applied to that line. The variant can be null when the product was deleted after the order, so never assume it exists. Keep your own copy of the title, SKU and price at the time you process an order: an order is a snapshot, and your records should be too.

Fulfillment orders

Here is a concept that trips up new developers: shipping work does not hang off the order directly. When a customer buys items, Shopify creates one or more fulfillment orders. A fulfillment order is a request to ship a group of line items from one location. An order that ships from two warehouses has two fulfillment orders; an order with a digital item and a physical item can differ again.

flowchart LR
    O["Order #1042"] --> F1["Fulfillment order A<br/>Location: Berlin"]
    O --> F2["Fulfillment order B<br/>Location: Austin"]
    F1 --> S1["Fulfillment<br/>tracking DE-001"]
    F2 --> S2["Fulfillment<br/>tracking US-554"]

One order can split into several fulfillment orders; each is shipped and tracked on its own.

You read them like this:

GRAPHQL
query OrderShipping($id: ID!) {
  order(id: $id) {
    name
    fulfillmentOrders(first: 5) {
      nodes {
        id
        status
        assignedLocation { name }
        lineItems(first: 20) {
          nodes {
            totalQuantity
            remainingQuantity
            lineItem { title }
          }
        }
      }
    }
  }
}

remainingQuantity tells you how much still has to ship. When a shipping app fulfills items, it works with fulfillment order IDs and line items, not with the order. Which fulfillment orders your app may see or act on depends on who is assigned to them (the merchant, your app as a fulfillment service, or another party), and that is why the fulfillment scopes come in several flavors. Treat status as a state machine, as with orders themselves: do not hard-code assumptions about which statuses can follow which, and handle ones you do not recognize.

Customers

A customer record holds identity and some history:

GRAPHQL
query CustomerSummary($id: ID!) {
  customer(id: $id) {
    id
    displayName
    createdAt
    numberOfOrders
    amountSpent { amount currencyCode }
    tags
    defaultEmailAddress { emailAddress }
  }
}

Fields like numberOfOrders and amountSpent are computed by Shopify, which saves you from summing orders yourself. Email and phone have been moved into dedicated sub-objects over the last few versions (defaultEmailAddress rather than a bare email string), a good example of why you read the schema for your target version (API Versioning and Deprecations).

Customers also appear on orders, and an order may have no customer at all: guest checkout is allowed. Code that does order.customer.id will crash on the first guest order, so always treat customer as nullable.

Protected customer data

Names, email addresses, phone numbers and addresses are personal data. Shopify therefore places them in a protected customer data category. Having the read_customers or read_orders scope is not enough to receive them: the app also has to be approved for protected customer data access, which you request in the app's settings in the Partner or Dev Dashboard.

The approval comes in levels, roughly:

  • Level 1: access to protected customer data objects (orders, customers) but not the personal fields. You can read order totals and line items, for example, with no names or emails.
  • Level 2: additionally the personal fields: name, email, phone and address.

For each level you must explain why you need the data, state how you protect it, and meet the requirements that go with it (for example data-protection practices and the privacy webhooks from Privacy, GDPR and Mandatory Webhooks). Custom apps built for a single merchant have a simpler route than public apps, but the idea is the same. The exact levels and forms change, so rely on the current Partner documentation for the procedure and keep this model in mind: objects first, personal fields second.

What does it look like when you lack access? Depending on the field and version, you may get an error in the top-level errors list naming the protected field, or a null value in its place. Both are normal outcomes for an unapproved app, not bugs, so code defensively:

  • Request personal fields only when your feature truly needs them.
  • Treat every personal field as optional in your types.
  • Do not log them, copy them into analytics, or store them longer than you need. Store the Shopify customer ID instead, and look up details when required.

A last rule of thumb: data minimization is cheaper than protection. If your tool only needs to know which orders are unfulfilled, ask for IDs and statuses, not for the shipping address.

Stand-in 1: an order-total calculator

Totals are where order code goes wrong. This stand-in takes an order shaped like the API response (decimal strings), converts everything to integer cents, rebuilds the total from the parts, and compares it with the total Shopify reported. The rule it uses is a simplification (subtotal minus discounts plus shipping plus tax, with tax added on top); real shops can have tax-inclusive prices, which the order's own fields tell you about. It is a model for learning, not Shopify's calculation.

Node.js Rebuild an order total in integer cents

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it: the integer version matches the reported figure exactly. The floating-point line happens to print the same value here, but that is luck of these particular numbers; with other amounts, sums of decimal fractions can drift by a tiny fraction (try changing the tax to 17.43 plus several more 0.10 lines), which is why money is stored as integers. Real code would also compare currencies and keep the order's shopMoney and presentmentMoney apart.

Stand-in 2: what each access level sees

This second stand-in models the "objects first, personal fields second" rule. It filters a customer record by the level an app has been approved for, so you can see what your code would receive and why optional fields matter.

Node.js A protected-data gate by approval level

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The honest summary: in the real API the exact behavior (error versus null) varies by field and version, and approval is granted by Shopify, not computed by your code. The stand-in only shows the shape of the problem and the defensive habit.

Common mistakes

  • Assuming all orders are visible. Without read_all_orders, you see only the recent window.
  • Treating money as numbers. Amounts are decimal strings in money bags; convert to cents before adding.
  • Mixing original and current totals. Choose one on purpose.
  • Shipping against the order. Fulfillment happens through fulfillment orders and their line items.
  • Dereferencing customer or variant without a null check. Guest checkouts and deleted products both produce null.
  • Requesting personal fields "just in case". It costs you approval effort, risk and compliance duties.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Your app has the read_orders scope but is not approved for protected customer data. What should you expect when you query an order's customer email?

    Personal fields need approval for protected customer data in addition to the scope. Without it you get an error or null, so code must treat them as optional.
  2. 2. What does a fulfillment order represent?

    An order can be split into several fulfillment orders, for example one per warehouse, and each is shipped and tracked independently.
  3. 3. Why should you convert amount strings such as "49.00" to integer cents before adding them?

    Decimal fractions often cannot be represented exactly as floats. Integer minor units keep sums exact.
  4. 4. An importer misses all orders older than about two months. What is the most likely cause?

    By default apps see only recent orders. Reading the full history needs read_all_orders, which requires Shopify's approval.
  5. 5. Which line is safest for guest checkouts?

    A guest order has no customer record, so customer can be null. Optional chaining avoids a crash.

Summary

  • Orders need read_orders (recent window) or read_all_orders (full history); customers need read_customers.
  • Money fields are money bags with shopMoney and presentmentMoney, and amounts are decimal strings: convert to integer cents before arithmetic.
  • current... totals describe the order as it stands now; choose original or current deliberately.
  • Shipping work lives in fulfillment orders (one per location or group of items), not directly on the order.
  • customer and variant can be null; guest checkouts and deleted products are normal.
  • Personal fields are protected customer data and need approval beyond the scope; request only what you need and store IDs instead of copies.

Next: Rate Limits and Query Cost.