Leveraging the Partner API: Useful Business Tools You Can Build

What attracted me, and a lot of Shopify Partners, to build on Shopify is that it is easy to extend. Whatever we can do through the merchant admin, we can do through theAdmin API.

We build apps to help merchants get things done, enhancing core Shopify features. With data from the API, we can give merchants insights and tools to grow their businesses.

Until recently, though, our Partner Dashboard was closed off from our tinkering. Many other developers and I came up with scrappy solutions to build the tools and get the data we need to grow our businesses. We had to work with the manual CSV exports or do hacky scraping of the dashboard.

Shopify has launched aPartner API,让我们更近了一步做公关的一切ogrammatically that we can do through the Partner Dashboard.

We’re super excited for Partner API and where it’s headed!

With this Partner API, we’re now able to replace our scrappy import scripts with some proper GraphQL. It also opens up opportunities for other products to integrate with our apps, themes, and jobs data.

First, I’ll walk you through how to get up and running with the Partner API using Ruby. Then we’ll see what others are saying about how they’ll use the API and what they're building.

How to work with the Partner API in Ruby

The Partner API usesGraphQL, which requires more work from the client than aREST API. In exchange, we get a richer way to query and return just the data that we need. What would be multiple REST queries can be a single GraphQL request.

There aren’t any client libraries for the Partner API like we have for the Admin API. I’ll walk you through how to work with the Partner API in Ruby.

We’ll start by addingthe GraphQL gem, a gem that internal Shopify teams use.

# Gemfile
gem 'graphql'
$ bundle install

Then:

$ rails generate graphql:install

Since we’re not running a GraphQL server, we can delete theapp/graphqldirectory and remove this route fromconfig/routes.rb.

post "/graphql" to: "graphql#execute"

通过你爸Shopify提供GraphiQL探险家rtner Dashboard, so you can also remove the one provided by the gem if you like. Delete this from yourroutes.rb:

if Rails.env.development?
mount GraphiQL::Rails::Engine, at: "/graphiql", graphql_path: "/graphql"
end

Now let’s start building!

OurGraphQL::Clientneeds an HTTP network adapter to make requests. We’ll create ourHTTPClientclass for the Partner API specific parts.

All API requests go to a single URL. The path contains our organization ID: a unique identifier for our partner account, and the API version we want to query.

For example:

“https://partners.shopify.com/#{organization_id}/api/#{api_version}/graphql.json”

Authenticationis with a custom HTTP header X-Shopify-Access-Token containing the access token we’ve created in our Partner Dashboard.

Putting this together, we have an HTTP Client like this:

Core to GraphQL is that every API has a typed schema. Our client uses this schema to make requests to the API. Since the schema can get large and does not vary between requests, we’ll save it to disk once and cache it in memory at runtime.

Here’s the code:

Once you’ve fetchedpartner-api-schema.json, you can, of course, remove theGraphQL::Client.dump_schemacheck altogether.

Now we’re ready to fetch the data we want from the Partner API. Take a look atthe Partner API referenceto see what’s available. Data-modifying operations are called mutations in GraphQL. The API is currently query-only; there are no mutations.

We’ll use querying all of our monthly and annual recurring app charges in this example.

You might also like:Getting Started with GraphQL.

Writing our query

We’ll start by going to theGraphiQL explorer. Here we can browse the schema in the Documentation Explorer and craft our query. Here’s how to fire it up:

1. From your Shopify Partner Dashboard, clickSettings

2. At the bottom of theSettingspage, clickManage Partner API clients

3. PushView GraphiQL Explorernext to the token you wish to use.

In theQueryRoot, we findtransactions. Insidetransactions, we can query for aTransactionTypeofAppSubscriptionSale.

For our example, we want to know when a transaction was created, how much has been paid out to us, for which app, and for which store. With GraphQL, we can selectively pull just those fields.

Run this query in your GraphiQL explorer to see the results.

GraphQL is typed. We’ve queried for theAppSubscriptionSaletransaction type and requested data from its fields. Other transaction types share some fields and add their own fields too.

We cannot simply leave off the type since not all fields are available on all types. Run this query, and you’ll get an error.

We use inline fragments to query the fields we want on the types we want.

