Skip to main content

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.

Anchor to AuthenticationAuthentication

The Shop Users API uses Bearer token authentication. You get user access tokens by calling the fetchTokensForUser mutation on the Shop Partners API.

  1. Authenticate with the Partners API using your client credentials.
  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

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.

Anchor to Endpoints and queriesEndpoints 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.

Anchor to Key operationsKey operations

Anchor to MetafieldsMetafields

Read and write custom data on the authenticated user's profile. Metafield definitions are created through the Shop Partners API, and you can read or write values for those definitions through the Users API.

QueryDescription
metafieldRetrieve a single metafield by key
metafieldsList metafields with pagination and filtering
MutationDescription
metafieldsSetSet or update metafield values on the user
metafieldDeleteDelete a metafield from the user

Metafield definitions are created and managed through the Shop Partners API.

Anchor to FavoritesFavorites

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

MutationDescription
favoritesAddAdd a product variant to the user's favorites
favoritesRemoveRemove a product variant from the user's favorites

You can also query favorites through the user query:

Query favorites

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

Anchor to Product listsProduct 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.

QueryDescription
user.productListRetrieve a single product list by ID
user.productListsList all product lists for the user
MutationDescription
productListCreateCreate a new product list
productListUpdateUpdate a product list's name or privacy status
productListDeleteDelete a product list
productListItemAddAdd a product variant to a list
productListItemRemoveRemove a product variant from a list

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

Create a wishlist

mutation {
productListCreate(name: "My Wishlist", privacyStatus: PUBLIC) {
productList {
id
name
publicId
privacyStatus
}
userErrors {
field
message
}
}
}
Was this page helpful?