Shopify Storefront API

https://shopify.dev/docs/api/storefront
Admin
Shopify Storefront API is a GraphQL API that enables developers to create unique customer...
Tokens:322,113
Snippets:2,601
Trust Score:9.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Storefront API client installation

Source: https://shopify.dev/docs/api/storefront

Install the official lightweight JavaScript client for the Storefront API using npm or yarn.

```bash
npm install --save @shopify/storefront-api-client
// or
yarn add @shopify/storefront-api-client
```

--------------------------------

### Shopify Ruby library installation

Source: https://shopify.dev/docs/api/storefront

Install the official Ruby client library using Bundler.

```bash
bundle add shopify_api
```

--------------------------------

### Shopify API installation

Source: https://shopify.dev/docs/api/storefront

Install the full suite library for TypeScript/JavaScript Shopify apps using npm or yarn.

```bash
npm install --save @shopify/shopify-api
// or
yarn add @shopify/shopify-api
```

--------------------------------

### Retrieve first three products - Response

Source: https://shopify.dev/docs/api/storefront/latest/queries/products

Example JSON response showing three product edges with cursors and titles.

```json
{
  "products": {
    "edges": [
      {
        "cursor": "eyJsYXN0X2lkIjo2NTcyMTE2NSwibGFzdF92YWx1ZSI6IjY1NzIxMTY1In0=",
        "node": {
          "title": "Storefront Spoon"
        }
      },
      {
        "cursor": "eyJsYXN0X2lkIjoyNjMwNzE4NTYsImxhc3RfdmFsdWUiOiIyNjMwNzE4NTYifQ==",
        "node": {
          "title": "Storefront Shoes"
        }
      },
      {
        "cursor": "eyJsYXN0X2lkIjo1Mzg4MjUyNjEsImxhc3RfdmFsdWUiOiI1Mzg4MjUyNjEifQ==",
        "node": {
          "title": "Guitar"
        }
      }
    ]
  }
}
```

--------------------------------

### Response for getProductMedia

Source: https://shopify.dev/docs/api/storefront/latest/queries/product

Example JSON response showing product media edges with image URLs.

