Getting started with the Shopify Partner API
The Shopify Partner API enables you to programmatically access the data from your Partner Dashboard. This guide shows you how to get set up and start making requests to the Partner API.
Partner API authentication
There are two pieces of information that you must include to successfully authenticate requests to a Partner API endpoint:
- Your organization ID
- A Partner API client access token
Organization ID
The organization ID must be included in the endpoint URL that you're querying. For example:
https://partners.shopify.com/<organization-id>/api/2021-04/graphql.json
You can find your organization ID in the URL of the Partner Dashboard when you're logged in. For example, from the Payouts page, if the URL is https://partners.shopify.com/1234/payments
, then your organization ID is 1234
.
Access token
You need to include an API client access token in an X-Shopify-Access-Token
request header. For example:
X-Shopify-Access-Token: <partner-access-token>
The API client access token must belong to the organization that you are querying. You can create a new API client for your organization through the Partner Dashboard.
Your access token secures your organization's data and should be kept secret at all times. If you need to replace your access token, you can generate a secondary token that you can rotate in to avoid downtime.
Create an API client
You can create a new API client through the Partner Dashboard. Each API client can access only the data belonging to the organization in which it is created.
If you have multiple Partner organizations, then you need to create an API client through the Partner Dashboard of each organization that you want to access using the API.
Only organization owners can create and manage API clients.
Steps:
- From your Partner Dashboard, navigate to Settings > Partner API clients, and then click Manage Partner API clients.
- Click Create API client.
- Enter a name to identify the API client.
- Select the appropriate permissions. You can add or remove permissions from a Partner API client as needed.
- Click Save, and then click Create API client.
- In the Credentials section, next to the Access token field, click Show to show the access token, or click Copy to copy the access token to your clipboard.
Permissions
You should grant only the permissions that your API client needs to work. For example, if you want to develop some code to pull app events, then you should grant only the Manage apps permission.
In some cases, you might need to grant multiple permissions to retrieve the data you need. For example, you need to grant the View financials permission to access Transaction
resources. If a transaction is generated by an app, then you also need the Manage apps permission to view the app's details.
You can add or remove permissions from a Partner API client as needed.
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 Job
resources, including all of the messages that have been exchanged within each job. This resource represents all of the Experts Marketplace jobs received by your organization.
Rotate the access token
If you want to change the token for security reasons, then you can create a secondary access token for your API client. After you’ve updated your code to use the secondary access token, you can delete the original access token. When the original access token is deleted, the secondary access token becomes your primary and only valid access token.
Steps:
- From your Partner Dashboard, navigate to Settings > Partner API clients, and then click Manage Partner API clients.
- Click on the Partner API client you want to update.
- In the Credentials section, click Generate secondary token.
- View or copy the secondary token.
- Update the
X-Shopify-Access-Token
value in your code. - Beside Access token, click Delete.
Access the Partner API GraphQL endpoint
You can access the Partner API GraphQL endpoint using Graphiql, cURL, or any HTTP client.
Using GraphiQL
You can access a GraphiQL explorer through your Partner Dashboard. The GraphiQL explorer uses your Partner API client to retrieve the requested information from your Partner account. You can also use the GraphiQL explorer to explore the schema and build queries.
Steps:
- From your Partner Dashboard, navigate to Settings > Partner API clients.
- Next to the Partner API client that you want to explore, click View GraphiQL explorer.
The following example is a basic request using the GraphiQL explorer. This request retrieves the transaction records for the month of October, 2020.
{
transactions (
createdAtMin: "2020-10-01T00:00:00Z",
createdAtMax: "2020-10-31T23:59:59Z"
) {
edges {
node {
id
createdAt
}
}
}
}
Using cURL
Your can use cURL or an HTTP client such as Postman or Insomnia to query the Partner API.
The following 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 Experts Marketplace jobs submitted to the organization.
curl -X POST "https://partners.shopify.com/{organization-id}/api/2021-04/graphql.json" \
-H "Content-Type: application/graphql" \
-H "X-Shopify-Access-Token: < partner-access-token >" \
-d '
{
jobs (last:20) {
edges {
node {
id
shop {
id
}
createdAt
lastEventAt
services {
name
}
}
}
}
}
'
IDs in the Partner API
IDs in the Partner API use the format gid://<platform-name>/<resource-name>/<ID>
.
<platform-name>
represents the platform that created the object. Valid values include:partners
: Objects created in or for the Partner context, such as apps, transactions, and jobs.shopify
: Objects created in or for the merchant context, such as app events, charges, and credits.
<resource-name>
represents the object type. Refer to the Partner API reference for a list of valid objects.<ID>
represents a contextually unique numeric identifier for the object.
For example, an app might have the ID gid://partners/App/5678
. In this example, partners
is the platform that created the object, App
is the object type, and 5678
is the contextually unique identifier for the object.
Example queries
Below are some example queries to the Partner API.
Transactions
This query retrieves all transactions related to services for a particular shop in the year 2020.
fragment serviceSale on ServiceSale {
netAmount {
amount
}
shop {
name
}
}
fragment serviceSaleAdjustment on ServiceSaleAdjustment {
netAmount {
amount
}
shop {
name
}
}
{
transactions(
first: 10,
shopId: "gid://partners/Shop/1234",
types: [SERVICE_SALE SERVICE_SALE_ADJUSTMENT],
createdAtMin: "2020-01-01T00:00:00Z",
createdAtMax: "2020-12-31T23:59:59Z"
) {
edges {
node {
id
createdAt
__typename
...serviceSale
...serviceSaleAdjustment
}
}
}
}
App install/uninstall events
This query retrieves all install and uninstall events for an app in the first quarter of 2020.
To retrieve the events for an app, you need to provide the app ID. You can find the app ID in the URL of the Partner Dashboard when you are viewing an app. For example, from the app dashboard, if the URL is https://partners.shopify.com/1234/apps/5678
, then the app ID is 5678
.
You need to enter the app ID using the format gid://partners/App/<app-id>
. For this example, the full app ID is gid://partners/App/5678
. Learn more about IDs in the Partner API.
{
app(id: "gid://partners/App/5678") {
id
name
events(
first: 10,
types: [RELATIONSHIP_INSTALLED RELATIONSHIP_UNINSTALLED],
occurredAtMin: "2020-01-01T00:00:00Z",
occurredAtMax: "2020-03-31T23:59:59Z"
) {
edges {
node {
type
occurredAt
shop {
id
}
... on RelationshipUninstalled {
reason
description
}
}
}
}
}
}
Translation header
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. The following example header enables error messages to be returned in Spanish when using the Partner API:
Accept-Language: es
If the locale is missing or unsupported, then the API returns error messages in English.
Rate 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.