Admin

Contains functions 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

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

NonEmbeddedAdminContext

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.

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

Stores App information from logged in merchants so they can make authenticated requests to the Admin API.

id

The unique identifier for the session.

shop

The Shopify shop domain, such as `example.myshopify.com`.

state

The state of the session. Used for the OAuth authentication code flow.

isOnline

Whether the access token in the session is online or offline.

scope

The desired scopes for the access token, at the time the session was created.

expires

The date the access token expires.

accessToken

The access token for the session.

onlineAccessInfo

Information on the user for the session. Only present for online sessions.

isActive

Whether the session is active. Active sessions have an access token that is not expired, and has the given scopes.

isScopeChanged

Whether the access token has the given scopes.

isExpired

Whether the access token is expired.

toObject

Converts an object with data into a Session.

equals

Checks whether the given session is equal to this session.

toPropertyArray

Converts the session into an array of key-value pairs.

OnlineAccessInfo

expires_in

How long the access token is valid for, in seconds.

associated_user_scope

The effective set of scopes for the session.

associated_user

The user associated with the access token.

OnlineAccessUser

id

The user's ID.

first_name

The user's first name.

last_name

The user's last name.

email

The user's email address.

email_verified

Whether the user has verified their email address.

account_owner

Whether the user is the account owner.

locale

The user's locale.

collaborator

Whether the user is a collaborator.

AuthScopes

A class that represents a set of access token scopes.

has

Checks whether the current set of scopes includes the given one.

equals

Checks whether the current set of scopes equals the given one.

toString

Returns a comma-separated string with the current set of scopes.

toArray

Returns an array with the current set of scopes.

SessionParams

[key: string]

id

The unique identifier for the session.

shop

The Shopify shop domain.

state

The state of the session. Used for the OAuth authentication code flow.

isOnline

Whether the access token in the session is online or offline.

scope

The scopes for the access token.

expires

The date the access token expires.

accessToken

The access token for the session.

onlineAccessInfo

Information on the user for the session. Only present for online sessions.

StoredOnlineAccessInfo

Omit<OnlineAccessInfo, 'associated_user'> & { associated_user: Partial<OnlineAccessUser>; }

AdminApiContext

rest

Methods for interacting with the Shopify Admin REST API There are methods for interacting with individual REST resources. You can also make `GET`, `POST`, `PUT` and `DELETE` requests should the REST resources not meet your needs.

graphql

Methods for interacting with the Shopify Admin GraphQL API

RestClientWithResources

RemixRestClient & {resources: Resources}

RemixRestClient

session

get

Performs a GET request on the given path.

post

Performs a POST request on the given path.

put

Performs a PUT request on the given path.

delete

Performs a DELETE request on the given path.

GetRequestParams

path

The path to the resource, relative to the API version root.

type

The type of data expected in the response.

data

The request body.

query

Query parameters to be sent with the request.

extraHeaders

Additional headers to be sent with the request.

tries

The maximum number of times the request can be made if it fails with a throttling or server error.

DataType

JSON

GraphQL

URLEncoded

HeaderParams

Headers to be sent with the request.

Record<string, string | number | string[]>

PostRequestParams

GetRequestParams & { data: Record<string, any> | string; }

GraphQLClient

Returns: interface Promise<T> { /** * Attaches callbacks for the resolution and/or rejection of the Promise. * @param onfulfilled The callback to execute when the Promise is resolved. * @param onrejected The callback to execute when the Promise is rejected. * @returns A Promise for the completion of which ever callback is executed. */ then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>; /** * Attaches a callback for only the rejection of the Promise. * @param onrejected The callback to execute when the Promise is rejected. * @returns A Promise for the completion of the callback. */ catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>; }, interface Promise<T> {}, Promise: PromiseConstructor, interface Promise<T> { readonly [Symbol.toStringTag]: string; }, interface Promise<T> { /** * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The * resolved value cannot be modified from the callback. * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected). * @returns A Promise for the completion of the callback. */ finally(onfinally?: (() => void) | undefined | null): Promise<T>; }

Params:

query: Operation extends keyof Operations

options: GraphQLQueryOptions<Operation, Operations>

export type GraphQLClient<Operations extends AllOperations> = < Operation extends keyof Operations, >( query: Operation, options?: GraphQLQueryOptions<Operation, Operations>, ) => Promise<GraphQLResponse<Operation, Operations>>;

GraphQLQueryOptions

variables

The variables to pass to the operation.

apiVersion

The version of the API to use for the request.

headers

Additional headers to include in the request.

tries

The total number of times to try the request if it fails.

ApiVersion

October22

January23

April23

July23

October23

January24

April24

Unstable

BillingContext

require

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

check

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

request

Requests payment for the plan.

cancel

Cancels an ongoing subscription, given its ID.

RequireBillingOptions

plans

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

onFailure

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

isTest

Whether to consider test purchases.

BillingCheckResponseObject

hasActivePayment

Whether the user has an active payment method.

