Admin

Contains methods for authenticating and interacting with the Admin API. This function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.

Authenticate, run API mutation, and redirect

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});
  }
};

authenticate.admin

Authenticates requests coming from the Shopify admin. The shape of the returned object changes depending on the `isEmbeddedApp` config.

AuthenticateAdmin

Returns: Promise<AdminContext<Config, Resources>>

Params:

request: Request

export type AuthenticateAdmin< Config extends AppConfigArg, Resources extends ShopifyRestResources = ShopifyRestResources, > = (request: Request) => Promise<AdminContext<Config, Resources>>;

AdminContext

EmbeddedTypedAdminContext<Config, Resources> & ScopesContext

EmbeddedTypedAdminContext

Config['isEmbeddedApp'] extends false ? NonEmbeddedAdminContext<Config, Resources> : EmbeddedAdminContext<Config, Resources>

NonEmbeddedAdminContext

admin

Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.

billing

Billing methods for this store, based on the plans defined in the `billing` config option.

cors

A function that ensures the CORS headers are set correctly for the response.

session

The session for the user who made the request. This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice. Use this to get shop or user-specific data.

BillingContext

cancel

Cancels an ongoing subscription, given its ID.

check

Checks if the shop has an active payment for any plan defined in the `billing` config option.

createUsageRecord

Creates a usage record for an app subscription.

request

Requests payment for the plan.

require

Checks if the shop has an active payment for any plan defined in the `billing` config option.

updateUsageCappedAmount

Updates the capped amount for a usage billing plan.

CancelBillingOptions

isTest

Whether to use the test mode. This prevents the credit card from being charged.

prorate

Whether to issue prorated credits for the unused portion of the app subscription. There will be a corresponding deduction (based on revenue share) to your Partner account. For example, if a $10.00 app subscription (with 0% revenue share) is cancelled and prorated half way through the billing cycle, then the merchant will be credited $5.00 and that amount will be deducted from your Partner account.

subscriptionId

The ID of the subscription to cancel.

CheckBillingOptions

isTest

Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged.

plans

The plans to check for. Must be one of the values defined in the `billing` config option.

CreateUsageRecordOptions

description

The description of the app usage record.

idempotencyKey

isTest

Whether to use the test mode. This prevents the credit card from being charged.

price

The price of the app usage record.

subscriptionLineItemId

RequestBillingOptions

isTest

Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.

plan

The plan to request. Must be one of the values defined in the `billing` config option.

returnUrl

The URL to return to after the merchant approves the payment.

RequireBillingOptions

isTest

Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged.

onFailure

How to handle the request if the shop doesn't have an active payment for any plan.

plans

The plans to check for. Must be one of the values defined in the `billing` config option.

UpdateUsageCappedAmountOptions

cappedAmount

The maximum charge for the usage billing plan.

subscriptionLineItemId

The subscription line item ID to update.

EnsureCORSFunction

export interface EnsureCORSFunction { (response: Response): Response; }

EmbeddedAdminContext

admin

Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.

billing

Billing methods for this store, based on the plans defined in the `billing` config option.

cors

A function that ensures the CORS headers are set correctly for the response.

redirect

A function that redirects the user to a new page, ensuring that the appropriate parameters are set for embedded apps. Returned only if `isEmbeddedApp` is `true`.

session

The session for the user who made the request. This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice. Use this to get shop or user-specific data.

sessionToken

The decoded and validated session token for the request. Returned only if `isEmbeddedApp` is `true`.

RedirectFunction

Returns: TypedResponse<never>

Params:

url: string

init: RedirectInit

export type RedirectFunction = ( url: string, init?: RedirectInit, ) => TypedResponse<never>;

RedirectInit

number | (ResponseInit & {target?: RedirectTarget})

RedirectTarget

'_self' | '_parent' | '_top' | '_blank'

ScopesContext

scopes

Methods to manage scopes for the store that made the request.

ScopesApiContext

The Scopes API enables embedded apps and extensions to request merchant consent for access scopes.

query

Queries Shopify for the scopes for this app on this shop

request

Requests the merchant to grant the provided scopes for this app on this shop Warning: This method performs a server-side redirect.

revoke

Revokes the provided scopes from this app on this shop Warning: This method throws an [error](https://shopify.dev/docs/api/admin-graphql/unstable/objects/AppRevokeAccessScopesAppRevokeScopeError) if the provided optional scopes contains a required scope.

ScopesDetail

granted

The scopes that have been granted on the shop for this app

optional

The optional scopes that the app has declared in its configuration

required

The required scopes that the app has declared in its configuration

ScopesRevokeResponse

revoked

The scopes that have been revoked on the shop for this app

Examples

Contains methods for authenticating and interacting with the Admin API. This function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.

cors

Setting CORS headers for a admin request

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})));
};

