Shopify Admin API GraphQL Overview

Shopify Admin API Endpoint - REST or GraphQL?

• Lots of graphQL query examples

• Creating your first query

• Authorization

• Filtering GraphQL

• Operators / Comparators

• Pagination

• Primitives, Objects and Collections

• Managing your GraphQL quota

Table of Contents

Just Want your Shopify Data?

• Syncing Shopify to Google Sheets - install our Google Sheets addon used by 100,000s of other data users, read more about the addon, some Shopify specific examples:
• Sync Shopify Orders to Google Sheets
• Sync Shopify Products to Sheets

• Sync Shopify API to Airtable - install our airtable addon in the marketplace

• Connect Shopify API Data to Excel - install our Excel addon or contact support

• Export Shopify API Data to Data Studio - contact support to join our beta

• Export Shopify API Data to PowerBI - contact support to join our beta

• Shopify API to Databases (S3, BigQuery, MySQL, Postgres) - contact support to join our beta

No More Pitches, Help Me Use the API Directly

Authorization

Creating a Connection to the GraphQL Endpoint

1. Click Extensions

2. Choose SyncWith Addon

3. Click Manage Connections

4. Cut and paste the Admin API endpoint
1. https://{store_name}.myshopify.com/admin/api/2022-04/graphql.json

5. Set the method to POST

6. Give the connection a name eg Shopify Orders

7. Complete Authorization as per above if you have not already

8. Select Shopify Login (Oauth) authentication

9. Select your Shopify store (will only show if you’ve completed authorization)

10. Syncwith automatically detects the path parameter {your-domain} in the endpoint path - so you just need to enter some non spaced random text. You don’t need to fill out your actual store name as we automatically populate it as long as you use Oauth and you’ve authenticated with Shopify. In this instance we wrote blahblahblah which will work.

 

• Inventory

• Orders

• Products and collections

• Shopify Payments

• Customers

• Discounts and marketing

Completing a Simple Query - First 10 Orders

{
	orders(first: 10) {
		edges {
			node { id }
		}
	}
}

1. Enter your graphQL code into the Body setting of the

2. Click Preview

3. Preview window will open and show you something like

Try clicking the View raw data toggle

SyncWith lets you automatically handle your JSON expansions by clicking the + expand button

Shipping the Data into Google Sheets

To insert the order data into Google Sheets simply click Insert

Changing the Order of Results

• Default Sort Key: CREATE_AT

• Default Sort Order: Ascending

{
	orders(first:10 reverse:true") {
		edges {
			node { 
				id 
			}
		}
	}
}

{
	orders(first:10 sortKey:TOTAL_PRICE) {
		edges {
			node { 
				id
			}
		}
	}
}

Recap

• We can now authenticate to Shopify

• We can write a basic GraphQL query to get back our first 10 orders

• We can specify a simple Order primitive like ID and get it back

• We can handle the JSON transform and move the data into Google Sheets

• We can’t filter the orders returned

Filtering a GraphQL Query

Useful Tool: Shopify GraphQL Explorer

Shopify has an interactive GraphQL explorer and query engine that is great to test queries and see the results live. This is the best way to author your query and then cut and paste it into syncwith. It can be found at https://shopify.dev/graphiql/admin-graphiql

Adding a Query Connection Parameter to Filter Orders

• Orders created on or after Jan 1, 2022

• Orders that have been cancelled

query:"created_at:>=2022-03-1 AND 
status:CANCELLED"

Available Filter Properties

Operators

• AND OR NOT

• state:enabled OR state:disabled

• eg NOT source_name:iphone AND NOT source_name:android

status:cancelled OR status:closed

Comparators

{
	orders(
		first:200, 
		reverse:true,
		query:"created_at:>=2021-11-01 AND created_at:<=2021-11-30"
	)
	{
		edges{
			node {
				id
			}
		}
	}
}

Grouping Filters

(source_name:iphone OR source_name:android) AND status:closed 

Recap

• We can now filter our query to ensure we’re only getting the orders back of interest

• We can set our sort key and sort ordering

• We’ve seen a couple examples of how to specify the values but need more instruction on how get the the data we want out of graphQL

