---
title: Shop Users API reference
description: GraphQL API for reading and writing metafields, managing product lists, and accessing favorites for Shop users.
api_version: unstable latest
source_url:
  html: https://shopify.dev/docs/api/shop-users/latest
  md: https://shopify.dev/docs/api/shop-users/latest.md
---

# Shop Users API

The Shop Users API is a GraphQL API scoped to an individual Shop user. Use it to read and write metafields, manage product lists (wishlists), and access favorites. You authenticate with a user access token obtained from the [Shop Partners API](https://shopify.dev/docs/api/shop-partners/latest).

## Authentication

The Shop Users API uses Bearer token authentication. You get user access tokens by calling the [`fetchTokensForUser`](https://shopify.dev/docs/api/shop-partners/latest/mutations/fetchTokensForUser) mutation on the [Shop Partners API](https://shopify.dev/docs/api/shop-partners/latest).

1. Authenticate with the Partners API using your [client credentials](https://shopify.dev/docs/api/shop/guides/creating-a-client).
2. Call `fetchTokensForUser` with the user's public ID to get an `accessToken` and `refreshToken`.
3. Include the access token as a `Bearer` token in the `Authorization` header on all Users API requests.

## cURL

```bash
curl -X POST \
  https://shop.app/api/users/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -d '{
    "query": "{ user { favorites(first: 10) { nodes { shopifyVariantId } } } }"
  }'
```

Access tokens expire after a set time. When a token expires, use the `refreshToken` to get a new one.

***

## Endpoints and queries

Send `POST` requests to the Users API endpoint:

`https://shop.app/api/users/graphql.json`

All requests must include a `Content-Type: application/json` header and a JSON body with a `query` field containing your GraphQL query or mutation.

***

## Key operations

### Metafields

Read and write custom data on the authenticated user's profile. Metafield definitions are created through the [Shop Partners API](https://shopify.dev/docs/api/shop-partners/latest), and you can read or write values for those definitions through the Users API.

| Query | Description |
| - | - |
| [`metafield`](https://shopify.dev/docs/api/shop-users/latest/queries/metafield) | Retrieve a single metafield by key |
| [`metafields`](https://shopify.dev/docs/api/shop-users/latest/queries/metafields) | List metafields with pagination and filtering |

| Mutation | Description |
| - | - |
| [`metafieldsSet`](https://shopify.dev/docs/api/shop-users/latest/mutations/metafieldsSet) | Set or update metafield values on the user |
| [`metafieldDelete`](https://shopify.dev/docs/api/shop-users/latest/mutations/metafieldDelete) | Delete a metafield from the user |

Metafield definitions are created and managed through the [Shop Partners API](https://shopify.dev/docs/api/shop-partners/latest).

### Favorites

Add and remove items from the user's default favorites list.

| Mutation | Description |
| - | - |
| [`favoritesAdd`](https://shopify.dev/docs/api/shop-users/latest/mutations/favoritesAdd) | Add a product variant to the user's favorites |
| [`favoritesRemove`](https://shopify.dev/docs/api/shop-users/latest/mutations/favoritesRemove) | Remove a product variant from the user's favorites |

You can also query favorites through the `user` query:

## Query favorites

```graphql
query {
  user {
    favorites(first: 10) {
      nodes {
        shopifyVariantId
        shopifyShopId
        createdAt
      }
    }
  }
}
```

### Product lists

Create and manage named product lists (for example, wishlists) for the authenticated user. Each user has a default favorites list and can create additional lists.

| Query | Description |
| - | - |
| [`user.productList`](https://shopify.dev/docs/api/shop-users/latest/queries/user) | Retrieve a single product list by ID |
| [`user.productLists`](https://shopify.dev/docs/api/shop-users/latest/queries/user) | List all product lists for the user |

| Mutation | Description |
| - | - |
| [`productListCreate`](https://shopify.dev/docs/api/shop-users/latest/mutations/productListCreate) | Create a new product list |
| [`productListUpdate`](https://shopify.dev/docs/api/shop-users/latest/mutations/productListUpdate) | Update a product list's name or privacy status |
| [`productListDelete`](https://shopify.dev/docs/api/shop-users/latest/mutations/productListDelete) | Delete a product list |
| [`productListItemAdd`](https://shopify.dev/docs/api/shop-users/latest/mutations/productListItemAdd) | Add a product variant to a list |
| [`productListItemRemove`](https://shopify.dev/docs/api/shop-users/latest/mutations/productListItemRemove) | Remove a product variant from a list |

Product lists support a `privacyStatus` of `PUBLIC` or `PRIVATE` (default).

## Create a wishlist

```graphql
mutation {
  productListCreate(name: "My Wishlist", privacyStatus: PUBLIC) {
    productList {
      id
      name
      publicId
      privacyStatus
    }
    userErrors {
      field
      message
    }
  }
}
```

***