Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 55 ยท Admin GraphQL API

Mutations and userErrors

Write data with Shopify Admin GraphQL mutations, read userErrors versus top-level errors, handle partial failure, and build a safe error-handling wrapper.

Reading data is forgiving: if a query asks for the wrong thing, you get a clear error and nothing changes. Writing data is different. A mutation creates, changes or deletes something in a merchant's shop, and it can fail in several different ways: the request is malformed, your app lacks permission, you are being throttled, or the data simply breaks a business rule ("the handle is already taken"). Each of those needs a different response from your code.

This lesson shows the shape of a mutation, how input objects work, and, most importantly, the two separate places where errors appear: the top-level errors list and the userErrors field inside the result. You will build a wrapper that sorts them out. Requests target Admin API version 2026-07 and are read-only here, because they would change a real shop; the wrapper is a runnable stand-in that works against a fake client.

Anatomy of a mutation

A mutation looks like a query with the keyword mutation. By convention it takes an input object, returns the changed object, and always asks for userErrors. This one creates a product (it needs the write_products scope):

GRAPHQL
mutation CreateProduct($product: ProductCreateInput!) {
  productCreate(product: $product) {
    product {
      id
      title
      handle
      status
    }
    userErrors {
      field
      message
    }
  }
}
JSON
{
  "product": {
    "title": "Linen shirt",
    "vendor": "Acme",
    "productType": "Shirt",
    "tags": ["summer", "linen"],
    "status": "DRAFT"
  }
}

Several things here are worth learning:

  • The argument is an input object typed with a name ending in Input. The variables JSON mirrors its fields. Required fields are marked with ! in the schema.
  • Mutation argument names have changed between versions (older versions used input: for product creation and newer ones use product:). This is one reason to read the schema of the version you target; see API Versioning and Deprecations.
  • The selection set tells Shopify what to return. Ask for the new id, because you will need it for everything that follows.
  • A mutation has a base cost of 10 points plus the cost of the fields you select. See Rate Limits and Query Cost.
  • Creating something as DRAFT first is a safe habit: the merchant sees nothing until you publish it.

A successful response contains the object and an empty userErrors list:

JSON
{
  "data": {
    "productCreate": {
      "product": { "id": "gid://shopify/Product/9001", "title": "Linen shirt", "handle": "linen-shirt", "status": "DRAFT" },
      "userErrors": []
    }
  }
}

Two kinds of errors

This is the idea that trips up almost every new Shopify developer. There are two error channels, and they mean different things.

Top-level errors describe a problem with the request itself, or something the API could not do at all. Examples: a syntax error in the query, an unknown field, a missing access scope (code ACCESS_DENIED), a throttled request (THROTTLED), or an internal failure. The response usually has no data for the field, or data: null. These are your mistakes or infrastructure problems. They do not usually fix themselves by showing a message to the merchant.

userErrors describe a problem with the data you sent. The request was valid and was executed, but the business rules rejected the change. Examples: a title that is blank, a duplicate handle, a value that fails validation, an ID that does not exist. These arrive inside data, with an HTTP status of 200, and the mutation field usually returns product: null alongside. They are the errors you can often show to a person, because message is written in plain language and field points at the input that caused it (for example ["product", "title"]).

JSON
{
  "data": {
    "productCreate": {
      "product": null,
      "userErrors": [
        { "field": ["product", "title"], "message": "Title can't be blank" }
      ]
    }
  }
}

Many mutations also add a code to their user errors, such as TAKEN or INVALID, which is better to branch on than the message text. Check the schema for the specific mutation; do not assume every mutation has one.

The consequence for your code is severe: an HTTP 200 does not mean success. If you only check the status code, or only look for errors, you will treat a rejected write as a success. Always check userErrors for every mutation you send.

flowchart TD
    S["Send mutation"] --> H{"HTTP status OK?"}
    H -->|"no, 5xx or 429"| R["Retry later with backoff"]
    H -->|"yes"| T{"Top-level errors?"}
    T -->|"THROTTLED"| R
    T -->|"ACCESS_DENIED, syntax,<br/>other"| B["Bug or permission: log and fix"]
    T -->|"none"| U{"userErrors empty?"}
    U -->|"no"| D["Bad data: show message<br/>or skip this item"]
    U -->|"yes"| OK["Success: use the returned object"]

Check the transport first, then top-level errors, then userErrors; only then read the result.

Partial failure and batches

