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:

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:

  1. From your Partner Dashboard, navigate to Settings > Partner API clients, and then click Manage Partner API clients.
  2. Click Create API client.
  3. Enter a name to identify the API client.
  4. Select the appropriate permissions. You can add or remove permissions from a Partner API client as needed.
  5. Click Save, and then click Create API client.
  6. 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 Conversation and Job resources. These resources represent Experts Marketplace conversations and jobs owned 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:

  1. From your Partner Dashboard, navigate to Settings > Partner API clients, and then click Manage Partner API clients.
  2. Click on the Partner API client you want to update.
  3. In the Credentials section, click Generate secondary token.
  4. View or copy the secondary token.
  5. Update the X-Shopify-Access-Token value in your code.
  6. 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:

  1. From your Partner Dashboard, navigate to Settings > Partner API clients.
  2. 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 active Experts Marketplace conversations with unread messages.

curl -X POST "https://partners.shopify.com/{organization-id}/api/2021-07/graphql.json" \
  -H "Content-Type: application/graphql" \
  -H "X-Shopify-Access-Token: < partner-access-token >" \
  -d '
    {
      conversations(
        first: 20,
        unreadOnly: true,
        statuses: [ACTIVE],
      ) {
        edges {
          node {
            id
            lastEventAt
            dashboardUrl
            merchantUser {
              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, conversations, 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.

On this page