shopify_api: the Ruby gem that holds the OAuth dance for your Shopify app

Four things the gem does, and one it deliberately leaves to you

The README lists what the library makes easier, and the list is short enough to be a design statement rather than a feature inventory.

It creates online or offline access tokens for the Admin API via OAuth. It makes requests to the REST API. It makes requests to the GraphQL API. And it registers and processes webhooks. In addition to the Admin API, it also allows querying the Storefront API.

Four capabilities, and the notable thing is what is not in the list. There is no session storage, no routing, no controller layer, no callback handling, no cookie handling. The README states that you can use this library in any application that has a Ruby backend, since it doesn't rely on any specific framework, and that you can include it alongside your preferred stack and use the features that you need.

That is a deliberate boundary, and it has a cost that is worth naming. OAuth for a Shopify app is not only the token exchange. There is the callback route, the state parameter, the session, the cookie, the shop identity, and the per shop credential storage. This gem handles the token mechanics and leaves the rest to you, which is exactly what a framework agnostic library has to do, and exactly why a Rails user should read the next paragraph.

For Rails, the README highly recommends the shopify_app gem to interact with this gem, because authentication, session storage, webhook registration and other frequently implemented paths are managed in that gem with easy to use configurations.

So the recommendation is not that shopify_api is wrong for Rails, it is that a second gem sits on top of it and does the repetitive parts. The two are complements, and reading them in the wrong order is how people end up implementing OAuth twice.

The Context object, which is where your app's identity lives

The entry point is a single setup call, and the shape of it explains how the library is meant to be used.

You start by initializing the ShopifyAPI::Context with the parameters of your app by calling ShopifyAPI::Context.setup when your app starts, for example in application.rb in a Rails app.

ShopifyAPI::Context.setup(
  api_key: "<api-key>",
  api_secret_key: "<api-secret-key>",
  host: "<https://application-host-name.com>",
  scope: "read_orders,read_products,etc",
  is_embedded: true, # Set to true if you are building an embedded app
  api_version: "2022-01", # The version of the API you would like to use
  is_private: false, # Set to true if you have an existing private app
)

Every argument is a decision rather than a detail. The scope string is the set of permissions your app requests, and it should be the least you need. is_embedded tells the library whether your app runs inside the Shopify admin iframe, which changes how the OAuth callback and the session token are handled. is_private distinguishes a public app going through OAuth from an existing private app that already has credentials. And api_version pins the version of the Admin API your calls are made against, which is a contract with Shopify rather than a cosmetic setting, because a versioned API means the shape of a response can change when the version changes.

The host is your application's public URL, which matters because the OAuth redirect is built from it. The README's requirements section says to add the URL and the appropriate redirect for your OAuth callback route to your app settings, so the setup values and the partner dashboard have to agree.

The fact that setup is a global call rather than an argument to each request is the other thing to notice. The Context holds the app's identity, and the per shop credentials live alongside it, which is the design that makes the library usable across shops without passing configuration everywhere.

Installing the gem, and the four steps between the gem and a working call

Installation is two lines, and one of them is enough.

gem "shopify_api"

Or, through bundler.

bundle add shopify_api

After that the README lays out four steps, and they are worth reading as a sequence because each depends on the previous one.

First, set up the Shopify context, as described above. Second, perform OAuth, going through the flow as described in the linked Shopify documentation, to create sessions for shops using your app. The gem provides functions to begin and complete the OAuth process, and the OAuth doc in the docs directory has the instructions.

Third, register webhooks and a webhook handler, following the steps in the Webhooks doc, which covers both registering and handling them. Fourth, start making authenticated requests, once the app can perform OAuth, using the docs for the Admin REST API, the Admin GraphQL API and the Storefront GraphQL API.

The requirement list explains what you need before any of that works. You need a working knowledge of ruby and a web framework such as Rails or Sinatra, a Shopify Partner account and development store, an app already set up in your test store or partner account, and the URL and the appropriate redirect for your OAuth callback route added to your app settings.

That last item is where people get stuck, and it is worth stressing that the gem cannot help with it. A Shopify app that does not have its callback URL registered in the partner dashboard will fail OAuth no matter how correctly ShopifyAPI::Context is set up, and the error you get will not say so.

