Admin API

Contains objects used to interact with the Admin API. This object is returned as part of different contexts, such as [`admin`](/docs/api/shopify-app-remix/authenticate/admin), [`unauthenticated.admin`](/docs/api/shopify-app-remix/unauthenticated/unauthenticated-admin), and [`webhook`](/docs/api/shopify-app-remix/authenticate/webhook).

admin

Provides utilities that apps can use to make requests to the Admin API.

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.

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

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

Examples

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;