redirect

Redirecting to an app route

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("/");
};

Redirecting outside of the Admin embedded app page

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' });
};

session

Using offline sessions

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));
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";

const shopify = shopifyApp({
  // ...etc
});
export default shopify;
export const authenticate = shopify.authenticate;

Using online sessions

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}));
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";

const shopify = shopifyApp({
  // ...etc
  useOnlineTokens: true,
});
export default shopify;
export const authenticate = shopify.authenticate;

sessionToken

Using the decoded session token

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}));
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";

const shopify = shopifyApp({
  // ...etc
  useOnlineTokens: true,
});
export default shopify;
export const authenticate = shopify.authenticate;

cancel

Cancelling a subscription

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
};

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

Check what billing plans a merchant is subscribed to

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);
};

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 for payments without filtering

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);
};

createUsageRecord

Creating a usage record

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
};

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;

request

Using a custom return URL

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
};

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

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
};

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;

require

Requesting billing right away

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
};

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

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
};

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;

updateUsageCappedAmount

Updating the capped amount for a usage billing plan

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
};

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;

query

Query for granted scopes

import type { LoaderFunctionArgs } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import { authenticate } from "../shopify.server";
import { json } from "@remix-run/node";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { scopes } = await authenticate.admin(request);

  const scopesDetail =  await scopes.query();

  return json({
    hasWriteProducts: scopesDetail.granted.includes('write_products'),
  });
};

export default function Index() {
  const {hasWriteProducts} = useLoaderData<typeof loader>();

  ...
}

request

Request consent from the merchant to grant the provided scopes for this app

import type { ActionFunctionArgs } from "@remix-run/node";
import { useFetcher } from "@remix-run/react";
import { authenticate } from "../shopify.server";
import { json } from "@remix-run/node";

// Example of an action to POST a request to for optional scopes
export const action = async ({ request }: ActionFunctionArgs) => {
  const { scopes } = await authenticate.admin(request);

  const body = await request.formData();
  const scopesToRequest = body.getAll("scopes") as string[];

  // If the scopes are not already granted, a full page redirect to the request URL occurs
  await scopes.request(scopesToRequest);
  // otherwise return an empty response
  return json({});
};

export default function Index() {
  const fetcher = useFetcher<typeof action>();

  const handleRequest = () => {
    fetcher.submit({scopes: ["write_products"]}, {
      method: "POST",
    });
  };

  ...
}

revoke

Revoke optional scopes

import type { ActionFunctionArgs } from "@remix-run/node";
import { useFetcher } from "@remix-run/react";
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 }: ActionFunctionArgs) => {
  const { scopes } = await authenticate.admin(request);

  const body = await request.formData();
  const scopesToRevoke = body.getAll("scopes") as string[];

  const revokedResponse = await scopes.revoke(scopesToRevoke);

  return json(revokedResponse);
};

export default function Index() {
  const fetcher = useFetcher<typeof action>();

  const handleRevoke = () => {
    fetcher.submit({scopes: ["write_products"]}, {
      method: "POST",
    });
  };

  ...
}

Admin

Authenticate, run API mutation, and redirect

authenticate.admin

AuthenticateAdmin

Returns: Promise<AdminContext<Config, Resources>>

Params:

AdminContext

EmbeddedTypedAdminContext

NonEmbeddedAdminContext

admin

billing

cors

session

BillingContext

cancel

check

createUsageRecord

request

require

updateUsageCappedAmount

CancelBillingOptions

isTest

prorate

subscriptionId

CheckBillingOptions

isTest

plans

CreateUsageRecordOptions

description

idempotencyKey

isTest

price

subscriptionLineItemId

RequestBillingOptions

isTest

plan

returnUrl

RequireBillingOptions

isTest

onFailure

plans

UpdateUsageCappedAmountOptions

cappedAmount

subscriptionLineItemId

EnsureCORSFunction

EmbeddedAdminContext

admin

billing

cors

redirect

session

sessionToken

RedirectFunction

Returns: TypedResponse<never>

Params:

RedirectInit

RedirectTarget

ScopesContext

scopes

ScopesApiContext

query

request

revoke

ScopesDetail

granted

optional

required

ScopesRevokeResponse

revoked

Related

Examples

cors

Setting CORS headers for a admin request

redirect

Redirecting to an app route

Redirecting outside of the Admin embedded app page

session

Using offline sessions

Using online sessions

sessionToken