shopify_api

ShopifyAPI is a lightweight gem for accessing the Shopify admin REST and GraphQL web services.

849

367

Ruby

Shopify API Library for Ruby

This library provides support for Ruby Shopify apps to access the Shopify Admin API, by making it easier to perform the following actions:

Creating online or offline access tokens for the Admin API via OAuth
Making requests to the REST API
Making requests to the GraphQL API
Registering/processing webhooks

In addition to the Admin API, this library also allows querying the Storefront API.

You can use this library in any application that has a Ruby backend, since it doesn’t rely on any specific framework — you can include it alongside your preferred stack and use the features that you need to build your app.

Note: These instructions apply to v10 or later of this package. If you’re running v9 in your app, you can find the documentation in this branch.

Use with Rails

If using in the Rails framework, we highly recommend you use the shopify_app gem to interact with this gem. Authentication, session storage, webhook registration, and other frequently implemented paths are managed in that gem with easy to use configurations.

Requirements

To follow these usage guides, you will need to:

have a working knowledge of ruby and a web framework such as Rails or Sinatra
have a Shopify Partner account and development store
have an app already set up in your test store or partner account
add the URL and the appropriate redirect for your OAuth callback route to your app settings

Installation

Add the following to your Gemfile:

gem "shopify_api"

or use bundler:

bundle add shopify_api

Steps to use the Gem

Setup Shopify Context

Start by initializing the ShopifyAPI::Context with the parameters of your app by calling ShopifyAPI::Context.setup (example below) when your app starts (e.g 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
)

Performing OAuth

You need to go through OAuth as described here to create sessions for shops using your app.
The Shopify API gem tries to make this easy by providing functions to begin and complete the OAuth process. See the Oauth doc for instructions on how to use these.

Register Webhooks and a Webhook Handler

If you intend to use webhooks in your application follow the steps in the Webhooks doc for instructions on registering and handling webhooks.

Start Making Authenticated Shopify API Requests

Once your app can perform OAuth, it can now make authenticated Shopify API calls, see docs for:

Making Admin REST API requests
Making Admin GraphQL API requests
Making Storefront GraphQL API requests

Breaking Change Notices

Developing this gem

After cloning the repository, you can install the dependencies with bundler:

bundle install

To run the automated tests:

bundle exec rake test

We use rubocop to lint/format the code. You can run it with the following command:

bundle exec rubocop