shopify_api 9.5.1 → 10.0.0

data/RELEASING

@@ -14,4 +14,4 @@ Releasing ShopifyAPI
 9. Publish the gem using Shipit
 10. Consider if the dependency in Shopify/shopify needs updated. It's used only by the tests so is a low risk change.
 Also consider Shopify/shopify_app whose gemspec depends on this.
-We don't need to do this for every release, but we should try to keep them relatively up to date.
+We don't need to do this for every release, but we should try to keep them relatively up to date.

data/Rakefile

@@ -1,55 +1,23 @@
+# typed: false
 # frozen_string_literal: true
-require 'rake'
-require "bundler/gem_tasks"
-require 'rake/testtask'
-require 'rubocop/rake_task'
-
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.warning = false
-end
 
-RuboCop::RakeTask.new
+require "rake/testtask"
+require "bundler/gem_tasks"
 
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task(:rcov) do
-    abort("RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov")
+namespace :test do
+  Rake::TestTask.new(:library) do |t|
+    t.test_files = FileList["test/**/*_test.rb"].exclude("test/rest/**/*.rb")
   end
-end
 
-task(default: [:test, :rubocop, :verify_docs])
+  Rake::TestTask.new(:rest_wrappers) do |t|
+    pattern = if ENV.key?("API_VERSION")
+      "test/rest/**/#{ENV["API_VERSION"]}/*.rb"
+    else
+      "test/rest/**/*.rb"
+    end
 
-require 'verify_docs'
-task(:verify_docs) do
-  unless VerifyDocs.call
-    abort("\nWARNING: docs/index.md and README.md no longer have identical content. Please correct this.")
+    t.pattern = pattern
   end
 end
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "shopify_api #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-task(:docker) do
-  cmd = "docker-compose up -d && docker exec -i -t shopify_api bash"
-  exec(cmd, err: File::NULL)
-end
+task test: ["test:library"]

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 ### New features
 
-New features will only be added to the master branch and will not be made available in point releases.
+New features will only be added to the main branch and will not be made available in point releases.
 
 ### Bug fixes
 
@@ -56,4 +56,4 @@ We look forward to working with all security researchers and strive to be respec
 
 ## Receiving Security Updates
 