GraphQL lets you send several mutations in one document using aliases, and the API executes them one after another. Each succeeds or fails independently. There is no transaction around them:

GRAPHQL
mutation TwoProducts($a: ProductCreateInput!, $b: ProductCreateInput!) {
  first: productCreate(product: $a) {
    product { id }
    userErrors { field message }
  }
  second: productCreate(product: $b) {
    product { id }
    userErrors { field message }
  }
}

If first succeeds and second hits a validation problem, you get a product ID and a user error in the same response, with the first change already saved. Your code must look at every alias. If your business logic needs all-or-nothing, you have to implement it yourself: for example by saving the created IDs, and deleting or reverting them if a later step fails. The ideas behind safe retries are in Idempotency.

Retrying a mutation also deserves thought. If the network drops after Shopify saved your change but before the response reached you, a blind retry of productCreate may create a duplicate. Prefer mutations that are naturally repeatable (for example metafieldsSet, which sets a value, or an update to a known ID), or check for the object before creating it again.

For very large write jobs (thousands of objects), a loop of single mutations is slow and expensive. Use a bulk mutation, covered in Bulk Operations.

Updating and deleting

The same pattern repeats for the other operations. Updates take the object ID inside the input, and deletes take the ID alone:

GRAPHQL
mutation Rename($product: ProductUpdateInput!) {
  productUpdate(product: $product) {
    product { id title }
    userErrors { field message }
  }
}
JSON
{ "product": { "id": "gid://shopify/Product/9001", "title": "Linen shirt (summer)" } }

Only the fields you send change; fields you omit stay as they are. This is why update inputs are usually smaller than create inputs, and why a missing field is not the same as an empty one: send null or an empty value only when you mean to clear it.

Try it: a wrapper that sorts the errors

The wrapper below takes a fake client and a mutation name. It returns either the data or a typed failure: retry for throttling and server trouble, fatal for permission and syntax problems, and invalid for user errors. A scripted fake client replays a fixed set of responses so that the output is the same every time.

Node.js An error-handling wrapper for mutations

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.

Look at how each case ends. A throttled request is retried and succeeds, a blank title becomes an invalid result with a readable message, and a missing scope is fatal (retrying will never help). That separation is the whole point: your job runner can retry retry, report invalid to the merchant or skip the item, and page a developer for fatal.

Handling a batch of items

When you create or update many items one by one, collect the results instead of stopping at the first problem. The next example processes a list, keeps going after invalid items, and prints a summary a merchant could actually use.

Node.js Collect successes and failures from a batch

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.

Reporting by row number is what turns a failed import from a mystery into something the merchant can fix.

Common mistakes

  • Checking only the HTTP status or only errors. A rejected write is a 200 with userErrors.
  • Not selecting userErrors at all. If you leave it out of the selection set, Shopify cannot show you the problem, and the failure is silent.
  • Matching on message text. Messages can change and are translated. Prefer code when it exists, and field for placement.
  • Retrying non-repeatable creates blindly. That can create duplicates. Make writes repeatable or check first.
  • Assuming a batch is atomic. Aliased mutations are independent; plan for half-done work.
  • Hard-coding input shapes. They change by version; test against the version you ship.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A mutation returns HTTP 200, errors is absent, and userErrors contains one item. What happened?

    userErrors report rejected data inside a normal response. A missing scope would appear in the top-level errors list as ACCESS_DENIED.
  2. 2. Which problem belongs in the top-level errors list rather than userErrors?

    Throttling, syntax errors and permission problems concern the request itself. Data validation problems come back as userErrors.
  3. 3. You send two aliased mutations in one request and the second returns a userError. What is the state of the first?

    There is no transaction around a GraphQL document. Each mutation field runs and succeeds or fails on its own.
  4. 4. Why is branching on the userError code safer than on its message?

    Use code when the mutation offers it. Keep the message for display.

Summary

  • A mutation takes an input object, returns the changed object and should always select userErrors.
  • Top-level errors mean the request failed (syntax, scope, throttling, server trouble); userErrors mean the data was rejected inside an otherwise valid response.
  • HTTP 200 is not success: check transport, then errors, then userErrors, then use the result.
  • Aliased mutations in one document are independent, so plan for partial failure and make retries safe.
  • Wrap mutations in one function that returns typed outcomes (ok, invalid, retry, fatal) so jobs behave consistently.
  • Input names and shapes change between versions; read the schema for the version you target.

Next: Metafields and Metaobjects from the API.