Skip to main content

GraphQL Partner API

The Partner API provides access to your Partner organization's data. Data includes transactions that impact your earnings and app events. With this information, you can effectively scale your business by automating front and back-office operations, freeing up time to focus on solutions for Shopify merchants.

Anchor to AuthenticationAuthentication

There are two pieces of information that you must include to successfully authenticate requests to a Partner API endpoint:

  • Your Partner ID, which is the number in your Partner Dashboard URL. For example: https://partners.shopify.com/{partner_id}/api/unstable/graphql.json. The number in your Dev Dashboard URL is your organization ID, so don't use it here.
  • A Partner API client access token. You get one when you create a Partner API client, and it must belong to the organization that you're querying. For example: X-Shopify-Access-Token: <partner-access-token>

Unlike the GraphQL Admin API, which issues tokens scoped to a specific store, Partner API tokens are scoped to your Partner organization and authorize access to data across all stores within it. For how this compares to authentication across other Shopify APIs, see Shopify API authentication.

cURL

curl -X POST \
https://partners.shopify.com/{partner_id}/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {partner_access_token}' \
-d '{
"query": "{your_query}"
}'

Anchor to Endpoints and queriesEndpoints and queries

Use the GraphiQL Explorer in the Dev Dashboard to query the Partner API. The GraphiQL Explorer uses your Partner API client to retrieve the requested information from your Partner account.

  1. In the Dev Dashboard, click Organization settings, click Users, and then click Security.
  2. In the Partner API clients section, select the client that you want to explore.
  3. Click View GraphiQL Explorer. The Explorer opens in a new tab.

You can also use the GraphiQL Explorer to work with the schema and build queries.

Queries begin with one of the objects listed under QueryRoot. The QueryRoot is the schema’s entry-point for queries. Queries are equivalent to making a GET request in REST.

To make a query, send a POST request to:

https://partners.shopify.com/{partner_id}/api/unstable/graphql.json

You can use cURL or an HTTP client such as Postman or Insomnia to query the Partner API. This example is a basic request using cURL. Replace {partner_id} with your Partner ID, and replace {partner-access-token} with your client access token. This request retrieves your 20 most recent app subscription sales, with the app, the store, and your net earnings for each. The client needs the View financials permission.

Anchor to VersioningVersioning

The Partner API is versioned. To keep your app stable, make sure that you specify a supported version in the URL.

Anchor to Create a Partner API clientCreate a Partner API client

Each API client has access only to the data belonging to the organization in which it is created. You need to create an API client for each organization that you want to access using the API.

Before you add a client, make sure that you have the following:

  • The App development organization permission
  • The Manage financials partner permission
  • A confirmed business email for your organization, on the Organization page in Contact details
  • Room under your organization's client limit

To rename a client, change its permissions, rotate or revoke its token, or delete it, you need the App development organization permission and the View financials partner permission.

You choose a client's permissions when you add it. The following permissions can be granted for each API client:

  • View financials: This permission is required to access Transaction resources and to cancel Shopify App Pricing subscriptions. Transaction resources represent all of the transactions that impact your Partner earnings.
  • Manage apps: This permission is required to access App resources, including all app-related events such as installs, uninstalls, and charges. This resource represents all of the public and private apps managed by your organization.
  • Manage themes: This permission is required to access the Theme resource. This resource represents all of the Shopify themes managed by your organization.
  1. In the Dev Dashboard, click Organization settings, click Users, and then click Security.
  2. In the Partner API clients section, click Add Partner API client.
  3. Enter a Name for the client, select the permissions that it needs, and then click Add client.
  4. On the client's page, copy the access token. You can't view it again after you leave the page.

To query the shopEmail field on ThemeSale transactions, the API client needs both the View financials and Manage themes permissions.

Anchor to Secure your data by rotating your access tokenSecure your data by rotating your access token

Your Partner API access token secures your organization's data. It should be kept secret at all times. If you need to replace your access token, then you can rotate it. A new token is generated while the current one keeps working, so you can move your integrations to the new token before you revoke the old one.

  1. In the Dev Dashboard, click Organization settings, click Users, and then click Security.
  2. In the Partner API clients section, select the client whose token you want to replace.
  3. Click Rotate, and then click Generate new token.
  4. Click Copy access token. You can't view the new token again after you leave the page.
  5. Move your integrations to the new token. Click Revoke old token, and then click Revoke old token in the confirmation dialog.

Anchor to Usage limitationsUsage limitations

  • Transaction information is for analytics purposes only. This information shouldn't be used for accounting or financial reporting.
  • All apps and services connecting to the Partner API are subject to Shopify’s API Terms of Service.
  • Merchant data that the Partner API returns, such as the store owner email on ThemeSale transactions, is subject to the Partner Program Agreement. Don't use it for unsolicited marketing.
POST

https://partners.shopify.com/{partner_id}/api/unstable/graphql.json