-To recieve all general updates to vulnerabilities, please subscribe to our hackerone [Hacktivity](https://hackerone.com/shopify/hacktivity)
+To recieve all general updates to vulnerabilities, please subscribe to our hackerone [Hacktivity](https://hackerone.com/shopify/hacktivity)

data/bin/tapioca

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/dev.yml

@@ -3,9 +3,30 @@ name: shopify-api
 type: ruby
 
 up:
-  - ruby: "3.0"
+  - ruby: 3.0.3
   - bundler
 
 commands:
+  console:
+    desc: 'start a ruby shell with ShopifyAPI already loaded'
+    aliases: ['c']
+    run: bundle exec irb -Ilib -rshopify_api
+  style:
+    desc: 'run rubocop'
+    run: bundle exec rubocop
+  typecheck:
+    desc: 'run Sorbet typechecking'
+    aliases: ['tc']
+    run: bundle exec srb tc
   test:
     run: bundle exec rake test
+  sanity:
+    desc: 'run all static checks against the codebase'
+    run: bundle exec rubocop && bundle exec srb tc && bundle exec rake test
+    subcommands:
+      all:
+        desc: 'run all checks regardless of the success states of previous checks'
+        run: bundle exec rubocop; bundle exec srb tc; bundle exec rake test
+  rbi:
+    desc: 'generate .rbi files for specified gem to the project'
+    run: bin/tapioca gem

data/docs/README.md

@@ -0,0 +1,13 @@
+<!-- Make sure this file is in sync with the Getting started section in README -->
+
+# Getting started
+
+You can follow our getting started guide to learn how to use this library.
+
+- [Getting started](getting_started.md)
+- [Performing OAuth](usage/oauth.md)
+- [REST Admin API](usage/rest.md)
+- [Make a GraphQL API call](usage/graphql.md)
+- [Make a Storefront API call](usage/graphql_storefront.md)
+- [Webhooks](usage/webhooks.md)
+- [Known issues and caveats](issues.md)

data/docs/getting_started.md

@@ -0,0 +1,53 @@
+# Getting started
+
+This page will outline everything you need to know and the steps you need to follow in order to start using the Shopify Ruby API gem in your app.
+
+## Requirements
+
+- A working knowledge of ruby and a web framework such as Rails or Sinatra
+- A private or custom app already set up in your test store or partner account
+- We recommend `ngrok` to tunnel traffic to your localhost for testing
+
+## Installation
+
+Add the following to your Gemfile:
+
+`gem "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).
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host_name: "<application-host-name>",
+  scope: "read_orders,read_products,etc",
+  session_storage: ShopifyAPI::Auth::FileSessionStorage.new, # This is only to be used for testing, more information in session docs
+  is_embedded: true, # Set to true if you are building an embedded app
+  is_private: false, # Set to true if you are building a private app
+  api_version: "2021-01" # The vesion of the API you would like to use
+)
+```
+
+### Setup a Session Store
+
+In order for the Shopify API gem to properly store sessions it needs an implementation of `ShopifyAPI::Auth::SessionStorage`. There is one provided in the gem, `ShopifyAPI::Auth::FileSessionStorage`, this is suitable for testing, however it is not intended for production apps. See the [Session Storage doc](usage/session_storage.md) for instructions on how to create a custom session store for a production application.
+
+Normally session information would be stored in cookies on the browser. However, due to restrictions with modern browsers we highly discourage using cookies for embedded apps. For this reason, an app needs to define a storage implementation that can be used to store and retrieve a session given an ID. In a non embedded app this ID will come from a cookie however, in an embedded app this ID will come from [App Bridge](https://shopify.dev/apps/tools/app-bridge)
+
+### Performing OAuth
+
+Next, unless you are making a private app, you need to go through OAuth as described [here](https://shopify.dev/apps/auth/oauth) 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](usage/oauth.md) 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](usage/webhooks.md) for instructions on registering and handling webhooks.
+
+### Start Making Authenticated Shopify Requests
+
+You can now start making authenticated Shopify API calls using the Admin [REST](usage/rest.md) or [GraphQL](usage/graphql.md) Clients or the [Storefront GraphQL Client](usage/graphql_storefront.md).

data/docs/issues.md

@@ -0,0 +1,39 @@
+# Known issues and caveats
+
+By following this guide, you will have a fully functional Shopify app. However, there are some things you should be aware of before using your new app in a production environment.
+
+## Notes on session handling
+
+Before you start writing your application, please note that the Shopify library needs to store some information for OAuth in sessions. Since each application may choose a different strategy to store information, the library cannot dictate any specific storage strategy. When calling `ShopifyAPI::Context.setup`, you'll need to provide an instance of a class that implements the `ShopifyAPI::Auth::SessionStorage` interface.
+
+This library provides a very simple implementation of that interface which stores sessions in files, `ShopifyAPI::Auth::FileSessionStorage` ([source code](../lib/shopify_api/auth/file_session_storage.rb)). This class is meant to speed up development with this library, but it is not suitable for production use, because it will lead to disk build-up as old sessions are not cleaned up.
+
+Before you deploy your app to production, it should use your selected storage method for sessions. You can do that by creating a class that implements the `SessionStorage` interface and pass that in your `Context.setup` call. Your class will need to implement the methods below.
+
+**Note**: After you create your implementation of `SessionStorage`, you should make sure to clean up old sessions periodically in your data storage. The library will delete some sessions when they are no longer useful, but it cannot guarantee that expired sessions are deleted automatically.
+
+#### `SessionStorage.storeSession`
+
+Creates **or updates** a `Session` object in your storage. This function should return a `bool` indicating whether the operation was successful.
+
+| Param     | Type      | Notes                       |
+| --------- | --------- | --------------------------- |
+| `session` | `Session` | The session object to store |
+
+#### `SessionStorage.loadSession`
+
+Fetches a `Session` object from your storage. This function should return a `Session` object, or `null` if it was not found.
+
+| Param       | Type     | Notes                         |
+| ----------- | -------- | ----------------------------- |
+| `sessionId` | `string` | The id of the session to load |
+
+#### `SessionStorage.deleteSession`
+
+Deletes a session from your storage. This function should return a `bool` indicating whether the operation was successful.
+
+| Param       | Type     | Notes                           |
+| ----------- | -------- | ------------------------------- |
+| `sessionId` | `string` | The id of the session to delete |
+
+[Back to guide index](README.md)

data/docs/usage/graphql.md

@@ -0,0 +1,115 @@
+# Make a GraphQL API call
+
+Once you have a [session](https://github.com/Shopify/shopify_api/blob/main/docs/usage/oauth.md#fetching-sessions) after completing oauth, you can make GraphQL queries to the Admin API with `ShopifyAPI::Clients::Graphql::Admin`
+
+Below is an example
+
+```ruby
+# load the current session with SessionUtils.load_current_session
+session = ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
+
+# initalize the client
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+# make the GraphQL query string
+query =<<~QUERY
+  {
+    products(first: 10) {
+      edges {
+        cursor
+        node {
+          id
+          title
+          onlineStoreUrl
+        }
+      }
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+# do something with the response data
+```
+
+You can also make GraphQL calls that take in variables
+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+query = <<~QUERY
+  query testQueryWithVariables($first: Int!){
+    products(first: $first) {
+      edges {
+        cursor
+        node {
+          id
+          title
+          onlineStoreUrl
+        }
+      }
+    }
+  }
+QUERY
+variables = {
+  first: 3
+}
+
+response = client.query(data: query, variables: variables)
+
+```
+
+Here is an example of how you might use fragments as part of the client
+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+# define the fragment as part of the query
+query = <<~QUERY
+  fragment ProductStuff on Product {
+    id
+    title
+    description
+    onlineStoreUrl
+  }
+  query testQueryWithVariables($first: Int){
+    products(first: $first) {
+      edges {
+        cursor
+        node {
+          ...ProductStuff
+        }
+      }
+    }
+  }
+QUERY
+variables = {
+  first: 3
+}
+response = client.query(query: query, variables: variables)
+# do something with the reponse
+```
+
+Want to make calls to the Storefront API? Click [here](graphql_storefront.md)
+
+# Proxy a GraphQL Query
+
+If you would like to give your front end the ability to make authenticated graphql queries to the Shopify Admin API, the `shopify_api` gem makes proxying a graphql request easy! The gem provides a utility function which will accept the raw request body (a GraphQL query), the headers, and the cookies (optional). It will add authentication to the request, proxy it to the Shopify Admin API, and return a `ShopifyAPI::Clients::HttpResponse`. An example utilization of this in Rails is shown below:
+
+```ruby
+def proxy
+  begin
+    response = ShopifyAPI::Utils::GraphqlProxy.proxy_query(
+      headers: request.headers.to_h,
+      body: request.raw_post,
+      cookies: request.cookies.to_h
+    )
+
+    render json: response.body, status: response.code
+  rescue ShopifyAPI::Errors::InvalidGraphqlRequestError
+    # Handle bad request
+  rescue ShopifyAPI::Errors::SessionNotFoundError
+    # Handle no session found
+  end
+end
+```
+
+**Note:** GraphQL proxying is only supported for online sessions for non-private apps, the utility will raise a `ShopifyAPI::Errors::SessionNotFoundError` if there are no existing online tokens for the provided credentials, and a `ShopifyAPI::Errors::PrivateAppError` if called from a private app.

data/docs/usage/graphql_storefront.md

@@ -0,0 +1,42 @@
+# Make a Storefront API call
+
+The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/storefront-api). To do that, you can use `ShopifyAPI::Clients::Graphql::Storefront` with the current session and a `storefrontAccessToken`.
+
+You can obtain Storefront API access tokens for both private apps and sales channels. Please read [our documentation](https://shopify.dev/docs/storefront-api/getting-started) to learn more about Storefront Access Tokens.
+
+Below is an example of how you may query the Storefront API:
+
+```ruby
+# Load the access token as per instructions above
+storefront_access_token = ''
+# your shop domain
+shop_url = 'shop.myshopify.com'
+
+# initialize the client with session and storefront access token
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token)
+
+query = <<~QUERY
+  {
+    collections(first: 2) {
+      edges {
+        node {
+          id
+          products(first: 5) {
+            edges {
+              node {
+                id
+                title
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+# do something with the returned data
+```
+
+Want to make calls to the Admin API? Click [here](graphql.md)

data/docs/usage/oauth.md

@@ -0,0 +1,105 @@
+# Performing OAuth
+
+Once the library is set up for your project, you'll be able to use it to start adding functionality to your app. The first thing your app will need to do is to obtain an access token to the Admin API by performing the OAuth process.
+
+To do this, you can follow the steps below.
+
+**Note:** You do not need to go through the OAuth process if you are creating a private app. In this case you can simply set your `<key+password>` as the `api_secret_key` in `ShopifyAPI::Context.setup`. For more information on authenticating a Shopify app please see the [Types of Authentication](https://shopify.dev/apps/auth#types-of-authentication) page.
+
+## Add a route to start OAuth
+
+The route for starting the OAuth process (in this case `/login`) will use the library's `begin_auth` method. The method will return an `auth_route` URI that will be used for redirecting the user to the Shopify Authentication screen and a session cookie to store on the user's browser. These return values will be a hash in the form of {`auth_route`: `String`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}
+
+| Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
+| -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
+| `shop`          | `String`               |    Yes    |       -       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                                            |
+| `redirect_path` | `String`               |    Yes    |       -       | The redirect path used for callback with a leading `/`. The route should be allowed under the app settings. |
+| `is_online`     | `Boolean`              |    No     |    `true`     | `true` if the session is online and `false` otherwise.                                                      |
+
+Your app should take the returned values from the `begin_auth` function and redirect the user to url defined by `auth_route` and set the cookie in the user's browser. We strongly recommend that you use secure, httpOnly cookies for this to help prevent session hijacking.
+
+An example is shown below in a Rails app but these steps could be applied in any framework:
+
+```ruby
+class ShopifyAuthController < ApplicationController
+  def login
+    shop = request.headers["Shop"]
+
+    auth_response = ShopifyAPI::Auth::Oauth.begin_auth(shop: domain, redirect_path: "/auth/callback")
+
+    cookies[auth_response[:cookie].name] = {
+      expires: auth_response[:cookie].expires,
+      secure: true,
+      http_only: true,
+      value: auth_response[:cookie].value
+    }
+
+    head 307
+    response.set_header("Location", auth_response[:auth_route])
+  end
+end
+```
+
+## Add your OAuth callback route
+
+After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `begin_auth`, above). Your app will now use the provided `validate_auth_callback` method to finalize the OAuth process. This method returns a hash containing the new session and a cookie to be set in the browser in form of {`session`: `ShopifyAPI::Auth::Session`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}.
+
+An example is shown below in a Rails app but these steps could be applied in any framework:
+
+```ruby
+def callback
+  begin
+    auth_result = ShopifyAPI::Auth::Oauth.validate_auth_callback(
+      cookies: cookies.to_h,
+      auth_query: ShopifyAPI::Auth::Oauth::AuthQuery.new(request.parameters.symbolize_keys.except(:controller, :action))
+    )
+    
+    cookies[auth_result[:cookie].name] = {
+      expires: auth_result[:cookie].expires,
+      secure: true,
+      http_only: true,
+      value: auth_result[:cookie].value
+    }
+
+    puts("OAuth complete! New access token: #{auth_result[:session].access_token}")
+
+    head 307
+    response.set_header("Location", "<some-redirect-url>")
+  rescue => e
+    puts(e.message)  
+    head 500
+  end
+end
+```
+## Fetching sessions
+
+You can use the OAuth methods to create both offline and online sessions. Once the process is completed, the session will be stored as per your `Context.session_storage`, and can be retrieved with `SessionUtils` class methods.
+
+- To load current session, you can use the following method:
+
+```ruby
+ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
+```
+
+Accepted arguments:
+| Parameter   | Type                      | Notes                                                                                                                                                                     |
+| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth_header`   | `String`    | JWT token will be extracted from `auth_header` to load session for embedded apps. If JWT token is not provided this methods will try with `cookies`. Only required if trying to load, an embedded session. |
+| `cookies`   | `Hash(String, String)`    | The cookies from the HTTP request. A session cookie named `shopify_app_session` is used to load session for non-embedded apps. Can be omitted if loading and embedded session without falling back on cookies |
+| `is_online` | `Boolean`                 | Whether to load online or offline sessions. Defaults to `false` |
+
+This method will return a `ShopifyAPI::Auth::Session`  if a session exists. Either a proper token or a proper cookie must be present.
+
+- To load offline session, you can use the following method:
+
+```ruby
+ShopifyAPI::Utils::SessionUtils.load_offline_session(shop)
+```
+
+Accepted arguments:
+| Parameter           | Type      | Notes                                                                                                                                                                     |
+| ------------------- | --------- | --------------------------------------------- |
+| `shop`              | `String`  | The shop url to find the offline session for. |
+| `include_expired`   | `Boolean` | Include expired sessions or not.              |
+
+This method will return a `ShopifyAPI::Auth::Session` if a session exists and `nil` otherwise. This method **does not** perform any validation on the shop domain, so it **must not** rely on user input for the domain. This method is typically meant to be used in background tasks like webhooks, where the data is expected to have been validated when the task was enqueued.

data/docs/usage/rest.md

@@ -0,0 +1,137 @@
+# Make a REST API call
+
+Once OAuth is complete, we can use the `ShopifyAPI::Clients::Rest::Admin` client to make an API call to the Shopify Admin API. To do this, you can create an instance of `ShopifyAPI::Clients::Rest::Admin` using the current session to make requests to the Admin API.
+
+## Methods
+
+The Rest Admin client offers the 4 core request methods: `get`, `delete`, `post`, and `put`. These methods each take the parameters outlined in the table below. If the request is successful these methods will all return a `ShopifyAPI::Clients::HttpResponse` object, which has properties `code`, `headers`, and `body` otherwise an error will be raised describing what went wrong.
+
+| Parameter      | Type                                                     | Required in Methods | Default Value | Notes                                                                                                                                                                                                                                                                                  |
+| -------------- | -------------------------------------------------------- | :-----------------: | :-----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`         | `String`                                                 |         all         |     none      | The requested API endpoint path. This can be one of two formats:<ul><li>The path starting after the `/admin/api/{version}/` prefix, such as `products`, which executes `/admin/api/{version}/products.json`</li><li>The full path, such as `/admin/oauth/access_scopes.json`</li></ul> |
+| `body`         | `Hash(any(Symbol, String), untyped)`                     |    `put`, `post`    |     none      | The body of the request                                                                                                                                                                                                                                                                |
+| `query`        | `Hash(any(Symbol, String), any(String, Integer, Float))` |        none         |     none      | An optional query object to be appended to the request url as a query string                                                                                                                                                                                                           |
+| `extraHeaders` | `Hash(any(Symbol, String), any(String, Integer, Float))` |        none         |     none      | Any additional headers you want to send with your request                                                                                                                                                                                                                              |
+| `tries`        | `Integer`                                                |        None         |      `1`      | The maximum number of times to try the request _(must be >= 0)_                                                                                                                                                                                                                        |
+
+**Note:** _These paramaters can still be used in all methods regardless of if they are required._
+
+## Usage Examples:
+
+### Perform a `GET` request:
+
+```ruby
+# Load the current session to get the `accessToken`.
+session = ShopifyAPI::Auth::SessionLoader.load_current_session(headers, cookies, is_online)
+
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Use `client.get` to request the specified Shopify REST API endpoint, in this case `products`.
+response = client.get(path: "products")
+
+# Do something with the returned data
+some_function(response.body)
+```
+
+### Perform a `POST` request:
+
+```ruby
+# Load the current session to get the `accessToken`.
+session = ShopifyAPI::Auth::SessionLoader.load_current_session(headers, cookies, is_online)
+
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Build your post request body.
+body = {
+  product: {
+    title: "Burton Custom Freestyle 151",
+    body_html: "\u003cstrong\u003eGood snowboard!\u003c\/strong\u003e",
+    vendor: "Burton",
+    product_type: "Snowboard",
+  }
+}
+
+# Use `client.post` to send your request to the specified Shopify Admin REST API endpoint.
+client.post({
+  path: "products",
+  body: body,
+});
+```
+
+_for more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/api/admin-rest/unstable/resources/product)._
+
+## Pagination
+
+This library also supports cursor-based pagination for REST Admin API requests. [Learn more about REST request pagination](https://shopify.dev/api/usage/pagination-rest).
+
+After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and passed as the page_info query param in other requests.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Auth::SessionLoader.load_current_session(headers, cookies, is_online)
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+response = client.get(path: "products", query: { limit: 10 })
+
+loop do
+  some_function(response.body)
+  break unless response.next_page_info
+  response =  client.get(path: "products", query: { limit: 10, page_info: response.next_page_info })
+end
+```
+
+Similarly, when using REST resources the `next_page_info` and `prev_page_info` can be found on the Resource class and passed as the page_info query param in other requests.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Auth::SessionLoader.load_current_session(headers, cookies, is_online)
+
+products = ShopifyAPI::Product.all(session: session, limit: 10)
+
+loop do
+  some_function(products)
+  break unless ShopifyAPI::Product.next_page?
+  products = ShopifyAPI::Product.all(session: session, limit: 10, page_info: ShopifyAPI::Product.next_page_info)
+end
+```
+
+The next/previous page_info strings can also be retrieved from the response object and added to a request query to retrieve the next/previous pages.
+
+An example of this is shown below:
+
+```ruby
+session = ShopifyAPI::Auth::SessionLoader.load_current_session(headers, cookies, is_online)
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+response = client.get(path: "products", query: { limit: 10 })
+next_page_info = response.next_page_info
+
+if next_page_info
+  next_page_response =client.get(path: "products", query: { limit: 10, page_info: next_page_info })
+  some_function(next_page_response)
+end
+```
+
+### Error Messages
+
+You can rescue `ShopifyAPI::Errors::HttpResponseError` and output error messages with `errors.full_messages`
+
+See example:
+
+```ruby
+ fulfillment = ShopifyAPI::Fulfillment.new(session: @session)
+  fulfillment.order_id = 2776493818000
+  ...
+  fulfillment.tracking_company = "Jack Black's Pack, Stack and Track"
+  fulfillment.save()
+rescue ShopifyAPI::Errors::HttpResponseError => e
+  puts fulfillment.errors.full_messages
+  # {"base"=>["Line items are already fulfilled"]}
+  # If you report this error, please include this id: e712dde0-1270-4258-8cdb-d198792c917e.
+```
+
+[Back to guide index](../README.md)