Skip to main content

Admin
object

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.

Anchor to authenticate.admin
authenticate.admin(
request
)

Authenticates requests coming from the Shopify admin.

Note

The shape of the returned object changes depending on the distribution config. Merchant custom apps (AppDistribution.ShopifyAdmin) are not embedded so do not return session tokens or redirect functionality. All other distributions are embedded and so they return a context with session tokens and redirect functionality.

Anchor to authenticate.admin-parametersParameters

Anchor to request
request
Request
required

Anchor to authenticate.admin-returnsReturns

Promise<<Config>>
Was this section helpful?

Authenticate, run API mutation, and redirect

/app/routes/**.ts

import {type ActionFunctionArgs, data} from 'react-router';
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 data({errors: error.body?.errors}, {status: 500});
}

return new Response('Failed to update product title', {status: 500});
}
};

Anchor to examplesExamples

Anchor to example-corscors

Anchor to example-setting-cors-headers-for-a-admin-requestSetting CORS headers for a admin request

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

Was this section helpful?

Setting CORS headers for a admin request

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

import { LoaderFunctionArgs, json } from "react-router";
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(await getMyAppData({user: session.onlineAccessInfo!.id})));
};

Anchor to example-redirectredirect

Anchor to example-redirecting-to-an-app-routeRedirecting to an app route

Use the redirect helper to safely redirect between pages.

Anchor to example-redirecting-to-a-page-in-the-shopify-adminRedirecting to a page in the Shopify Admin

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.

Anchor to example-redirecting-outside-of-the-admin-embedded-app-pageRedirecting outside of the Admin embedded app page

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

Was this section helpful?

Redirecting to an app route

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

import { LoaderFunctionArgs, json } from "react-router";
import { authenticate } from "../shopify.server";

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

Anchor to example-sessionsession

Anchor to example-using-offline-sessionsUsing offline sessions

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

Anchor to example-using-online-sessionsUsing online sessions

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

Was this section helpful?

Using offline sessions

import { LoaderFunctionArgs, json } from "react-router";
import { authenticate } from "../shopify.server";
import { getMyAppData } from "~/db/model.server";

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

Anchor to example-sessiontokensessionToken

Anchor to example-using-the-decoded-session-tokenUsing the decoded session token

Get user-specific data using the sessionToken object.

Was this section helpful?

Using the decoded session token

import { LoaderFunctionArgs, json } from "react-router";
import { authenticate } from "../shopify.server";
import { getMyAppData } from "~/db/model.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
const { sessionToken } = await authenticate.admin(
request
);
return (await getMyAppData({user: sessionToken.sub}));
};

Anchor to example-graphqlgraphql

Anchor to example-querying-the-graphql-apiQuerying the GraphQL API

Use admin.graphql to make query / mutation requests.

Anchor to example-handling-graphql-errorsHandling GraphQL errors

Catch GraphqlQueryError errors to see error messages from the API.

Was this section helpful?

Querying the GraphQL API

import { ActionFunctionArgs } from "react-router";
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 ({
productId: productData.data?.productCreate?.product?.id,
});
}

Anchor to example-cancelcancel

Anchor to example-cancelling-a-subscriptionCancelling a subscription

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

Was this section helpful?

Cancelling a subscription

import { LoaderFunctionArgs } from "react-router";
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
};

Anchor to example-checkcheck

Anchor to example-check-what-billing-plans-a-merchant-is-subscribed-toCheck what billing plans a merchant is subscribed to

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.

Anchor to example-check-for-payments-without-filteringCheck for payments without filtering

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

Was this section helpful?

Check what billing plans a merchant is subscribed to

import { LoaderFunctionArgs } from "react-router";
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);
};

Anchor to example-createusagerecordcreateUsageRecord

Anchor to example-creating-a-usage-recordCreating a usage record

Create a usage record for the active usage billing plan

Was this section helpful?

Creating a usage record

import { ActionFunctionArgs } from "react-router";
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
};

Anchor to example-requestrequest

Anchor to example-using-a-custom-return-urlUsing a custom return URL

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

Anchor to example-overriding-plan-settingsOverriding plan settings

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.

Was this section helpful?

Using a custom return URL

import { LoaderFunctionArgs } from "react-router";
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
};

Anchor to example-requirerequire

Anchor to example-requesting-billing-right-awayRequesting billing right away

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

Anchor to example-redirect-to-a-plan-selection-pageRedirect to a plan selection page

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.

Was this section helpful?

Requesting billing right away

import { LoaderFunctionArgs } from "react-router";
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
};

Anchor to example-updateusagecappedamountupdateUsageCappedAmount

Anchor to example-updating-the-capped-amount-for-a-usage-billing-planUpdating the capped amount for a usage billing plan

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

Was this section helpful?

Updating the capped amount for a usage billing plan

import { ActionFunctionArgs } from "react-router";
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
};

Anchor to example-queryquery

Anchor to example-query-for-granted-scopesQuery for granted scopes

Call scopes.query to get scope details.

Was this section helpful?

Query for granted scopes

/app._index.tsx

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

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

const scopesDetail = await scopes.query();

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

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

...
}

Anchor to example-requestrequest

Anchor to example-request-consent-from-the-merchant-to-grant-the-provided-scopes-for-this-appRequest consent from the merchant to grant the provided scopes for this app

Call scopes.request to request optional scopes.

Was this section helpful?

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

/app/routes/app.request.tsx

import type { ActionFunctionArgs } from "react-router";
import { useFetcher } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

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

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

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

...
}

Anchor to example-revokerevoke

Anchor to example-revoke-optional-scopesRevoke optional scopes

Call scopes.revoke to revoke optional scopes.

Was this section helpful?

Revoke optional scopes

/app._index.tsx

import type { ActionFunctionArgs } from "react-router";
import { useFetcher } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

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

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

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

...
}

Anchor to relatedRelated

Interact with the Admin API.API context
Bill merchants for your app using the Admin API.Billing context