• We are still only returning a fixed number of results eg first:200, we need more instruction on how to page through results

Understanding Pagination with the Shopify GraphQL API

1. Send the query to Shopify

2. Get x results

3. Get the ID of the last result

4. Send another query and ask for the x more items starting after the last result (using the connection argument after)

5. And so on and so forth till there are no more results.

{
	orders(first:3){
		edges{
			node { id }
		}
	}
}

"data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/1379031122002"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031253074"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031318610"
          }
        }
      ]
    }
  }

{
	orders(first:3){
		edges{
			node { id }
			cursor #getting the cursor to each specific edge / order
		}
	}
}

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/1379031122002"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxMTIyMDAyLCJsYXN0X3ZhbHVlIjoiMjAxNi0wNi0xNCAwMzo0MDo0Mi4wMDAwMDAifQ=="
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031253074"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxMjUzMDc0LCJsYXN0X3ZhbHVlIjoiMjAxNi0wNi0xOCAwMzowNjo1NS4wMDAwMDAifQ=="
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031318610"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxMzE4NjEwLCJsYXN0X3ZhbHVlIjoiMjAxNi0wNi0yMyAyMTo1MTowNS4wMDAwMDAifQ=="
        }
      ]
    }
  }

{
	orders(
	first:3, 
	after:"eyJsYXN0X2lkIjoxMzc5MDMxMjUzMDc0LCJsYXN0X3ZhbHVlIjoiMjAxNi0wNi0xOCAwMzowNjo1NS4wMDAwMDAifQ=="
	){
		edges{
			node { id }
			cursor #getting the cursor to each specific edge / order
		}
	}
}

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/1379031318610"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxMzE4NjEwLCJsYXN0X3ZhbHVlIjoiMjAxNi0wNi0yMyAyMTo1MTowNS4wMDAwMDAifQ=="
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031384146"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxMzg0MTQ2LCJsYXN0X3ZhbHVlIjoiMjAxNi0wNy0xMyAxNzo1OTowMi4wMDAwMDAifQ=="
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031482450"
          },
          "cursor": "eyJsYXN0X2lkIjoxMzc5MDMxNDgyNDUwLCJsYXN0X3ZhbHVlIjoiMjAxNi0wNy0xNiAyMDo0NDozNy4wMDAwMDAifQ=="
        }
      ]
    }
  }

{
	orders(
	first:5, 
	query:"created_at:>=2021-12-01 AND created_at:<=2021-12-07"
	){
		edges{
			node { id }
			cursor #getting shopify to output the cursor here
		}
	}
}

• The path that contains the cursor

• The variable/parameter that contains the cursor value

• Above we tested a fixed cursor after:"eyJsYXN0X2lkI..." to show how the after parameter works.

• We need a dynamic cursor that gets updated on each request

• Synwith lets us pass in a dynamic value to the endpoint. To do this we need to add a variable in the GraphQL statement such that the connection argument after:

• SyncWith will handling updating this variable with the appropriate cursor

• This is why we need to tell SyncWith
• the variable name
• the path to the cursor

query ($after: String) #adding the variable after which is of type string
{
	orders(
	first:5, 
	query:"created_at:>=2021-12-01 AND created_at:<=2021-12-07",
	after:$after #telling shopify to start at after our variable $after
	){	
		edges{
			node { id }
			cursor #getting shopify to output the cursor here
		}
	}
}

• We have a variable called a$fter that is used to tell Shopify where to start

• We have the cursor being outputed at every edge.

• We’re telling Syncwith what the variable name is variables.after

• We’re telling Syncwith the path to the cursor data.orders.edges.4.cursor

• SyncWith will dynamically replace the variable $after with the correct cursor value

• We’re telling Syncwith that the value of the cursor is on the 4th edge - eg the last order returned by the previous query

• SyncWith will conduct multiple queries incrementing the cursor on each query

• The reason we use edges.4.cursor and not edges.5.cursor is because the edges are returned as an array and the first item is 0, so the 5th item is array item 4

• If you change the number of orders to sat first:20 then you’ll need to update the currsor path to be data.orders.edges.19.cursor, to make sure you’re always getting the cursor from the last item returned.

