shopify-api-js

The @shopify/shopify-api library is organized into several main components that handle different aspects of interacting with Shopify. Use the following top-level objects to manage your app's integration:

• config: Options used to initialize the library.
• auth: Functions for authenticating with Shopify APIs.
• clients: Clients used to make requests to Shopify APIs (e.g., GraphQL or REST).
• session: Functions for managing Shopify sessions.
• webhooks: Functions 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 resources.

The shopify.billing object provides methods to manage billing charges with Shopify. These methods are based on the plans defined in your app's billing configuration.

Important Requirements:

• This package uses the GraphQL Admin API to request or check payments.
• Your app must complete the OAuth process before it can successfully charge merchants.

Available properties on the shopify.billing object:

• check: Verifies if the current shop has already paid for specific plans.
• request: Initiates a new payment request for a specific payment plan.
• cancel: Cancels an existing subscription plan using its subscription ID.
• subscriptions: Retrieves a list of all subscription plans the current shop has paid for.

The shopify.clients object provides specialized classes for interacting with different Shopify API surfaces. Depending on your application's needs, you can use these clients to perform RESTful operations, execute GraphQL queries, or interact with the Storefront API.

import { shopifyApi } from '@shopify/shopify-api';

// Accessing clients via the shopifyApi instance
const restClient = shopifyApi.clients.Rest;
const graphqlClient = shopifyApi.clients.Graphql;
const storefrontClient = shopifyApi.clients.Storefront;
const graphqlProxy = shopifyApi.clients.graphqlProxy;

The shopify.webhooks object provides a complete suite of functions to manage the lifecycle of Shopify webhooks within your application. You can use it to:

1. Configure handlers: Use addHandlers to map specific webhook topics to your application's logic.
2. Register webhooks: Use register to communicate with Shopify and ensure the configured topics are actually subscribed to in your store.
3. Process incoming requests: Use process to validate the authenticity of a webhook request received from Shopify and execute the associated handlers.
4. Inspect registry: Use getTopicsAdded to see which topics are currently in your local registry, or getHandlers to inspect the handlers configured for a specific topic.

When implementing OAuth, choose the flow based on your app type:

1. Token Exchange (Recommended for embedded apps):

   • Uses a user's session token to retrieve an [access token].
   • Faster and prevents flickering because it doesn't require redirects.
   • If using Shopify managed installation, Shopify automatically handles access scope changes.

2. Authorization Code Grant Flow (Suitable for non-embedded apps):

   • The app manages installations and access scope changes manually.
   • Requires creating two endpoints to handle redirects.

In current versions of the library, shopify.webhooks.process() expects the body content to be passed explicitly as a string via the rawBody parameter. It no longer reads the request body directly from the stream.

Express Configuration

If you use express.json() globally in your app, you must ensure that your webhook endpoint uses express.text({type: '*/*'}) middleware. This ensures req.body is a string, which is required for successful validation and processing:

await shopify.webhooks.process({
  rawBody: req.body, // must be a string
  rawRequest: req,
  rawResponse: res,
});

A Session object contains the authentication and identity data required to make API calls. When isOnline is true, the expires and onlineAccessInfo properties will be populated.

Because billing requires an active session, your app must be installed before it can request payment. You can use the check method to gate access to your app or specific endpoints.

Recommended check points:

1. After OAuth completes: Use the session returned from shopify.auth.callback to ensure billing is part of the authentication flow.
2. When validating frontend requests: Use shopify.session.getCurrentId to run checks on incoming requests.

Important: Merchants can cancel subscriptions after installation. It is highly recommended to use billing webhooks to revoke access when a merchant cancels or declines payment.