Versioning, and the separate branch that holds the old instructions

The versioning story is the part of this repository that most affects a decision to adopt it, and it is handled explicitly.

The README says the instructions it gives apply to v10 or later of the package, and that if you are running v9 in your app, the documentation is in that branch. The repository has a default branch of main and the v9 documentation is kept in a separate tree, which is a reasonable pattern for a library that has had several major versions and cannot rewrite history.

The breaking changes are not left to the changelog. There are separate documents in the repository root, BREAKING_CHANGES_FOR_V10.md, BREAKING_CHANGES_FOR_V15.md and BREAKING_CHANGES_FOR_V16.md, plus BREAKING_CHANGES_FOR_OLDER_VERSIONS.md, and the README links each one under a Breaking Change Notices heading. A team upgrading from an old major version has a document to read before it reads anything else, which is more than most gems offer.

The release list in the repository metadata is worth reading carefully, because it is shorter than the versioning story suggests. The most recent listed releases are 9.0.2 from 2020-03-06, 9.0.0 from 2020-01-27 and 4.3.4 from 2017-01-12, while the README describes v10 or later and the repository carries a v16 breaking changes document. The published release tags therefore do not describe the current line of the gem, and the last push to the repository was on 2026-10-15.

The practical reading is that the gem is developed through a scheme that publishes versioned artefacts, and that its version numbers and its release tags are not the same numbering. If you are pinning a version in a Gemfile, check the changelog and the breaking changes documents for that line rather than assuming the tag list tells you what is current.

What the gem does not do, and the alternative that covers it

Three boundaries, and the third is the one to think hardest about.

The first is that it is a client, not a service. It makes HTTP requests to the Admin API and to the Storefront API. It does not model your domain, it does not persist anything, and it does not give you a background job system. If your application needs to sync a thousand products every night, the gem gives you the calls and leaves the scheduling, the pagination and the retry policy to you.

The second is the versioned API. Because you pass an api_version, you are choosing a snapshot of Shopify's behaviour, and when you move to a newer version you are choosing to accept whatever changed in it. The breaking changes documents exist for the gem's own versions, and the API version you set is a separate axis of change that the gem cannot protect you from.

The third is the alternative, and the README names two things. The first is the shopify_app gem for Rails users, which sits on top of this one and handles authentication, session storage and webhook registration. The difference in approach is that shopify_app takes the framework as given, so the config is YAML and the sessions are Rails objects, while this gem gives you Ruby objects and leaves the wiring to you.

The second alternative is a different shape entirely: not using a Ruby gem for the Admin API at all, and instead calling the GraphQL API over plain HTTP from whichever language your backend is written in. GraphQL over HTTP is a well trodden path, and the Shopify API is reachable with any HTTP client. What you lose is the OAuth helper functions, the webhook registration helpers, and the Storefront query helpers, and what you keep is full control and no dependency.

For a Rails shop, the shopify_app gem is the obvious answer and the README says so. For a non Ruby backend, this gem is not the answer at all, and the choice is between a hand rolled GraphQL client and something like the official GraphQL client libraries, which are code generators rather than wrappers.

Editorial conclusion

shopify_api fits a Ruby developer building a Shopify app who wants OAuth, webhook registration and typed API access in one library, and who does not want their application code coupled to a particular web framework. It does not fit a Rails app that would be better served by the shopify_app gem, which the README recommends, and it does not fit a team that wants Shopify calls abstracted away behind its own service, because the gem is deliberately a thin client over the HTTP APIs. Check three things before you commit. Check which major version line you are on, because the README says its instructions apply to v10 or later and that the v9 documentation lives in a separate branch, and the repository carries a separate breaking change notice file for each of v10, v15 and v16 plus one for older versions. Check that the API version you set is one you intend to pin, because the context takes an api_version argument and Shopify's versioned API means that choice becomes part of your contract. And check whether you are using Rails, since the README recommends the shopify_app gem for that case. The last push was on 2026-10-15, the newest listed release tag is 9.0.2 from 2020-03-06, and the license is MIT.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Shopify/shopify-api-ruby on GitHub