GraphQL variables

You can simplify GraphQL queries and mutations by extracting data into separate variables. GraphQL variables let you re-use the same requests with different arguments.

Variable structure

GraphQL requests can be split into two sections: the query, and variables.

In the query section, GraphQL variables begin with the $ symbol and are declared after the query or mutation keyword, similar to passing an argument to a function.

When you declare a variable, you need to specify its type, such as CustomerInput. This lets GraphQL know that you intend to refer to this type by this variable name later in the actual query.

The following query declares an $input variable and passes it to the input argument.

mutation($input: CustomerInput!) {
  customerCreate(input: $input) { ... }
}

In the variables section, the variables themselves are defined as a JSON object.

The following JSON object defines the $input variable for the query above.

{
  "input": {
    "firstName": "Greg",
    "lastName": "Variables",
    "email": "gregvariables@teleworm.us"
  }
}

Simplify the customer creation request

The following example uses the customerCreate mutation from the previous article, but simplifies the mutation by using variables. The result is a much cleaner and reusable mutation.

POST /admin/api/2021-01/graphql.json

mutation ($input: CustomerInput!) {
  customerCreate(input: $input)
  {
    customer {
      id
      displayName
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "input": {
    "firstName": "Greg",
    "lastName": "Variables",
    "email": "gregvariables@teleworm.us"
  }
}

JSON response

{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid://shopify/Customer/1310038130710",
        "displayName": "Greg Variables"
      },
      "userErrors": []
    }
  }
  ...
}

Run in GraphiQL

Variables in cURL

Because variables are a core concept of GraphQL, you can use them outside of fully featured clients. For example, you can perform the customerCreate mutation with variables by using cURL.

The cURL command below creates a customer. The JSON data object has two properties:

  • query — The mutation, provided as a string.
  • variables - An object for holding variables. The only variable is the input object that's used for the mutation.

To run the cURL command from the command line, make the following substitutions:

  • { store } — The name of your development store.
  • { access_token } — Your app's API access token.
curl -X POST \
https://{ store }.myshopify.com/admin/api/2021-01/graphql.json  \
-H 'Content-Type: application/json' \
-H 'x-shopify-access-token: { access_token }' \
-d '{
  "query": "mutation($input: CustomerInput!) { customerCreate(input: $input) { customer { id displayName } userErrors { field message } } }",
  "variables": {
    "input": {
      "firstName": "Greg",
      "lastName": "Variables",
      "email": "gregvariables@teleworm.us""
    }
  }
}'

The response will look similar to this:

{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid://shopify/Customer/1322001989654",
        "displayName": "Greg Variables"
      },
      "userErrors": []
    }
  },
  ...
}

Next steps