```json
{
  "product": {
    "id": "gid://shopify/Product/929898465",
    "media": {
      "edges": [
        {
          "node": {
            "mediaContentType": "IMAGE",
            "alt": "",
            "image": {
              "url": "https://cdn.shopify.com/s/files/1/0003/2595/3821/products/draft58.jpg?v=1773111786"
            }
          }
        },
        {
          "node": {
            "mediaContentType": "IMAGE",
            "alt": "",
            "image": {
              "url": "https://cdn.shopify.com/s/files/1/0003/2595/3821/products/draft59.jpg?v=1773111786"
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Create a customer - Response

Source: https://shopify.dev/docs/api/storefront/latest/mutations/customerCreate

Example response from the customerCreate mutation showing the created customer and empty customerUserErrors array.

```json
{
  "customerCreate": {
    "customer": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "johnsmith@shopify.com",
      "phone": "+15146669999",
      "acceptsMarketing": true
    },
    "customerUserErrors": []
  }
}
```

--------------------------------

### Retrieve local prices for a product - Response

Source: https://shopify.dev/docs/api/storefront/latest/queries/product

Example JSON response for the local pricing query, showing price in CAD.

```json
{
  "product": {
    "variants": {
      "nodes": [
        {
          "price": {
            "amount": "90.0",
            "currencyCode": "CAD"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Response for get customer by access token

Source: https://shopify.dev/docs/api/storefront/latest/queries/customer

Example JSON response containing the customer object with the requested fields.

```json
{
  "customer": {
    "id": "gid://shopify/Customer/410535040",
    "firstName": "John",
    "lastName": "Smith",
    "acceptsMarketing": false,
    "email": "johnsmith@example.com",
    "phone": "+16134504533"
  }
}
```

--------------------------------

### Node.js Client for getProductMedia

Source: https://shopify.dev/docs/api/storefront/latest/queries/product

Node.js example using the Storefront client to query product media. Requires a storefrontAccessToken and the shopify client library.

```javascript
const client = new shopify.clients.Storefront({
  domain: 'your-development-store.myshopify.com',
  storefrontAccessToken,
});
const data = await client.query({
  data: {
    "query": `query getProductMedia($id: ID!) {
      product(id: $id) {
        id
        media(first: 10) {
          edges {
            node {
              mediaContentType
              alt
              ...mediaFieldsByType
            }
          }
        }
      }
    }
    
    fragment mediaFieldsByType on Media {
      ... on ExternalVideo {
        id
        embeddedUrl
      }
      ... on MediaImage {
        image {
          url
        }
      }
      ... on Model3d {
        sources {
          url
          mimeType
          format
          filesize
        }
      }
      ... on Video {
        sources {
          url
          mimeType
          format
          height
          width
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/929898465"
    },
  },
});
```

--------------------------------

### Get recent products via curl (no token)

Source: https://shopify.dev/docs/api/storefront

Sends a POST request to the Storefront API GraphQL endpoint without an access token. This example is incomplete for authenticated requests; use the version with the X-Shopify-Storefront-Access-Token header for real calls.

```bash
curl -X POST \
https://{store_name}.myshopify.com/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-d '{
"query": "{
products(first: 3) {
edges {
node {
id
title
}
}
}
}"
}'
```

--------------------------------

### Ruby: Create REST client and access token

Source: https://shopify.dev/docs/api/storefront

Complete Ruby example that creates a REST client from an offline session and then creates a new storefront access token.

```ruby
# Create a REST client from your offline session
client = ShopifyAPI::Clients::Rest::Admin.new(
  session: session
)

# Create a new access token
storefront_token_response = client.post(
  path: 'storefront_access_tokens',
  body: {
    storefront_access_token: {
      title: "This is my test access token",
    }
  }
)

storefront_access_token = storefront_token_response.body['storefront_access_token']['access_token']
```

--------------------------------

### Shop Reference Example

Source: https://shopify.dev/docs/api/storefront/latest/queries/shop

An example query referencing the Shop object in the Storefront API.

```APIDOC
## Example: shop reference

### Description
An example query that references the Shop object.

### Query
```graphql
query {
  shop {
    socialLoginProviders {
      # fields
    }
    subscriptionPolicy {
      # fields
    }
    termsOfSale {
      # fields
    }
    termsOfService {
      # fields
    }
  }
}
```
```

--------------------------------

### Ruby Storefront client querying products

Source: https://shopify.dev/docs/api/storefront

Use this Ruby example to query products with the Shopify API Storefront client. It initializes the client with your shop and access token, then executes a query to fetch the first three products.

```ruby
# Load the access token as per instructions above
store_front_access_token = '<my token>'
# Shop from which we're fetching data
shop = 'my-shop.myshopify.com'

# The Storefront client takes in the shop url and the Storefront Access Token for that shop.
storefront_client = ShopifyAPI::Clients::Graphql::Storefront.new(
  shop,
  storefront_access_token
)

# Call query and pass your query as `data`
my_query = <<~QUERY
  {
    products (first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
QUERY
products = storefront_client.query(query: my_query)
```

--------------------------------

### Create a customer - Node.js client

Source: https://shopify.dev/docs/api/storefront/latest/mutations/customerCreate

Node.js example using the Shopify Storefront client to execute the customerCreate mutation. Requires a storefrontAccessToken and the shopify client library.

```javascript
const client = new shopify.clients.Storefront({
  domain: 'your-development-store.myshopify.com',
  storefrontAccessToken,
});
const data = await client.query({
  data: {
    "query": `mutation customerCreate($input: CustomerCreateInput!) {
      customerCreate(input: $input) {
        customer {
          firstName
          lastName
          email
          phone
          acceptsMarketing
        }
        customerUserErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "input": {
            "firstName": "John",
            "lastName": "Smith",
            "email": "johnsmith@shopify.com",
            "phone": "+15146669999",
            "password": "5hopify",
            "acceptsMarketing": true
        }
    },
  },
});
```

--------------------------------

### Shopify API Storefront client querying products

Source: https://shopify.dev/docs/api/storefront

Use this example with the Shopify API library to query products. It initializes a Storefront client with your shop domain and access token, then executes a query to fetch the first three products.

```javascript
// Load the access token as per instructions above
const storefrontAccessToken = '<my token>';
// Shop from which we're fetching data
const shop = 'my-shop.myshopify.com';

// StorefrontClient takes in the shop url and the Storefront Access Token for that shop.
const storefrontClient = new shopify.clients.Storefront({
  domain: shop,
  storefrontAccessToken,
});

// Use client.query and pass your query as `data`
const products = await storefrontClient.query({
  data: `{
    products (first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }`,
});
```

--------------------------------

### Shopify app React Router package installation

Source: https://shopify.dev/docs/api/storefront

Install the official package for React Router apps using npm or yarn.

```bash
npm install --save @shopify/shopify-app-react-router
// or
yarn add @shopify/shopify-app-react-router
```

--------------------------------

### Retrieve local prices for a product - Node.js client

Source: https://shopify.dev/docs/api/storefront/latest/queries/product

Node.js example using the Storefront client to query local pricing with @inContext.

```javascript
const client = new shopify.clients.Storefront({
  domain: 'your-development-store.myshopify.com',
  storefrontAccessToken,
});
const data = await client.query({
  data: `query ProductPricing @inContext(country: CA) {
    product(handle: "wool-sweater") {
      variants(first: 1) {
        nodes {
          price {
            amount
            currencyCode
          }
        }
      }
    }
  }`,
});
```

--------------------------------

### Response for cartDeliveryAddressesRemove

Source: https://shopify.dev/docs/api/storefront/latest/mutations/cartDeliveryAddressesRemove

Example response showing an empty addresses array after removal.

```json
{
  "cartDeliveryAddressesRemove": {
    "userErrors": [],
    "warnings": [],
    "cart": {
      "id": "gid://shopify/Cart/c1-8f1f41212a211bb1502fd5e27fa5b413?key=f0c5f2509893edbafaab3de9c160b9a8",
      "delivery": {
        "addresses": []
      }
    }
  }
}
```

--------------------------------

### Node.js example for cartDeliveryAddressesRemove

Source: https://shopify.dev/docs/api/storefront/latest/mutations/cartDeliveryAddressesRemove

Uses the Storefront API client to query the mutation.

```javascript
const client = new shopify.clients.Storefront({
  domain: 'your-development-store.myshopify.com',
  storefrontAccessToken,
});
const data = await client.query({
  data: {
    "query": `mutation CartDeliveryAddressesRemove($id: ID!, $addressIds: [ID!]!) {
      cartDeliveryAddressesRemove(cartId: $id, addressIds: $addressIds) {
        userErrors {
          message
          code
          field
        }
        warnings {
          message
          code
          target
        }
        cart {
          id
          delivery {
            addresses {
              id
              selected
              oneTimeUse
              address {
                ... on CartDeliveryAddress {
                  firstName
                  lastName
                }
              }
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Cart/c1-8f1f41212a211bb1502fd5e27fa5b413?key=f0c5f2509893edbafaab3de9c160b9a8",
        "addressIds": [
            "gid://shopify/CartSelectableAddress/delivery-address-1"
        ]
    },
  },
});
```

--------------------------------

### Variables for cartDeliveryAddressesRemove

Source: https://shopify.dev/docs/api/storefront/latest/mutations/cartDeliveryAddressesRemove

Example variables for the mutation, including a cart ID and an address ID.

```json
{
  "id": "gid://shopify/Cart/c1-8f1f41212a211bb1502fd5e27fa5b413?key=f0c5f2509893edbafaab3de9c160b9a8",
  "addressIds": [
    "gid://shopify/CartSelectableAddress/delivery-address-1"
  ]
}
```

--------------------------------

### Hydrogen storefront client setup

Source: https://shopify.dev/docs/api/storefront

Initializes a Hydrogen storefront client using environment variables for the public token, store domain, and API version.

```javascript
const storefront = createStorefrontClient({
publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
storeDomain: `https://\${env.PUBLIC_STORE_DOMAIN}\`,
storefrontApiVersion: env.PUBLIC_STOREFRONT_API_VERSION || '2023-01',
});
```
Tokens:
Raw