shopify-app-js

The api-clients packages provide specialized clients for making requests to Shopify's APIs. These clients are designed to work on any JavaScript runtime that provides a fetch API implementation, provided you have the necessary access tokens.

Use these clients to interact with:

• Admin APIs (GraphQL and REST)
• Storefront API (GraphQL)
• Generic GraphQL APIs

The shopify.billing object provides functions to manage merchant payments, including checking existing plans, requesting new payments, canceling subscriptions, and managing usage-based billing.

Important Requirement: This package uses the GraphQL Admin API. Consequently, your app must complete the OAuth process before it can successfully request or look up payments for a merchant.

The shopify.utils object provides a collection of helper functions designed to simplify common tasks in Shopify app development, such as input sanitization, security validation, and API version compatibility checks.

Available utilities include:

• sanitizeShop: Validates and sanitizes Shopify shop domains to ensure user input is safe.
• sanitizeHost: Validates and sanitizes the host argument provided by Shopify for embedded apps.
• validateHmac: Validates the HMAC signature in incoming requests from Shopify to ensure authenticity.
• versionCompatible: Checks if the current library version is equal to or newer than a specified API version.
• versionPriorTo: Checks if the current library version is older than a specified API version.

Shopify provides two primary ways for app partners to charge merchants, allowing payments to be processed through Shopify Payments:

1. Shopify managed app pricing: The easiest method. You set up plans, and Shopify hosts the selection page for merchants. This requires no specific billing configuration in your app setup, though you can use the check method to retrieve plans for the current merchant.
2. Admin billing API: Used to trigger specific purchases (subscriptions or one-time charges) directly within the Shopify platform via the API.

The shopify-app-js repository provides several packages for building Shopify apps depending on your preferred runtime or framework:

• @shopify/shopify-api: A framework and runtime agnostic library. Use this if you want to build apps using pure TypeScript/JavaScript or if you are using a custom framework. It handles Shopify OAuth, APIs, webhooks, and more.
• @shopify/shopify-app-remix: A specialized implementation of @shopify/shopify-api designed specifically to simplify app development using the Remix framework.
• @shopify/shopify-app-express: A specialized implementation of @shopify/shopify-api designed specifically for use with the Express framework.

The shopify.webhooks object provides a suite of functions for managing shop-specific webhooks. This includes adding event handlers, registering those subscriptions with Shopify, and validating/processing incoming webhook requests.

Important Note on Webhook Types: Most functions in this object are intended for shop-specific webhooks. If your application only uses app-specific webhooks, you should instead use shopify.webhooks.validate to verify the authenticity of the requests. For a detailed comparison, see the App-specific vs shop-specific webhooks guide.

The shopify.clients object provides specialized client classes for interacting with different Shopify APIs. Depending on your requirements, you can use these clients to perform administrative tasks or storefront operations:

• Rest: Use the Rest class to interact with the Shopify Admin REST API.
• Graphql: Use the Graphql class to interact with the Shopify Admin GraphQL API.
• Storefront: Use the Storefront class to interact with the Shopify Storefront API.
• graphqlProxy: Use the graphqlProxy function to create a proxy that forwards requests to the GraphQL API and returns the response from Shopify.

The @shopify/shopify-api library is the central entry point for interacting with Shopify. It exports a main object (typically initialized via shopifyApi) that provides access to several specialized modules for different app functionalities.

Key modules available through the library include:

• auth: Functions for authenticating with Shopify APIs.
• clients: Clients used to make requests to Shopify APIs (e.g., Admin or Storefront).
• session: Functions for managing Shopify sessions.
• webhooks: Tools to configure and handle Shopify webhooks.
• billing: Functions to enable app billing for merchants.
• utils: General utility functions for app development.
• rest: Object-oriented representations of the Admin REST API.

When expiringOfflineAccessTokens is enabled in your configuration:

• Session Object: The refresh token is available directly on the Session object.
• New Sessions: New OAuth flows will automatically store the refresh token in the new database columns.
• Existing Sessions: Existing sessions remain functional; the new database columns are nullable, so old sessions without refresh tokens are unaffected.
• Backward Compatibility: If you do not enable expiringOfflineAccessTokens, the app will not store or use refresh tokens, and the storeSession method will continue to function normally without the new fields.