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.

Choose a version:

Anchor to AuthenticationAuthentication

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. If you don't have a client yet, follow the creating a client guide.

cURL

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 } } } }"

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

Anchor to Key operationsKey operations

Anchor to Metafield definitionsMetafield 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`	Create a new metafield definition
`metafieldDefinitionUpdate`	Update a definition's key, name, description, or access
`metafieldDefinitionDelete`	Delete a definition and all associated metafields

Query	Description
`metafieldDefinition`	Retrieve a single definition by key
`metafieldDefinitions`	List definitions with pagination and filtering

Metafields with values for these definitions are read and written through the Shop Users API.

Anchor to Metafield accessMetafield access

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

Mutation	Description
`metafieldAccessGrant`	Share a metafield definition with another client or namespace
`metafieldAccessRevoke`	Revoke shared access to a metafield definition

Anchor to User tokensUser tokens

Fetch OAuth tokens for the Shop Users API 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`	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. 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

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

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.

Anchor to MediaMedia

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

Mutation	Description
`mediaCreate`	Create a new shop video with related products
`mediaUpdate`	Update an existing shop video
`mediaDelete`	Delete a shop video

Query	Description
`media`	Retrieve active shop videos for a product or variant

Was this page helpful?