oneTimePurchases

The one-time purchases the shop has.

appSubscriptions

The active subscriptions the shop has.

OneTimePurchase

id

The ID of the one-time purchase.

name

The name of the purchased plan.

test

Whether this is a test purchase.

status

The status of the one-time purchase.

AppSubscription

id

The ID of the app subscription.

name

The name of the purchased plan.

test

Whether this is a test subscription.

lineItems

ActiveSubscriptionLineItem

id

plan

AppPlan

pricingDetails

RecurringAppPlan

interval

price

discount

BillingInterval

OneTime

Every30Days

Annual

Usage

Money

amount

currencyCode

AppPlanDiscount

durationLimitInIntervals

remainingDurationInIntervals

priceAfterDiscount

value

AppPlanDiscountAmount

BillingConfigSubscriptionPlanDiscountAmount | BillingConfigSubscriptionPlanDiscountPercentage

BillingConfigSubscriptionPlanDiscountAmount

amount

The amount to discount. Cannot be set if `percentage` is set.

percentage

The percentage to discount. Cannot be set if `amount` is set.

BillingConfigSubscriptionPlanDiscountPercentage

amount

The amount to discount. Cannot be set if `percentage` is set.

percentage

The percentage to discount. Cannot be set if `amount` is set.

UsageAppPlan

balanceUsed

cappedAmount

terms

CheckBillingOptions

plans

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

isTest

Whether to consider test purchases.

RequestBillingOptions

plan

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

isTest

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

returnUrl

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

CancelBillingOptions

subscriptionId

The ID of the subscription to cancel.

prorate

Whether to prorate the cancellation.

isTest

EnsureCORSFunction

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

EmbeddedAdminContext

sessionToken

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

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.

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.

JwtPayload

iss

The shop's admin domain.

dest

The shop's domain.

aud

The client ID of the receiving app.

sub

The User that the session token is intended for.

exp

When the session token expires.

nbf

When the session token activates.

iat

When the session token was issued.

jti

A secure random UUID.

sid

A unique session ID per user and app.

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'

Examples

Contains functions 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.

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;

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 Shopify admin

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;

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

rest

Using REST resources

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

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

  return json(
    admin.rest.resources.Order.count({ session }),
  );
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";
import { restResources } from "@shopify/shopify-api/rest/admin/2023-07";

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

Performing a GET request to the REST API

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

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

  const response = await admin.rest.get({
    path: "/customers/count.json",
  });
  const customers = await response.json();

  return json({ customers });
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";
import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";

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

Performing a POST request to the REST API

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

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

  const response = admin.rest.post({
    path: "customers/7392136888625/send_invite.json",
    body: {
      customer_invite: {
        to: "new_test_email@shopify.com",
        from: "j.limited@example.com",
        bcc: ["j.limited@example.com"],
        subject: "Welcome to my new shop",
        custom_message: "My awesome new store",
      },
    },
  });

  const customerInvite = await response.json();
  return json({ customerInvite });
};

import { shopifyApp } from "@shopify/shopify-app-remix/server";
import { restResources } from "@shopify/shopify-api/rest/admin/2023-04";

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

graphql

Querying the GraphQL API

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

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

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

Handling GraphQL errors

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

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

const shopify = shopifyApp({
  // ...
});
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';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      amount: 5,
      currencyCode: 'USD',
      interval: BillingInterval.Every30Days,
    },
    [ANNUAL_PLAN]: {
      amount: 50,
      currencyCode: 'USD',
      interval: BillingInterval.Annual,
    },
  }
});
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]: {
      amount: 5,
      currencyCode: 'USD',
      interval: BillingInterval.Every30Days,
    },
    [ANNUAL_PLAN]: {
      amount: 50,
      currencyCode: 'USD',
      interval: BillingInterval.Annual,
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Requesting billing with line items

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';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
       {
         amount: 5,
         currencyCode: 'USD',
         interval: BillingInterval.Every30Days,
        },
        {
         amount: 1,
         currencyCode: 'USD',
         interval: BillingInterval.Usage.
         terms: '1 dollar per 1000 emails',
        },
      ],
    },
  }
 future: {v3_lineItemBilling: true}
});
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]: {
      amount: 5,
      currencyCode: 'USD',
      interval: BillingInterval.Every30Days,
    },
    [ANNUAL_PLAN]: {
      amount: 50,
      currencyCode: 'USD',
      interval: BillingInterval.Annual,
    },
  }
});
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]: {
      amount: 5,
      currencyCode: 'USD',
      interval: BillingInterval.Every30Days,
    },
    [ANNUAL_PLAN]: {
      amount: 50,
      currencyCode: 'USD',
      interval: BillingInterval.Annual,
    },
  }
});
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]: {
      amount: 5,
      currencyCode: 'USD',
      interval: BillingInterval.Every30Days,
    },
    [ANNUAL_PLAN]: {
      amount: 50,
      currencyCode: 'USD',
      interval: BillingInterval.Annual,
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;