Recap

• We can now write a query and filter to get only the items we want

• We can paginate the results, format the JSON and get the data into Google Sheets

• Can’t access various items within an object, for example if we’re getting orders back:
• How do we get values from objects within the order
• How do we enumerate collections within an object - eg the line items that make up the order or the transactions that make up the full payment, etc.

Primitives, Objects and Collections

Objects

• Order.billingAddress - type MailingAddress

• Order.currentTotalPriceSet - type MoneyBag

{
	orders(first:10){
		edges{
			node { id billingAddress }
		}
	}
}

"errors": [
    {
      "message": "Field must have selections (field 'billingAddress' returns MailingAddress but has no selections. Did you mean 'billingAddress { ... }'?)",
      "locations": [
        {
          "line": 4,
          "column": 14
        }
      ],
      "path": [
        "query",
        "orders",
        "edges",
        "node",
        "billingAddress"
      ]

{
	orders(first:10){
		edges{
			node { id billingAddress{name address1 address2 city country}
		}
	}
}

Primitives

• Order.cancelledAt - DateTime

• Order.confirmed - Boolean

• Order.discountCode - String

• Order.email - String

• Order.id - ID

• Order.note - String

• Order.refundable - Boolean

{
	orders(first:10){
		edges{
			node { 
			cancelledAt
			confirmed
			discountCode
			email
			id
			note
			refundable
			}
		}
	}
}

Collections

• Line Items - eg an order is made up of 5 products

• Events - an order has many events from it’s creation to it’s delivery, each event is tracked seperately

• Agreements - an order can have many sales agreements

• Fulfillments - an order can require multiple shipments to fulfil the order

{
	orders(first:10){ # orders is a collection
		edges{
			node {id} # the node is a specific order of which we want the ID
		}
	}
}

orders(first:10) #the order collection can take many arguments in this case first

Shopify Documentation will show you the arguments available. For example Order.fulfillments has one available argument first.

Whereas Order.LineItems takes many more arguments:

• first

• after

• last

• before

• reverse

Getting a Collection of Collections - Eg Orders & LineItems

{
	orders(first:2){ # orders is a collection
		edges{
			node {
				id #order id
				lineItems(first:10){edges{node{ id}}} #first 10 lineitems for each order
			}
		}
	}
}

• We got two orders back as expected

• We got 3 line items on the first orders and 4 line items on the second order

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/1379031122002",
            "lineItems": {
              "edges": [
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010689663058"
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010689695826"
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010689728594"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/1379031253074",
            "lineItems": {
              "edges": [
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010690121810"
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010690154578"
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010690187346"
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010690220114"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }

Getting Values out of a Collection

{
	orders(first:1){ # orders is a collection
		edges{
			node {
				id #order id
				lineItems(first:2){edges{node{ #first 10 lineitems for each order
					id #lineitem id
					sku #lineitem sku
					quantity #number ordered of the line item
					name #name of the product
					discountedTotalSet { presentmentMoney { amount } } #price of the item
				}}} 
			}
		}
	}
}

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/1379031122002",
            "lineItems": {
              "edges": [
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010689663058",
                    "sku": "",
                    "quantity": 1,
                    "name": "Glass Head Pins",
                    "discountedTotalSet": {
                      "presentmentMoney": {
                        "amount": "8.0"
                      }
                    }
                  }
                },
                {
                  "node": {
                    "id": "gid://shopify/LineItem/3010689695826",
                    "sku": "",
                    "quantity": 1,
                    "name": "Hot Hemmer",
                    "discountedTotalSet": {
                      "presentmentMoney": {
                        "amount": "23.3"
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }

Adding Pagination - Last 7 days of Orders with Line Items

query ($after: String) #after variable used to paginate our orders
{
	orders(first:5 after:$after query:"created_at:>2022-05-01"){ # orders is a collection
		edges{
			node {
				id #order id
				lineItems(first:2){edges{node{ #first 2 lineitems for each order
					id #lineitem id
					sku #lineitem sku
					quantity #number ordered of the line item
					name #name of the product
					discountedTotalSet { presentmentMoney { amount } } #price of the item
				}}}
			}
			cursor
		}
	}
} 

• Set your variable to variables.after

• Set your path to data.orders.edges.4.cursor

• Hit preview

Writing our First Query that Requires Pagination

Managing GraphQL Quota

• requesting 5 orders at a time

• first 2 line items per order

"extensions": {
    "cost": {
      "requestedQueryCost": 37,
      "actualQueryCost": 33,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 951,
        "restoreRate": 50
      }
    }
  }

Shopify GraphQL Rate Limits

• Your requested query cost cannot exceed a cost of 1000

• You have a budget that you burn through, you start with 1000 and you restore at 50 / second

• Your actual query cost comes out of your budget

• Your currentlyAvailable determines whether Shopify will accept your query
• If requestedQueryCost > currentlyAvailable it will not run
• If requestedQueryCost ≤ currentlyAvailable it will run

Pagenation

• If you’re paginating you will be running multiple queries

• Say each request has a real cost of 200

• Say each request takes 2 seconds to complete

• During each request running you will burn 200 and restore 100, so you’ll lose 1000 from your initial allocation of 1000

• If your query requires you to paginate through more than 10 pages your 11th request will fail

• But the sticker is if you have a high requestedQueryCost that has a low actualQueryCost you can run into the issue where you can’t run queries even though actualQueryCosts ≤ currentlyAvailable

Balancing # of Requests / Query Cost / Query Budget and Query

query ($after: String) #after variable used to paginate our orders
{
	orders(first:5 after:$after query:"created_at:>2022-05-01"){ # orders is a collection
		edges{
			node {
				id #order id
				lineItems(first:50){edges{node{ #first 2 lineitems for each order
					id #lineitem id
					sku #lineitem sku
					quantity #number ordered of the line item
					name #name of the product
					discountedTotalSet { presentmentMoney { amount } } #price of the item
				}}}
			}
			cursor
		}
	}
} 

"extensions": {
    "cost": {
      "requestedQueryCost": 517,
      "actualQueryCost": 59,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 941,
        "restoreRate": 50
      }
    }

query ($after: String) #after variable used to paginate our orders
{
	orders(first:20 after:$after query:"created_at:>2022-05-01"){ # orders is a collection
		edges{
			node {
				id #order id
				lineItems(first:35){edges{node{ #first 2 lineitems for each order
					id #lineitem id
					sku #lineitem sku
					quantity #number ordered of the line item
					name #name of the product
					discountedTotalSet { presentmentMoney { amount } } #price of the item
				}}}
			}
			cursor
		}
	}
} 

{
  "errors": [
    {
      "message": "Query cost is 1462, which exceeds the single query max cost limit (1000).\n\nSee https://shopify.dev/concepts/about-apis/rate-limits for more information on how the\ncost of a query is calculated.\n\nTo query larger amounts of data with fewer limits, bulk operations should be used instead.\nSee https://shopify.dev/tutorials/perform-bulk-operations-with-admin-api for usage details.\n",
      "extensions": {
        "code": "MAX_COST_EXCEEDED",
        "cost": 1462,
        "maxCost": 1000,
        "documentation": "https://shopify.dev/api/usage/rate-limits"
      }
    }
  ]
}

"extensions": {
    "cost": {
      "requestedQueryCost": 951,
      "actualQueryCost": 137,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 863,
        "restoreRate": 50
      }
    }
  }

{
  "errors": [
    {
      "message": "Throttled",
      "extensions": {
        "code": "THROTTLED",
        "documentation": "https://shopify.dev/api/usage/rate-limits"
      }
    }
  ],
  "extensions": {
    "cost": {
      "requestedQueryCost": 951,
      "actualQueryCost": null,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 897,
        "restoreRate": 50
      }
    }
  }
}

Need Help?

• Are you using the Shopify GraphQL to move shopify data somewhere

• We’d love to hear your use cases

• Need to move and keep Shopify data sync’d to a database, BigQuery, PowerBI, S3, etc. We’d love to hear from you to see if we can help

• Reach out to us at https://syncwith.com/support