Admin

Examples

• Description

  Authenticate, run API mutation, and redirect

  /app/routes/**.ts

  import {type ActionFunctionArgs, json} from '@remix-run/node';
  import {GraphqlQueryError} from '@shopify/shopify-api';
  
  import {authenticate} from '../shopify.server';
  
  export const action = async ({request}: ActionFunctionArgs) => {
    const {admin, redirect} = await authenticate.admin(request);
  
    try {
      await admin.graphql(
        `#graphql
        mutation updateProductTitle($input: ProductInput!) {
          productUpdate(input: $input) {
            product {
              id
            }
          }
        }`,
        {
          variables: {
            input: {id: '123', title: 'New title'},
          },
        },
      );
  
      return redirect('/app/product-updated');
    } catch (error) {
      if (error instanceof GraphqlQueryError) {
        return json({errors: error.body?.errors}, {status: 500});
      }
  
      return new Response('Failed to update product title', {status: 500});
    }
  };

• Description

  Use the `cors` helper to ensure your app can respond to requests from admin extensions.

  /app/routes/admin/my-route.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  import { getMyAppData } from "~/db/model.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session, cors } = await authenticate.admin(request);
    return cors(json(await getMyAppData({user: session.onlineAccessInfo!.id})));
  };

• Description

  Use the `redirect` helper to safely redirect between pages.

  /app/routes/admin/my-route.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session, redirect } = await authenticate.admin(request);
    return redirect("/");
  };

• Description

  Redirects to a product page in the Shopify admin. Pass in a `target` option of `_top` or `_parent` to navigate in the current window, or `_blank` to open a new tab.

  /app/routes/admin/my-route.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session, redirect } = await authenticate.admin(request);
    return redirect("shopify://admin/products/123456", { target: '_parent' });
  };

• Description

  Pass in a `target` option of `_top` or `_parent` to navigate in the current window, or `_blank` to open a new tab.

  /app/routes/admin/my-route.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session, redirect } = await authenticate.admin(request);
    return redirect("/", { target: '_parent' });
  };

• Using offline sessions

  Description

  Get your app's shop-specific data using an offline session.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  import { getMyAppData } from "~/db/model.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session } = await authenticate.admin(request);
    return json(await getMyAppData({shop: session.shop));
  };

  shopify.server.ts

  import { shopifyApp } from "@shopify/shopify-app-remix/server";
  
  const shopify = shopifyApp({
    // ...etc
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Using online sessions

  Description

  Get your app's user-specific data using an online session.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  import { getMyAppData } from "~/db/model.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { session } = await authenticate.admin(request);
    return json(await getMyAppData({user: session.onlineAccessInfo!.id}));
  };

  shopify.server.ts

  import { shopifyApp } from "@shopify/shopify-app-remix/server";
  
  const shopify = shopifyApp({
    // ...etc
    useOnlineTokens: true,
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Using the decoded session token

  Description

  Get user-specific data using the `sessionToken` object.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs, json } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  import { getMyAppData } from "~/db/model.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { sessionToken } = await authenticate.admin(
      request
    );
    return json(await getMyAppData({user: sessionToken.sub}));
  };

  shopify.server.ts

  import { shopifyApp } from "@shopify/shopify-app-remix/server";
  
  const shopify = shopifyApp({
    // ...etc
    useOnlineTokens: true,
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Querying the GraphQL API

  Description

  Use `admin.graphql` to make query / mutation requests.

  /app/routes/**\/*.ts

  import { ActionFunctionArgs } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const action = async ({ request }: ActionFunctionArgs) => {
    const { admin } = await authenticate.admin(request);
  
    const response = await admin.graphql(
      `#graphql
      mutation populateProduct($input: ProductInput!) {
        productCreate(input: $input) {
          product {
            id
          }
        }
      }`,
      {
        variables: {
          input: { title: "Product Name" },
        },
      },
    );
  
    const productData = await response.json();
    return json({
      productId: productData.data?.productCreate?.product?.id,
    });
  }

  /app/shopify.server.ts

  import { shopifyApp } from "@shopify/shopify-app-remix/server";
  
  const shopify = shopifyApp({
    // ...
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Handling GraphQL errors

  Description

  Catch `GraphqlQueryError` errors to see error messages from the API.

  /app/routes/**\/*.ts

  import { ActionFunctionArgs } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const action = async ({ request }: ActionFunctionArgs) => {
    const { admin } = await authenticate.admin(request);
  
    try {
      const response = await admin.graphql(
        `#graphql
        query incorrectQuery {
          products(first: 10) {
            nodes {
              not_a_field
            }
          }
        }`,
      );
  
      return json({ data: await response.json() });
    } catch (error) {
      if (error instanceof GraphqlQueryError) {
        // error.body.errors:
        // { graphQLErrors: [
        //   { message: "Field 'not_a_field' doesn't exist on type 'Product'" }
        // ] }
        return json({ errors: error.body?.errors }, { status: 500 });
      }
      return json({ message: "An error occurred" }, { status: 500 });
    }
  }

  /app/shopify.server.ts

  import { shopifyApp } from "@shopify/shopify-app-remix/server";
  
  const shopify = shopifyApp({
    // ...
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Cancelling a subscription

  Description

  Use the `billing.cancel` function to cancel an active subscription with the id returned from `billing.require`.

  /app/routes/cancel-subscription.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    const billingCheck = await billing.require({
      plans: [MONTHLY_PLAN],
      onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
    });
  
    const subscription = billingCheck.appSubscriptions[0];
    const cancelledSubscription = await billing.cancel({
      subscriptionId: subscription.id,
      isTest: true,
      prorate: true,
     });
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  export const ANNUAL_PLAN = 'Annual subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
      [ANNUAL_PLAN]: {
        lineItems: [
          {
            amount: 50,
            currencyCode: 'USD',
            interval: BillingInterval.Annual,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Check what billing plans a merchant is subscribed to

  Description

  Use billing.check if you want to determine which plans are in use. Unlike `require`, `check` does notthrow an error if no active billing plans are present.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    const { hasActivePayment, appSubscriptions } = await billing.check({
      plans: [MONTHLY_PLAN],
      isTest: false,
    });
    console.log(hasActivePayment);
    console.log(appSubscriptions);
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  export const ANNUAL_PLAN = 'Annual subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
      [ANNUAL_PLAN]: {
        lineItems: [
          {
            amount: 50,
            currencyCode: 'USD',
            interval: BillingInterval.Annual,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Description

  Use billing.check to see if any payments exist for the store, regardless of whether it's a test ormatches one or more plans.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    const { hasActivePayment, appSubscriptions } = await billing.check();
    // This will be true if any payment is found
    console.log(hasActivePayment);
    console.log(appSubscriptions);
  };

• Creating a usage record

  Description

  Create a usage record for the active usage billing plan

  /app/routes/create-usage-record.ts

  import { ActionFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const action = async ({ request }: ActionFunctionArgs) => {
     const { billing } = await authenticate.admin(request);
  
    const chargeBilling = await billing.createUsageRecord({
       description: "Usage record for product creation",
       price: {
         amount: 1,
         currencyCode: "USD",
        },
       isTest: true,
     });
   console.log(chargeBilling);
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const USAGE_PLAN = 'Usage subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [USAGE_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Usage,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Using a custom return URL

  Description

  Change where the merchant is returned to after approving the purchase using the `returnUrl` option.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    await billing.require({
      plans: [MONTHLY_PLAN],
      onFailure: async () => billing.request({
        plan: MONTHLY_PLAN,
        isTest: true,
        returnUrl: 'https://admin.shopify.com/store/my-store/apps/my-app/billing-page',
      }),
    });
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  export const ANNUAL_PLAN = 'Annual subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
      [ANNUAL_PLAN]: {
        lineItems: [
          {
            amount: 50,
            currencyCode: 'USD',
            interval: BillingInterval.Annual,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Overriding plan settings

  Description

  Customize the plan for a merchant when requesting billing. Any fields from the plan can be overridden, as long as the billing interval for line items matches the config.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    await billing.require({
      plans: [MONTHLY_PLAN],
      onFailure: async () => billing.request({
        plan: MONTHLY_PLAN,
        isTest: true,
        trialDays: 14,
        lineItems: [
          {
            interval: BillingInterval.Every30Days,
            discount: { value: { percentage: 0.1 } },
          },
        ],
      }),
    });
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  export const ANNUAL_PLAN = 'Annual subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
      [ANNUAL_PLAN]: {
        lineItems: [
          {
            amount: 50,
            currencyCode: 'USD',
            interval: BillingInterval.Annual,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Requesting billing right away

  Description

  Call `billing.request` in the `onFailure` callback to immediately redirect to the Shopify page to request payment.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    await billing.require({
      plans: [MONTHLY_PLAN],
      isTest: true,
      onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
    });
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Redirect to a plan selection page

  Description

  When the app has multiple plans, create a page in your App that allows the merchant to select a plan. If a merchant does not have the required plan you can redirect them to page in your app to select one.

  /app/routes/**\/*.ts

  import { LoaderFunctionArgs, redirect } from "@remix-run/node";
  import { authenticate, MONTHLY_PLAN, ANNUAL_PLAN } from "../shopify.server";
  
  export const loader = async ({ request }: LoaderFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
    const billingCheck = await billing.require({
      plans: [MONTHLY_PLAN, ANNUAL_PLAN],
      isTest: true,
      onFailure: () => redirect('/select-plan'),
    });
  
    const subscription = billingCheck.appSubscriptions[0];
    console.log(`Shop is on ${subscription.name} (id ${subscription.id})`);
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const MONTHLY_PLAN = 'Monthly subscription';
  export const ANNUAL_PLAN = 'Annual subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [MONTHLY_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Every30Days,
          }
        ],
      },
      [ANNUAL_PLAN]: {
        lineItems: [
          {
            amount: 50,
            currencyCode: 'USD',
            interval: BillingInterval.Annual,
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Updating the capped amount for a usage billing plan

  Description

  Update the capped amount for the usage billing plan specified by `subscriptionLineItemId`.

  /app/routes/**\/*.ts

  import { ActionFunctionArgs } from "@remix-run/node";
  import { authenticate } from "../shopify.server";
  
  export const action = async ({ request }: ActionFunctionArgs) => {
    const { billing } = await authenticate.admin(request);
  
    await billing.updateUsageCappedAmount({
      subscriptionLineItemId: "gid://shopify/AppSubscriptionLineItem/12345?v=1&index=1",
      cappedAmount: {
        amount: 10,
        currencyCode: "USD"
      },
    });
  
    // App logic
  };

  shopify.server.ts

  import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/server";
  
  export const USAGE_PLAN = 'Usage subscription';
  
  const shopify = shopifyApp({
    // ...etc
    billing: {
      [USAGE_PLAN]: {
        lineItems: [
          {
            amount: 5,
            currencyCode: 'USD',
            interval: BillingInterval.Usage,
            terms: "Usage based"
          }
        ],
      },
    }
  });
  export default shopify;
  export const authenticate = shopify.authenticate;

• Description

  Call `scopes.query` to get scope details.

  /app._index.tsx

  import { authenticate } from "../shopify.server";
  import { json } from "@remix-run/node";
  
  export const loader = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { required, optional, granted } = await scopes.query();
  
    if (granted.includes("write_products")) {
      // do something
    }
  
    return null
  };

• Description

  Call `scopes.request` to request optional scopes.

  /app/routes/app.request.tsx

  import { authenticate } from "../shopify.server";
  
  // Example of an action to request optional scopes
  export const action = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { granted } = await scopes.query();
  
    if (!granted.includes("write_products")) {
      await scopes.request(["write_products"]);
    }
  
    return null
  };

• Description

  Call `scopes.revoke` to revoke optional scopes.

  /app._index.tsx

  import { authenticate } from "../shopify.server";
  import { json } from "@remix-run/node";
  
  // Example of an action to POST optional scopes to revoke
  export const action = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { granted } = await scopes.query();
  
    if (granted.includes("write_products")) {
      const revokedResponse = await scopes.revoke(["write_products"]);
      return json(revokedResponse);
    }
  
    return null
  };