Getting started with the GraphQL Admin and REST Admin APIs

The GraphQL Admin and REST Admin APIs let you build apps and other integrations for the Shopify admin using GraphQL or REST. With the APIs, you can create apps that offer functionality at every stage of a store's operation, including shipping, fulfillment, and product management.

Authentication

The GraphQL Admin and REST Admin APIs require a Shopify access token (for public apps and custom apps) or an API password (for private apps) for making authenticated requests.

You can obtain an access token either by following the OAuth authorization process or by creating a private app and using that app's API password.

Authenticate using OAuth

To get the access token, follow the OAuth authorization flow in the OAuth guide. Include the access token as a X-Shopify-Access-Token header in your requests.

Authenticate using basic HTTP authentication

  1. From your Shopify admin, click Apps.
  2. Click Manage private apps.
  3. Click Create a new private app.
  4. Enter the details for your private app.
  5. Click Save.
  6. Use the generated API password as the access token.

GraphQL Admin API

The GraphQL Admin API is a GraphQL-based alternative to the REST-based Admin API, and makes the functionality of the Shopify admin available at a single GraphQL endpoint:

POST https://{shop}.myshopify.com/admin/api/2021-01/graphql.json

You can access the GraphQL Admin API using the GraphiQL app, curl, or any HTTP client:

Use the GraphiQL app

We recommend installing Shopify’s own GraphiQL app to explore your shop’s data using the GraphQL Admin API. After you've installed the app, you can test it by running the following query:

POST https://{shop}.myshopify.com/admin/api/2021-01/graphql.json

  query {
    shop {
      name
      primaryDomain {
        url
        host
      }
    }
  }

View response

JSON response:

    {
      "data": {
        "shop": {
          "name": "graphql",
          "primaryDomain": {
            "url": "https://graphql.myshopify.com",
            "host": "graphql.myshopify.com"
          }
        }
      }
    }

Use curl

The following example shows a query for the first 5 product IDs and handles. Replace {shop} with your store’s domain and {password} with the access token you generated in the Authentication section.

POST https://{shop}.myshopify.com/admin/api/2021-01/graphql.json

  curl -X POST \
  https://{shop}.myshopify.com/admin/api/2021-01/graphql.json \
  -H 'Content-Type: application/graphql' \
  -H 'X-Shopify-Access-Token: {password}' \
  -d '
  {
    products(first: 5) {
      edges {
        node {
          id
          handle
        }
      }
      pageInfo {
        hasNextPage
      }
    }
  }
  '

View response

JSON response:

  {
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/1974208299030",
            "handle": "rough-snowflake-camisole"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true
      }
    }
  }
}

Example query

In GraphQL, queries are the equivalent of REST’s GET action verb. They generally begin with one of the objects listed under QueryRoot and can get data from any connections that object has. Even though a POST is being sent to the GraphQL endpoint, if the body only contains queries, then data will only be retrieved and not modified.

The following example shows a query for the quantity of inventory items available at a location:

POST https://{shop}.myshopify.com/admin/api/2021-01/graphql.json

  {
    inventoryItem(id: "gid://shopify/InventoryItem/19848949301270") {
      id
      inventoryLevels(first: 10) {
        edges {
          node {
            available
          }
        }
      }
    }
  }

View response

JSON response:

  {
  "data": {
    "inventoryItem": {
      "id": "gid://shopify/InventoryItem/19848949301270",
      "inventoryLevels": {
        "edges": [
          {
            "node": {
              "available": 5
            }
          }
        ]
      }
    }
  }
}

Example mutation

Mutations are the equivalent of REST’s data-modifying action verbs, such as PUT or DELETE. The following example shows a mutation that increases the available inventory at a location:

POST https://{shop}.myshopify.com/admin/api/2021-01/graphql.json

  mutation {
    inventoryAdjustQuantity(
      input:{
        inventoryLevelId: "gid://shopify/InventoryLevel/13570506808?inventory_item_id=10820777115690"
        availableDelta: 1
      }
    )
    {
      inventoryLevel {
        available
      }
    }
  }

View response

JSON response:

  {
  "inventoryAdjustQuantity": {
    "inventoryLevel": {
      "available": 9
    },
    "userErrors": []
  }
}

REST Admin API

You can access the REST Admin API using curl or any other HTTP client. REST Admin API endpoints are organized by resource. You'll need to use different API endpoints depending on the service that your app provides.

Example GET request using curl

The following curl request retrieves information by using the Shop resource and the GET /admin/api/2021-01/shop.json endpoint. Replace {shop} with your store’s domain and {password} with the access token you generated in the Authentication section.

Request:

  curl -X GET \
  https://{shop}.myshopify.com/admin/api/2021-01/shop.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {password}'

View response

JSON response:

