---
title: Shop Partners API reference
description: GraphQL API for managing metafield definitions, issuing user tokens, and handling media on the Shop platform.
api_version: unstable latest
source_url:
  html: https://shopify.dev/docs/api/shop-partners/latest
  md: https://shopify.dev/docs/api/shop-partners/latest.md
---

# Shop Partners API

The Shop Partners API is a GraphQL API that you use to manage metafield definitions, issue user access tokens, and handle media for your Shop integration. You authenticate with the client ID and secret from your [Dev Dashboard client](https://shopify.dev/docs/api/shop/guides/creating-a-client).

## Authentication

The Shop Partners API uses HTTP Basic authentication. Include your client ID as the username and client secret as the password with every request. You can find these credentials on your client's settings page in the [Dev Dashboard](https://dev.shopify.com/dashboard). If you don't have a client yet, follow the [creating a client](https://shopify.dev/docs/api/shop/guides/creating-a-client) guide.

## cURL

```bash
curl -X POST \
  https://shop.app/api/partners/graphql.json \
  -H 'Content-Type: application/json' \
  -u '{CLIENT_ID}:{CLIENT_SECRET}' \
  -d '{
    "query": "{ metafieldDefinitions(first: 5) { edges { node { key } } } }"
  }'
```

***

## Endpoints and queries

Send `POST` requests to the Partners API endpoint:

`https://shop.app/api/partners/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

### Metafield definitions

Use metafield definitions to define custom data fields that can be attached to Shop users. You can create, update, and delete definitions, and control access to them across clients.

| Mutation | Description |
| - | - |
| [`metafieldDefinitionCreate`](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionCreate) | Create a new metafield definition |
| [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionUpdate) | Update a definition's key, name, description, or access |
| [`metafieldDefinitionDelete`](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionDelete) | Delete a definition and all associated metafields |

| Query | Description |
| - | - |
| [`metafieldDefinition`](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinition) | Retrieve a single definition by key |
| [`metafieldDefinitions`](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinitions) | List definitions with pagination and filtering |

Metafields with values for these definitions are read and written through the [Shop Users API](https://shopify.dev/docs/api/shop-users/latest).

### Metafield access

Share metafield definitions between clients or namespaces. You need the `share_metafield` scope and admin permission on the resource.

| Mutation | Description |
| - | - |
| [`metafieldAccessGrant`](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldAccessGrant) | Share a metafield definition with another client or namespace |
| [`metafieldAccessRevoke`](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldAccessRevoke) | Revoke shared access to a metafield definition |

### User tokens

Fetch OAuth tokens for the [Shop Users API](https://shopify.dev/docs/api/shop-users/latest) on behalf of a user. These mutations return an access token (used to call the Users API) and a refresh token (used to get new access tokens when the current one expires).

| Mutation | Description |
| - | - |
| [`fetchTokensForUser`](https://shopify.dev/docs/api/shop-partners/latest/mutations/fetchTokensForUser) | Get an access token and refresh token for a user by their public ID or consent token |

The `fetchTokensForUser` mutation returns an `accessToken` that you use as a Bearer token when calling the [Shop Users API](https://shopify.dev/docs/api/shop-users/latest). The token expires after a set time (returned in seconds in the `expiresIn` field). Use the `refreshToken` to get a new access token when the current one expires.

If you have the user's public ID, pass it directly:

## Fetch tokens by public ID

```graphql
mutation {
  fetchTokensForUser(publicId: "user_public_id") {
    accessToken
    refreshToken
    expiresIn
    tokenType
    scope
  }
}
```

Alternatively, if you have a single-use consent token, pass it instead:

## Fetch tokens by consent token

```graphql
mutation {
  fetchTokensForUser(consentToken: "your_consent_token") {
    accessToken
    refreshToken
    expiresIn
    tokenType
    scope
    publicId
  }
}
```

Consent tokens are single-use. The mutation returns the user's `publicId`, which you can use for subsequent token fetches.

### Media

Create, update, and delete shop videos with related products.

| Mutation | Description |
| - | - |
| [`mediaCreate`](https://shopify.dev/docs/api/shop-partners/latest/mutations/mediaCreate) | Create a new shop video with related products |
| [`mediaUpdate`](https://shopify.dev/docs/api/shop-partners/latest/mutations/mediaUpdate) | Update an existing shop video |
| [`mediaDelete`](https://shopify.dev/docs/api/shop-partners/latest/mutations/mediaDelete) | Delete a shop video |

| Query | Description |
| - | - |
| [`media`](https://shopify.dev/docs/api/shop-partners/latest/queries/media) | Retrieve active shop videos for a product or variant |

***