shopify_api 14.11.1 → 16.0.0

data/docs/usage/oauth.md

@@ -13,6 +13,9 @@ For more information on authenticating a Shopify app please see the [Types of Au
   - [Token Exchange](#token-exchange)
   - [Authorization Code Grant](#authorization-code-grant)
   - [Client Credentials Grant](#client-credentials-grant)
+- [Expiring Offline Access Tokens](#expiring-offline-access-tokens)
+  - [Refreshing Access Tokens](#refreshing-access-tokens)
+  - [Migrating Non-Expiring Tokens to Expiring Tokens](#migrating-non-expiring-tokens-to-expiring-tokens)
 - [Using OAuth Session to make authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls)
 
 ## Session Persistence
@@ -305,6 +308,132 @@ end
 
 ```
 
+## Expiring Offline Access Tokens
+
+
+To start requesting expiring offline access tokens, set the `expiring_offline_access_tokens` parameter to `true` when setting up the Shopify context:
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: <SHOPIFY_API_KEY>,
+  api_secret_key: <SHOPIFY_API_SECRET>,
+  api_version: <SHOPIFY_API_VERSION>,
+  scope: <SHOPIFY_API_SCOPES>,
+  expiring_offline_access_tokens: true, # Enable expiring offline access tokens
+  ...
+)
+```
+
+When enabled:
+- **Authorization Code Grant**: The OAuth flow will request expiring offline access tokens by sending `expiring: 1` parameter
+- **Token Exchange**: When requesting offline access tokens via token exchange, the flow will request expiring tokens
+
+The resulting `Session` object will contain:
+- `access_token`: The access token that will eventually expire
+- `expires`: The expiration time for the access token
+- `refresh_token`: A token that can be used to refresh the access token
+- `refresh_token_expires`: The expiration time for the refresh token
+
+### Refreshing Access Tokens
+
+When your access token expires, you can use the refresh token to obtain a new access token using the `ShopifyAPI::Auth::RefreshToken.refresh_access_token` method.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                               |
+| `refresh_token`| `String` | Yes       | The refresh token from the session.                                                             |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with a fresh access token and a new refresh token. Your app should store this new session to replace the expired one.
+
+#### Example
+```ruby
+def refresh_session(shop, refresh_token)
+  begin
+    # Refresh the access token using the refresh token
+    new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+      shop: shop,
+      refresh_token: refresh_token
+    )
+
+    # Store the new session, replacing the old one
+    MyApp::SessionRepository.store_shop_session(new_session)
+  rescue ShopifyAPI::Errors::HttpResponseError => e
+    puts("Failed to refresh access token: #{e.message}")
+    raise e
+  end
+end
+```
+#### Checking Token Expiration
+The `Session` object provides helper methods to check if tokens have expired:
+
+```ruby
+session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+# Check if the access token has expired
+if session.expired?
+  # Access token has expired, refresh it
+  new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+    shop: session.shop,
+    refresh_token: session.refresh_token
+  )
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+
+# Check if the refresh token has expired
+if session.refresh_token_expired?
+  # Refresh token has expired, need to re-authenticate with OAuth
+end
+```
+
+### Migrating Non-Expiring Tokens to Expiring Tokens
+
+If you have existing non-expiring offline access tokens and want to migrate them to expiring tokens, you can use the `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method. This performs a token exchange that converts your non-expiring offline token into an expiring one with a refresh token.
+
+> [!WARNING]
+> This is a **one-time, irreversible migration** per shop. Once you migrate a shop's token to an expiring token, you cannot convert it back to a non-expiring token. The shop would need to reinstall your app with `expiring_offline_access_tokens: false` in your Context configuration to obtain a new non-expiring token.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                               |
+| `non_expiring_offline_token` | `String` | Yes | The non-expiring offline access token to migrate. |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with an expiring access token and refresh token. Your app should store this new session to replace the non-expiring one.
+
+#### Example
+```ruby
+def migrate_shop_to_expiring_offline_token(shop)
+  # Retrieve the existing non-expiring session
+  old_session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+  # Migrate to expiring token
+  new_session = ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+    shop: shop,
+    non_expiring_offline_token: old_session.access_token
+  )
+
+  # Store the new expiring session, replacing the old one
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+```
+
+#### Migration Strategy
+When migrating your app to use expiring tokens, follow this order:
+
+1. **Update your database schema** to add `expires_at` (timestamp), `refresh_token` (string) and `refresh_token_expires` (timestamp) columns to your session storage
+2. **Implement refresh logic** in your app to handle token expiration using `ShopifyAPI::Auth::RefreshToken.refresh_access_token`
+3. **Enable expiring tokens in your Context setup** so new installations will request and receive expiring tokens:
+   ```ruby
+   ShopifyAPI::Context.setup(
+     expiring_offline_access_tokens: true,
+     # ... other config
+   )
+   ```
+4. **Migrate existing non-expiring tokens** for shops that have already installed your app using the migration method above
+
 ## Using OAuth Session to make authenticated API calls
 Once your OAuth flow is complete, and you have persisted your `Session` object, you may use that `Session` object to make authenticated API calls.
 

data/docs/usage/webhooks.md

@@ -29,26 +29,9 @@ module WebhookHandler
 end
 ```
 
-**Note:** As of version 13.5.0 the `ShopifyAPI::Webhooks::Handler` class is still available to be used but will be removed in a future version of the gem.
-
 ### Best Practices
 It is recommended that in order to respond quickly to the Shopify webhook request that the handler not do any heavy logic or network calls, rather it should simply enqueue the work in some job queue in order to be executed later.
 
-### Webhook Handler for versions 13.4.0 and prior
-If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::Handler` and implement the handle method which accepts the following named parameters: topic: `String`, shop: `String`, and body: `Hash[String, untyped]`. An example implementation is shown below:
-
-```ruby
-module WebhookHandler
-  extend ShopifyAPI::Webhooks::Handler
-
-  class << self
-    def handle(topic:, shop:, body:)
-      puts "Received webhook! topic: #{topic} shop: #{shop} body: #{body}"
-    end
-  end
-end
-```
-
 ## Add to Webhook Registry
 
 The next step is to add all the webhooks you would like to subscribe to for any shop to the webhook registry. To do this you can call `ShopifyAPI::Webhooks::Registry.add_registration` for each webhook you would like to handle. `add_registration` accepts a topic string, a delivery_method symbol (currently supporting `:http`, `:event_bridge`, and `:pub_sub`), a webhook path (the relative path for an http webhook) and a handler. This only needs to be done once when the app is started and we recommend doing this at the same time that you setup `ShopifyAPI::Context`. An example is shown below to register an http webhook:

data/lib/shopify_api/admin_versions.rb

@@ -5,6 +5,7 @@ module ShopifyAPI
   module AdminVersions
     SUPPORTED_ADMIN_VERSIONS = T.let([
       "unstable",
+      "2026-01",
       "2025-10",
       "2025-07",
       "2025-04",
@@ -22,12 +23,7 @@ module ShopifyAPI
       "2022-04",
       "2022-01",
     ], T::Array[String])
-
-    LATEST_SUPPORTED_ADMIN_VERSION = T.let("2025-07", String)
-    RELEASE_CANDIDATE_ADMIN_VERSION = T.let("2025-10", String)
   end
 
   SUPPORTED_ADMIN_VERSIONS = ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS
-  LATEST_SUPPORTED_ADMIN_VERSION = ShopifyAPI::AdminVersions::LATEST_SUPPORTED_ADMIN_VERSION
-  RELEASE_CANDIDATE_ADMIN_VERSION = ShopifyAPI::AdminVersions::RELEASE_CANDIDATE_ADMIN_VERSION
 end

data/lib/shopify_api/auth/oauth/access_token_response.rb

@@ -13,6 +13,8 @@ module ShopifyAPI
         const :expires_in, T.nilable(Integer)
         const :associated_user, T.nilable(AssociatedUser)
         const :associated_user_scope, T.nilable(String)
+        const :refresh_token, T.nilable(String)
+        const :refresh_token_expires_in, T.nilable(Integer)
 
         sig { returns(T::Boolean) }
         def online_token?
@@ -29,7 +31,9 @@ module ShopifyAPI
             session == other.session &&
             expires_in == other.expires_in &&
             associated_user == other.associated_user &&
-            associated_user_scope == other.associated_user_scope
+            associated_user_scope == other.associated_user_scope &&
+            refresh_token == other.refresh_token &&
+            refresh_token_expires_in == other.refresh_token_expires_in
         end
       end
     end

data/lib/shopify_api/auth/oauth.rb

@@ -71,7 +71,12 @@ module ShopifyAPI
             "Invalid state in OAuth callback." unless state == auth_query.state
 
           null_session = Auth::Session.new(shop: auth_query.shop)
-          body = { client_id: Context.api_key, client_secret: Context.api_secret_key, code: auth_query.code }
+          body = {
+            client_id: Context.api_key,
+            client_secret: Context.api_secret_key,
+            code: auth_query.code,
+            expiring: Context.expiring_offline_access_tokens ? 1 : 0, # Only applicable for offline tokens
+          }
 
           client = Clients::HttpClient.new(session: null_session, base_path: "/admin/oauth")
           response = begin
@@ -100,7 +105,7 @@ module ShopifyAPI
           else
             SessionCookie.new(
               value: session.id,
-              expires: session.online? ? session.expires : nil,
+              expires: session.expires ? session.expires : nil,
             )
           end
 

data/lib/shopify_api/auth/refresh_token.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module Auth
+    module RefreshToken
+      extend T::Sig
+
+      class << self
+        extend T::Sig
+
+        sig do
+          params(
+            shop: String,
+            refresh_token: String,
+          ).returns(ShopifyAPI::Auth::Session)
+        end
+        def refresh_access_token(shop:, refresh_token:)
+          unless ShopifyAPI::Context.setup?
+            raise ShopifyAPI::Errors::ContextNotSetupError,
+              "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+
+          shop_session = ShopifyAPI::Auth::Session.new(shop:)
+          body = {
+            client_id: ShopifyAPI::Context.api_key,
+            client_secret: ShopifyAPI::Context.api_secret_key,
+            grant_type: "refresh_token",
+            refresh_token:,
+          }
+
+          client = Clients::HttpClient.new(session: shop_session, base_path: "/admin/oauth")
+          response = begin
+            client.request(
+              Clients::HttpRequest.new(
+                http_method: :post,
+                path: "access_token",
+                body:,
+                body_type: "application/json",
+              ),
+            )
+          rescue ShopifyAPI::Errors::HttpResponseError => error
+            ShopifyAPI::Context.logger.debug("Failed to refresh access token: #{error.message}")
+            raise error
+          end
+
+          session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
+
+          Session.from(
+            shop:,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/auth/session.rb

@@ -30,6 +30,12 @@ module ShopifyAPI
       sig { returns(T.nilable(String)) }
       attr_accessor :shopify_session_id
 
+      sig { returns(T.nilable(String)) }
+      attr_accessor :refresh_token
+
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :refresh_token_expires
+
       sig { returns(T::Boolean) }
       def online?
         @is_online
@@ -40,6 +46,11 @@ module ShopifyAPI
         @expires ? @expires < Time.now : false
       end
 
+      sig { returns(T::Boolean) }
+      def refresh_token_expired?
+        @refresh_token_expires ? @refresh_token_expires < Time.now + 60 : false
+      end
+
       sig do
         params(
           shop: String,
@@ -52,10 +63,12 @@ module ShopifyAPI
           is_online: T.nilable(T::Boolean),
           associated_user: T.nilable(AssociatedUser),
           shopify_session_id: T.nilable(String),
+          refresh_token: T.nilable(String),
+          refresh_token_expires: T.nilable(Time),
         ).void
       end
       def initialize(shop:, id: nil, state: nil, access_token: "", scope: [], associated_user_scope: nil, expires: nil,
-        is_online: nil, associated_user: nil, shopify_session_id: nil)
+        is_online: nil, associated_user: nil, shopify_session_id: nil, refresh_token: nil, refresh_token_expires: nil)
         @id = T.let(id || SecureRandom.uuid, String)
         @shop = shop
         @state = state
@@ -68,6 +81,8 @@ module ShopifyAPI
         @associated_user = associated_user
         @is_online = T.let(is_online || !associated_user.nil?, T::Boolean)
         @shopify_session_id = shopify_session_id
+        @refresh_token = refresh_token
+        @refresh_token_expires = refresh_token_expires
       end
 
       class << self
@@ -105,6 +120,10 @@ module ShopifyAPI
             expires = Time.now + access_token_response.expires_in.to_i
           end
 
+          if access_token_response.refresh_token_expires_in
+            refresh_token_expires = Time.now + access_token_response.refresh_token_expires_in.to_i
+          end
+
           new(
             id: id,
             shop: shop,
@@ -115,31 +134,28 @@ module ShopifyAPI
             associated_user: associated_user,
             expires: expires,
             shopify_session_id: access_token_response.session,
+            refresh_token: access_token_response.refresh_token,
+            refresh_token_expires: refresh_token_expires,
           )
         end
-
-        sig { params(str: String).returns(Session) }
-        def deserialize(str)
-          Oj.load(str)
-        end
       end
 
       sig { params(other: Session).returns(Session) }
       def copy_attributes_from(other)
-        JSON.parse(other.serialize).keys.each do |key|
-          next if key.include?("^")
-
-          variable_name = "@#{key}"
-          instance_variable_set(variable_name, other.instance_variable_get(variable_name))
-        end
+        @shop = other.shop
+        @state = other.state
+        @access_token = other.access_token
+        @scope = other.scope
+        @associated_user_scope = other.associated_user_scope
+        @expires = other.expires
+        @associated_user = other.associated_user
+        @is_online = other.online?
+        @shopify_session_id = other.shopify_session_id
+        @refresh_token = other.refresh_token
+        @refresh_token_expires = other.refresh_token_expires
         self
       end
 
-      sig { returns(String) }
-      def serialize
-        Oj.dump(self)
-      end
-
       alias_method :eql?, :==
       sig { params(other: T.nilable(Session)).returns(T::Boolean) }
       def ==(other)
@@ -153,8 +169,9 @@ module ShopifyAPI
             (!(expires.nil? ^ other.expires.nil?) && (expires.nil? || expires.to_i == other.expires.to_i)) &&
             online? == other.online? &&
             associated_user == other.associated_user &&
-            shopify_session_id == other.shopify_session_id
-
+            shopify_session_id == other.shopify_session_id &&
+            refresh_token == other.refresh_token &&
+            refresh_token_expires&.to_i == other.refresh_token_expires&.to_i
         else
           false
         end

data/lib/shopify_api/auth/token_exchange.rb

@@ -49,6 +49,10 @@ module ShopifyAPI
             requested_token_type: requested_token_type.serialize,
           }
 
+          if requested_token_type == RequestedTokenType::OFFLINE_ACCESS_TOKEN
+            body.merge!({ expiring: ShopifyAPI::Context.expiring_offline_access_tokens ? 1 : 0 })
+          end
+
           client = Clients::HttpClient.new(session: shop_session, base_path: "/admin/oauth")
           response = begin
             client.request(
@@ -74,6 +78,52 @@ module ShopifyAPI
             access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
           )
         end
+
+        sig do
+          params(
+            shop: String,
+            non_expiring_offline_token: String,
+          ).returns(ShopifyAPI::Auth::Session)
+        end
+        def migrate_to_expiring_token(shop:, non_expiring_offline_token:)
+          unless ShopifyAPI::Context.setup?
+            raise ShopifyAPI::Errors::ContextNotSetupError,
+              "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+
+          shop_session = ShopifyAPI::Auth::Session.new(shop: shop)
+          body = {
+            client_id: ShopifyAPI::Context.api_key,
+            client_secret: ShopifyAPI::Context.api_secret_key,
+            grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+            subject_token: non_expiring_offline_token,
+            subject_token_type: RequestedTokenType::OFFLINE_ACCESS_TOKEN.serialize,
+            requested_token_type: RequestedTokenType::OFFLINE_ACCESS_TOKEN.serialize,
+            expiring: "1",
+          }
+
+          client = Clients::HttpClient.new(session: shop_session, base_path: "/admin/oauth")
+          response = begin
+            client.request(
+              Clients::HttpRequest.new(
+                http_method: :post,
+                path: "access_token",
+                body: body,
+                body_type: "application/json",
+              ),
+            )
+          rescue ShopifyAPI::Errors::HttpResponseError => error
+            ShopifyAPI::Context.logger.debug("Failed to migrate to expiring offline token: #{error.message}")
+            raise error
+          end
+
+          session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
+
+          Session.from(
+            shop: shop,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
+          )
+        end
       end
     end
   end

data/lib/shopify_api/clients/graphql/storefront.rb

@@ -8,21 +8,15 @@ module ShopifyAPI
         sig do
           params(
             shop: String,
-            storefront_access_token: T.nilable(String),
             private_token: T.nilable(String),
             public_token: T.nilable(String),
             api_version: T.nilable(String),
           ).void
         end
-        def initialize(shop, storefront_access_token = nil, private_token: nil, public_token: nil, api_version: nil)
-          unless storefront_access_token.nil?
-            warning = <<~WARNING
-              DEPRECATED: Use the named parameters for the Storefront token instead of passing
-              the public token as the second argument. Also, you may want to look into using
-              the Storefront private access token instead:
-              https://shopify.dev/docs/api/usage/authentication#getting-started-with-private-access
-            WARNING
-            ShopifyAPI::Logger.deprecated(warning, "15.0.0")
+        def initialize(shop, private_token: nil, public_token: nil, api_version: nil)
+          token = private_token || public_token
+          if token.nil?
+            raise ArgumentError, "Storefront client requires either private_token or public_token to be provided"
           end
 
           session = Auth::Session.new(
@@ -32,7 +26,7 @@ module ShopifyAPI
             is_online: false,
           )
           super(session: session, base_path: "/api", api_version: api_version)
-          @storefront_access_token = T.let(T.must(private_token || public_token || storefront_access_token), String)
+          @storefront_access_token = T.let(token, String)
           @storefront_auth_header = T.let(
             private_token.nil? ? "X-Shopify-Storefront-Access-Token" : "Shopify-Storefront-Private-Token",
             String,

data/lib/shopify_api/clients/http_client.rb

@@ -112,6 +112,8 @@ module ShopifyAPI
       def serialized_error(response)
         body = {}
         body["errors"] = response.body["errors"] if response.body["errors"]
+        body["error"] = response.body["error"] if response.body["error"]
+        body["error_description"] = response.body["error_description"] if response.body["error"]
 
         if response.headers["x-request-id"]
           id = T.must(response.headers["x-request-id"])[0]

data/lib/shopify_api/context.rb

@@ -7,7 +7,7 @@ module ShopifyAPI
 
     @api_key = T.let("", String)
     @api_secret_key = T.let("", String)
-    @api_version = T.let(LATEST_SUPPORTED_ADMIN_VERSION, String)
+    @api_version = T.let("", String)
     @api_host = T.let(nil, T.nilable(String))
     @scope = T.let(Auth::AuthScopes.new, Auth::AuthScopes)
     @is_private = T.let(false, T::Boolean)
@@ -25,6 +25,7 @@ module ShopifyAPI
     @rest_disabled = T.let(false, T.nilable(T::Boolean))
 
     @rest_resource_loader = T.let(nil, T.nilable(Zeitwerk::Loader))
+    @expiring_offline_access_tokens = T.let(false, T::Boolean)
 
     class << self
       extend T::Sig
@@ -47,6 +48,7 @@ module ShopifyAPI
           api_host: T.nilable(String),
           response_as_struct: T.nilable(T::Boolean),
           rest_disabled: T.nilable(T::Boolean),
+          expiring_offline_access_tokens: T.nilable(T::Boolean),
         ).void
       end
       def setup(
@@ -65,7 +67,8 @@ module ShopifyAPI
         old_api_secret_key: nil,
         api_host: nil,
         response_as_struct: false,
-        rest_disabled: false
+        rest_disabled: false,
+        expiring_offline_access_tokens: false
       )
         unless ShopifyAPI::AdminVersions::SUPPORTED_ADMIN_VERSIONS.include?(api_version)
           raise Errors::UnsupportedVersionError,
@@ -86,6 +89,7 @@ module ShopifyAPI
         @old_api_secret_key = old_api_secret_key
         @response_as_struct = response_as_struct
         @rest_disabled = rest_disabled
+        @expiring_offline_access_tokens = T.must(expiring_offline_access_tokens)
         @log_level = if valid_log_level?(log_level)
           log_level.to_sym
         else
@@ -101,8 +105,8 @@ module ShopifyAPI
         @rest_resource_loader&.setup
         @rest_resource_loader&.unload
 
-        # No resources for the unstable version or the release candidate version
-        return if api_version == "unstable" || api_version == RELEASE_CANDIDATE_ADMIN_VERSION
+        # No resources for the unstable version
+        return if api_version == "unstable"
 
         version_folder_name = api_version.gsub("-", "_")
 
@@ -148,6 +152,9 @@ module ShopifyAPI
       sig { returns(T.nilable(String)) }
       attr_reader :private_shop, :user_agent_prefix, :old_api_secret_key, :host, :api_host
 
+      sig { returns(T::Boolean) }
+      attr_reader :expiring_offline_access_tokens
+
       sig { returns(T::Boolean) }
       def embedded?
         @is_embedded
@@ -155,7 +162,7 @@ module ShopifyAPI
 
       sig { returns(T::Boolean) }
       def setup?
-        [api_key, api_secret_key, T.must(host)].none?(&:empty?)
+        [api_key, api_secret_key, api_version, T.must(host)].none?(&:empty?)
       end
 
       sig { returns(T.nilable(Auth::Session)) }