# Get your 20 most recent app subscription sales
curl -X POST "https://partners.shopify.com/{partner_id}/api/unstable/graphql.json" \
-H "Content-Type: application/json" \
-H "X-Shopify-Access-Token: {partner-access-token}" \
-d '{"query": "{ transactions(first: 20, types: [APP_SUBSCRIPTION_SALE]) { edges { node { id createdAt ... on AppSubscriptionSale { app { name } shop { myshopifyDomain } netAmount { amount currencyCode } } } } } }"}'

Anchor to Rate limitsRate limits

The Partner API has a rate limit of four requests per second per Partner API client. After the limit is exceeded, all requests are throttled and return an {"errors": [{"message": "Too many requests"}]} error.

{}

Request

HTTP/1.1 429 Too Many Requests
{}

Response

HTTP/1.1 429 Too Many Requests
{
"errors": [{
"message": "Too many requests",
"extensions": {
"code": "429"
}
}]
}

Anchor to Status and error codesStatus and error codes

All API queries return HTTP status codes that contain more information about the response.

Anchor to 200 OK200 OK

The GraphQL Partner API can return a 200 OK response code in cases that would typically produce 4xx errors in REST.

200 response codes can return different formats including both strings and objects.

Anchor to Error handlingError handling

The response for the errors object contains additional detail to help you debug your operation.

The response for mutations contains additional detail to help debug your query. To access this, you must request userErrors.

Properties

errors•array

A list of all errors returned

Show error item properties
errors[n].message•string

Contains details about the error(s).

errors[n].extensions•object

Provides more information about the error(s) including properties and metadata.

Show extensions properties
extensions.code•string

Shows error codes common to Shopify. Additional error codes may also be shown.

Show common error codes
400

Bad Request: The server will not process the request.

401

Unauthorized: A call was made with an invalid API client (for example, using tokens that don't exist) or against an invalid Organization (for example, one that is disabled).

404

Not found: The resource isn’t available. This occurs when querying for something that has been deleted.

429

Too Many Requests: The client has exceeded the rate limit.

500

Internal Server Error: An internal error occurred in Shopify. Check out the Shopify status page for more information.

{}

Sample 200 error responses

{
"errors": [
{
"message": "Too many requests",
"extensions": {
"code": "429"
}
}
]
}
{
"errors": [
{
"message": "Internal error. Looks like something went wrong on our end.
Request ID: 1b355a21-7117-44c5-8d8b-8948082f40a8 (include this in support requests).",
"extensions": {
"code": "500"
}
}
]
}

Anchor to 4xx and 5xx status codes4xx and 5xx status codes

The 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopify’s services.

Many errors that would typically return a 4xx or 5xx status code, return an HTTP 200 errors response instead. Refer to the 200 OK section above for details.

Anchor to [object Object]400 Bad Request

The server will not process the request.

Anchor to [object Object]401 Unauthorized

A call was made with an invalid API client (for example, using tokens that don't exist) or against an invalid Organization (for example, one that's been disabled).

Anchor to [object Object]404 Not Found

The resource isn’t available. This is often caused by querying for something that’s been deleted.

Anchor to [object Object]429 Too Many Requests

Too many requests were sent in a given time period.

Info

Didn’t find the status code you’re looking for? View the complete list of API status response and error codes.

{}

Sample error codes

HTTP/1.1 400 Bad Request
{
"errors": [{
"message": "Maximum query length is 50000 characters",
"extensions": {
"code": "400"
}
}]
}
HTTP/1.1 401 Unauthorized
{
"errors": [{
"message": "Invalid access token",
"extensions": {
"code": "401"
}
}]
}
HTTP/1.1 404 Not Found
{
"errors": [{
"message": "Invalid API version",
"extensions": {
"code": "404"
}
}]
}
HTTP/1.1 429 Too Many Requests
{
"errors": [{
"message": "Too many requests",
"extensions": {
"code": "429"
}
}]
}

Anchor to Shopify App PricingShopify App Pricing

The Partner API includes queries and mutations that support Shopify App Pricing, the managed pricing system for public apps.

  • Active Subscription: Retrieve the current managed pricing subscription for a specific shop, including plan, billing period, billing cycle, subscription items (with pricing and usage), discounts, and pending updates. Requires the Manage apps permission.
  • App Subscription Cancel: Cancel the active Shopify App Pricing subscription for a specific shop and app. Requires the View financials permission.
  • Historical Events: Retrieve a paginated timeline of installs, uninstalls, charges, earnings, subscription changes, and credits across your apps and themes. Supports filtering by shop, subject, event type, and date range. Requires the Manage apps permission.

Anchor to TranslationsTranslations

To receive translated error messages when using the Partner API, you need to specify a locale in the Accept-Language HTTP request header when sending queries. This example shows a header that enables error messages to be returned in Spanish when using the Partner API.

If the locale is missing or unsupported, then the API returns error messages in English.

{}

Sample request header for locale

Accept-Language: es
Was this page helpful?