Shopify API Library for Ruby

The shopify_api gem provides a comprehensive suite of tools for interacting with Shopify's APIs (REST, GraphQL, Storefront, and Webhooks) using Ruby. To begin building, you should follow the specific guides for your intended integration path:

• Core Setup: Follow the Getting started guide for initial library configuration.
• Authentication: Use the Performing OAuth guide to handle shop authorization.
• Admin API (REST): Use the REST Admin API guide for managing store resources.
• Admin API (GraphQL): Use the Make a GraphQL API call guide for complex queries and mutations.
• Storefront API: Use the Make a Storefront API call guide for building customer-facing experiences.
• Webhooks: Use the Webhooks guide to handle real-time events from Shopify.

Before you can register webhooks for specific shops, you must add the desired topics to the local ShopifyAPI::Webhooks::Registry. This should be done once during app startup (e.g., when setting up ShopifyAPI::Context).

Use ShopifyAPI::Webhooks::Registry.add_registration with the following parameters:

• topic (String): The webhook topic (e.g., "orders/create").
• delivery_method (Symbol): The method of delivery. Supported values: :http, :event_bridge, :pub_sub.
• handler (Class/Module): The handler implementation (required for :http).
• path (String): The relative path for HTTP webhooks, or an ARN/PubSub URI for other methods.
• fields (Array of Strings or comma-separated String, optional): Filters the payload to specific fields.
• metafieldNamespaces (Array of Strings, optional): Ensures specific metafield namespaces are included in the payload. If using fields, you must also include "metafields" in the fields list.
• filter (String, optional): A webhooks filter string.

Note: The local registry must be reloaded whenever your server restarts, even though the registrations are saved on the Shopify platform.

# Basic HTTP registration
ShopifyAPI::Webhooks::Registry.add_registration(
  topic: "orders/create",
  delivery_method: :http,
  handler: WebhookHandler,
  path: 'callback/orders/create'
)

# Registration with field filtering
ShopifyAPI::Webhooks::Registry.add_registration(
  topic: "orders/create",
  delivery_method: :http,
  handler: WebhookHandler,
  path: 'callback/orders/create',
  fields: ["number", "note"]
)

# Registration with metafield namespaces
ShopifyAPI::Webhooks::Registry.add_registration(
  topic: "orders/create",
  delivery_method: :http,
  handler: WebhookHandler,
  metafieldNamespaces: ["custom"]
)

# Registration with a filter
ShopifyAPI::Webhooks::Registry.add_registration(
  topic: "products/update",
  delivery_method: :http,
  handler: WebhookHandler,
  filter: "variants.price:>=10.00"
)

You can use ShopifyAPI::Utils::GraphqlProxy.proxy_query to allow your front-end to make authenticated GraphQL requests to the Shopify Admin API through your server. This utility handles authentication and proxies the request.

Implementation Example (Rails)

def proxy
  begin
    response = ShopifyAPI::Utils::GraphqlProxy.proxy_query(
      session: session,
      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

Constraints

• Online Sessions Only: Proxying is only supported for online sessions for non-private apps.
• Errors:
  • Raises ShopifyAPI::Errors::SessionNotFoundError if no online tokens exist for the credentials.
  • Raises ShopifyAPI::Errors::PrivateAppError if called from a private app.

To avoid passing a session object to every single method call, you can set a global active_session using ShopifyAPI::Context.activate_session(session). When an API client is initialized without a specific session argument, it will automatically use the session currently set in ShopifyAPI::Context.

#### Configuration
def configure_app
  session = ShopifyAPI::Auth::Session.new(
      shop: "#{your_shop_name}.myshopify.com",
      access_token: "the_token_for_your_custom_app_found_in_admin"
    )

  ShopifyAPI::Context.setup(
    api_key: "<api-key>",
    api_secret_key: "<api-secret-key>",
    scope: "read_orders,read_products,etc",
    is_embedded: true,
    api_version: "2024-01",
    is_private: true,
  )

  # Activate session to be used in all subsequent API calls
  ShopifyAPI::Context.activate_session(session)
end

#### Using clients
def make_api_request
  # This client will automatically use the active_session from Context
  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(api_version: "2024-07")

  query = "{ products(first: 10) { edges { node { id title } } }"
  response = graphql_client.query(query: query)

  # REST resources also use the active_session
  product_count = ShopifyAPI::Product.count
end