Let’s add theServiceSaletype to our query. It doesn’t have an app field. We’ll omit that from its inline fragment.

GraphQL paginates using a cursor. The query results contain a cursor string and ahasNextPageboolean. If there’s another page, we pass the cursor string on the next query, and the next page is returned. We can request up to 100 results at a time.

We’ll add these pagination fields to our query.

Now the query is ready, let’s complete our Ruby code.

Putting it all together

Our query is parsed and validated against the Partner API schema at runtime. The GraphQL gem requires the parsed query to be a constant so that we don’t inefficiently parse and validate the query every time it’s executed.

The API is rate limited to four requests per second per API client. We’ll write a simple throttler to make at most one call every 0.3 seconds.

Here’s the complete code for a Rails class to query the Partner API, paging through results.

And there you have it—how to work with the Partner API in Ruby. Now, when it comes to how this will impact partners, I’ve been hearing conversations in the partner communities on social media discussing the opportunities and the unknowns.

What’s the big deal with the Partner API?

A few partners on Twitter and Facebook have asked, What’s the big deal with the Partner API?” There are two opportunities with the Partner API:

1. Internal tools
2. Buy, don’t build

Partners have all kinds of interesting internal scripts and tools using CSVs and scraped data. They break when the CSV format changes or the Partner Dashboard is changed. A documented and supported Partner API makes these robust and much easier to build.

Then, it opens the possibility of buying tools instead of building our own. It can be fun to hack around on APIs and build admin scripts and dashboards. Sometimes though, I just want to pay for a useful tool and get back to investing time in my products.

We’ll see a crop of Shopify Partner tools start to grow because we can now give other products secure access to our data with scopes and revocable tokens.

There’s been a bit of chatter about what these internal and partner tools could be.

SaaS metrics

To grow our partner businesses, we need to be on top of our SaaS metrics to know where to focus our efforts. Getting accurate and timely numbers for monthly recurring revenue (MRR), churn, lifetime customer value (LTV), and average revenue per user (ARPU) has not been easy.

SaaS metrics products can now plug directly into the Partner API. Baremetrics is working on support. A free tool I contribute to,Partner Metrics, now supports the Partner API.

Forecasting lets us model how our businesses will go in the future, helping us plan. Partners arealready askingfor tools likeSummitto add support.

You might also like:8 Growth Metrics Every App Developer Should Track.

Marketing attribution

It hasn’t been easy to calculate how effective a marketing campaign is. Attributing specific merchants to a campaign, how much revenue they generate for us, and how much the campaign cost has been murky. Partners are looking formore visibility of return on marketing spend.

...Can’t wait to see what tools get made. My dream is some toolset that helps devs run effective paid user acquisition for their new app.

You might also like:How to Market an App: 11 Expert Tips.

Cash for partners

Shopify Capitalgives merchants quick and easy access to cash. With the transparency the Partner API brings, will we see similar non-dilutive financing for Shopify App Developers?

Prediction: With the launch of Shopify’s Partner API, app developers will soon have easier access to cash.

And just five days later, Shopify Partner Eyal Toledano, Creator atBatch Commerce, responded that his team started building a “no nonsense CRM” calledPartner CRMthat connects into their app dashboard and will help them manage their merchant/client lifecycle.

Partner programs

App developers often partner upwith their referral programs, offering a percentage of a merchant’s monthly spend for a referral. Until recently, that’s been hard to calculate accurately. With the Partner API, we can work out exactly how much a merchant has paid us and how much to pay for the referral.

Support and CRM

Partners use customer relationship management (CRM) software and helpdesk tools likeHubSpot,Zendesk, andGorgiasto support merchants. When a ticket comes in, we can more effectively help merchants if we have a view of the apps they have installed, their history with our products, and billing information. CRM and helpdesk tools can query the Partner API directly to pull this detailed view of a merchant.

Building together with the Partner API

As you can tell, I’m excited about building on our partner platform, just like we’ve been able to develop on the merchant platform. We can now get deeper insights into our businesses to grow faster. Partners can build tools for partners.

"We can now get deeper insights into our businesses to grow faster."

The Shopify Partner community is remarkable in how we work together, and the Partner API gives us a way to strengthen our relationships even more.