GraphQL Partner API

Anchor to AuthenticationAuthentication

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

• Your organization ID. You can find this in the URL of the Partners Dashboard when you're logged in. For example: https://partners.shopify.com/organization-id/api/2024-10/graphql.json
• A Partner API client access token. The API client access token must belong to the organization that you're querying. You can create a new API client for your organization through the Partner Dashboard. For example: X-Shopify-Access-Token: <partner-access-token>

Anchor to Endpoints and queriesEndpoints and queries

Use GraphiQL explorer through your Partners Dashboard to query the Partner API. The GraphiQL explorer uses your Partner API client to retrieve the requested information from your Partner account.

From your Partners Dashboard, navigate to Settings > Partner API clients. Next to the Partner API client that you want to explore, click View GraphiQL explorer.

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/{org_id}/api/2024-10/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 {organization-id} with the ID for the organization you are querying, and replace {partner-access-token} with your client access token. This request retrieves the last 20 active Experts Marketplace conversations with unread messages.

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

Anchor to Create a Partner API clientCreate a Partner API client

You must be an organization owner to create and manage your API client through the Partners Dashboard. 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. From the Partners Dashboard, navigate to Settings > Partner API clients, and then click Manage Partner API clients.

The following permissions can be granted for each API client:

• View financials: This permission is required to access Transaction resources. These 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.
• Manage jobs: This permission is required to access Conversation and Job resources. These resources represent Experts Marketplace conversations and jobs owned by your organization.

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

Your access token secures your organization's data. It should be kept secret at all times. If you need to replace your access token, you can generate a secondary token from your Partners Dashboard, Navigate to Settings > Partner API clients, and then click Manage Partner API clients.

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. Only organization owners can create and manage Partner API clients.

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.

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.

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.

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.