{
  "shop": {
    "id": 690933842,
    "name": "Apple Computers",
    "email": "steve@apple.com",
    "domain": "shop.apple.com",
    "province": "California",
    "country": "US",
    "address1": "1 Infinite Loop",
    "zip": "95014",
    "city": "Cupertino",
    "source": null,
    "phone": "1231231234",
    "latitude": 45.45,
    "longitude": -75.43,
    "primary_locale": "en",
    "address2": "Suite 100",
    "created_at": "2007-12-31T19:00:00-05:00",
    "updated_at": "2021-01-01T14:39:35-05:00",
    "country_code": "US",
    "country_name": "United States",
    "currency": "USD",
    "customer_email": "customers@apple.com",
    "timezone": "(GMT-05:00) Eastern Time (US & Canada)",
    "iana_timezone": "America/New_York",
    "shop_owner": "Steve Jobs",
    "money_format": "$",
    "money_with_currency_format": "$ USD",
    "weight_unit": "lb",
    "province_code": "CA",
    "taxes_included": null,
    "auto_configure_tax_inclusivity": null,
    "tax_shipping": null,
    "county_taxes": true,
    "plan_display_name": "Shopify Plus",
    "plan_name": "enterprise",
    "has_discounts": true,
    "has_gift_cards": true,
    "myshopify_domain": "apple.myshopify.com",
    "google_apps_domain": null,
    "google_apps_login_enabled": null,
    "money_in_emails_format": "$",
    "money_with_currency_in_emails_format": "$ USD",
    "eligible_for_payments": true,
    "requires_extra_payments_agreement": false,
    "password_enabled": false,
    "has_storefront": true,
    "eligible_for_card_reader_giveaway": false,
    "finances": true,
    "primary_location_id": 905684977,
    "cookie_consent_level": "implicit",
    "visitor_tracking_consent_preference": "allow_all",
    "force_ssl": true,
    "checkout_api_supported": true,
    "multi_location_enabled": false,
    "setup_required": false,
    "pre_launch_enabled": false,
    "enabled_presentment_currencies": [
      "USD"
    ]
  }
}

Example POST request

The following example illustrates how to create a product that has a draft status by using the Product resource and the POST /admin/api/2021-01/products.json endpoint.

Request:

POST https://{shop}.myshopify.com/admin/api/2021-01/products.json

{
  "product": {
    "title": "Burton Custom Freestyle 151",
    "body_html": "<strong>Good snowboard!</strong>",
    "vendor": "Burton",
    "product_type": "Snowboard",
    "status": "draft"
  }
}

View response

JSON response:

{
  "product": {
    "id": 4,
    "title": "Burton Custom Freestyle 151",
    "body_html": "<strong>Good snowboard!<\/strong>",
    "vendor": "Burton",
    "product_type": "Snowboard",
    "created_at": "2020-09-09T17:03:05-07:00",
    "handle": "burton-custom-freestyle-151",
    "updated_at": "2020-09-09T17:03:06-07:00",
    "published_at": "2020-09-09T17:03:05-07:00",
    "template_suffix": null,
    "status": "draft",
    "published_scope": "web",
    "tags": "",
    "admin_graphql_api_id": "gid:\/\/shopify\/Product\/4",
    "variants": [
      {
        "id": 5,
        "product_id": 4,
        "title": "Default Title",
        "price": "0.00",
        "sku": "",
        "position": 1,
        "inventory_policy": "deny",
        "compare_at_price": null,
        "fulfillment_service": "manual",
        "inventory_management": null,
        "option1": "Default Title",
        "option2": null,
        "option3": null,
        "created_at": "2020-09-09T17:03:06-07:00",
        "updated_at": "2020-09-09T17:03:06-07:00",
        "taxable": true,
        "barcode": null,
        "grams": 0,
        "image_id": null,
        "weight": 0.0,
        "weight_unit": "kg",
        "inventory_item_id": 789,
        "inventory_quantity": 0,
        "old_inventory_quantity": 0,
        "requires_shipping": true,
        "admin_graphql_api_id": "gid:\/\/shopify\/ProductVariant\/6"
      }
    ],
    "options": [
      {
        "id": 456,
        "product_id": 4,
        "name": "Title",
        "position": 1,
        "values": [
          "Default Title"
        ]
      }
    ],
    "images": [],
    "image": null
  }
}

Example PUT request

The following example illustrates how to update the postal code of a customer address by using the Customer Address resource and the PUT /admin/api/2021-01/customers{customer_id}/addresses/{address_id}.json endpoint.

Request:

PUT /admin/api/2021-01/customers/207119551/addresses/207119551.json

{
  "address": {
    "id": 207119551,
    "zip": "90210"
  }
}

View response

JSON response:

{
  "customer_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "90210",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
  }
}

Example DELETE request

The following example illustrates how to delete an order by using the Order resource and the DELETE /admin/api/2021-01/orders/{order_id}.json endpoint.

Request:

DELETE /admin/api/2021-01/orders/450789469.json

View response

JSON response:

HTTP/1.1 200 OK
{}

Next steps