Admin API

object

AdminApiContext

FeatureEnabled<ConfigArg['future'], 'removeRest'> extends true
    ? AdminApiContextWithoutRest
    : AdminApiContextWithRest<Resources>

FeatureEnabled

Future extends FutureFlags
  ? Future[Flag] extends true
    ? true
    : false
  : false

FutureFlags

• removeRest

  When enabled, methods for interacting with the admin REST API will not be returned. This affects: * `authenticate.admin(request)` * `authenticate.webhook(request)` * `authenticate.flow(request)` * `authenticate.appProxy(request)` * `authenticate.fulfillmentService(request)` * `unauthenticated.admin(shop)` In a future release we will remove REST from the package completely. Please see: [https://www.shopify.com/ca/partners/blog/all-in-on-graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql)

  boolean

• unstable_newEmbeddedAuthStrategy

  When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange). This assumes the app has scopes declared for [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation). Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).

  boolean

export interface FutureFlags {
  /**
   * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).
   * This assumes the app has scopes declared for [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
   *
   * Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).
   *
   * @default false
   */
  unstable_newEmbeddedAuthStrategy?: boolean;

  /**
   * When enabled, methods for interacting with the admin REST API will not be returned.
   *
   * This affects:
   *
   * * `authenticate.admin(request)`
   * * `authenticate.webhook(request)`
   * * `authenticate.flow(request)`
   * * `authenticate.appProxy(request)`
   * * `authenticate.fulfillmentService(request)`
   * * `unauthenticated.admin(shop)`
   *
   * In a future release we will remove REST from the package completely.
   *
   * Please see: [https://www.shopify.com/ca/partners/blog/all-in-on-graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql)
   *
   * @default false
   */
  removeRest?: boolean;
}

AdminApiContextWithoutRest

• graphql

  Methods for interacting with the Shopify Admin GraphQL API

  GraphQLClient<AdminOperations>

export interface AdminApiContextWithoutRest {
  /**
   * Methods for interacting with the Shopify Admin GraphQL API
   *
   * {@link https://shopify.dev/docs/api/admin-graphql}
   * {@link https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-api/docs/reference/clients/Graphql.md}
   *
   * @example
   * <caption>Querying the GraphQL API.</caption>
   * <description>Use `admin.graphql` to make query / mutation requests.</description>
   * ```ts
   * // /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,
   *   });
   * }
   * ```
   *
   * ```ts
   * // /app/shopify.server.ts
   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
   *
   * const shopify = shopifyApp({
   *   // ...
   * });
   * export default shopify;
   * export const authenticate = shopify.authenticate;
   * ```
   *
   * @example
   * <caption>Handling GraphQL errors.</caption>
   * <description>Catch `GraphqlQueryError` errors to see error messages from the API.</description>
   * ```ts
   * // /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 });
   *   }
   * }
   * ```
   *
   * ```ts
   * // /app/shopify.server.ts
   * import { shopifyApp } from "@shopify/shopify-app-remix/server";
   *
   * const shopify = shopifyApp({
   *   // ...
   * });
   * export default shopify;
   * export const authenticate = shopify.authenticate;
   * ```
   */
  graphql: GraphQLClient<AdminOperations>;
}

GraphQLClient

• query

  Operation extends keyof Operations

• options

  GraphQLQueryOptions<Operation, Operations>

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

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

GraphQLQueryOptions

• apiVersion

  The version of the API to use for the request.

  ApiVersion

• headers

  Additional headers to include in the request.

  Record<string, any>

• signal

  An optional AbortSignal to cancel the request.

  AbortSignal

• tries

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

  number

• variables

  The variables to pass to the operation.

  ApiClientRequestOptions<Operation, Operations>["variables"]

export interface GraphQLQueryOptions<
  Operation extends keyof Operations,
  Operations extends AllOperations,
> {
  /**
   * The variables to pass to the operation.
   */
  variables?: ApiClientRequestOptions<Operation, Operations>['variables'];
  /**
   * The version of the API to use for the request.
   */
  apiVersion?: ApiVersion;
  /**
   * Additional headers to include in the request.
   */
  headers?: Record<string, any>;
  /**
   * The total number of times to try the request if it fails.
   */
  tries?: number;

  /**
   * An optional AbortSignal to cancel the request.
   */
  signal?: AbortSignal;
}

AdminApiContextWithRest

• graphql

  Methods for interacting with the Shopify Admin GraphQL API

  GraphQLClient<AdminOperations>

• rest

  Methods for interacting with the Shopify Admin REST API

  RestClientWithResources<Resources>

export interface AdminApiContextWithRest<
  Resources extends ShopifyRestResources = ShopifyRestResources,
> extends AdminApiContextWithoutRest {
  /**
   * Methods for interacting with the Shopify Admin REST API
   *
   * @deprecated In a future major release REST will be removed from this package. Please see [all-in on graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql).
   *
   * 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.
   *
   * {@link https://shopify.dev/docs/api/admin-rest}
   *
   * @example
   * <caption>Using REST resources.</caption>
   * <description>Getting the number of orders in a store using REST resources. Visit the [Admin REST API references](/docs/api/admin-rest) for examples on using each resource. </description>
   *
   * ```ts
   * // /app/routes/**\/*.ts
   * 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 }),
   *   );
   * };
   * ```
   *
   * ```ts
   * // /app/shopify.server.ts
   * 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;
   * ```
   *
   * @example
   * <caption>Performing a GET request to the REST API.</caption>
   * <description>Use `admin.rest.get` to make custom requests to make a request to to the `customer/count` endpoint</description>
   *
   * ```ts
   * // /app/routes/**\/*.ts
   * 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 });
   * };
   * ```
   *
   * ```ts
   * // /app/shopify.server.ts
   * 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;
   * ```
   *
   * @example
   * <caption>Performing a POST request to the REST API.</caption>
   * <description>Use `admin.rest.post` to make custom requests to make a request to to the `customers.json` endpoint to send a welcome email</description>
   * ```ts
   * // /app/routes/**\/*.ts
   * 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 });
   * };
   * ```
   *
   * ```ts
   * // /app/shopify.server.ts
   * 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;
   * ```
   */
  rest: RestClientWithResources<Resources>;
}

RestClientWithResources

RemixRestClient & {resources: Resources}

RemixRestClient

• session

  Session

• get

  Performs a GET request on the given path.

  (params: GetRequestParams) => Promise<Response>

• post

  Performs a POST request on the given path.

  (params: PostRequestParams) => Promise<Response>

• put

  Performs a PUT request on the given path.

  (params: PostRequestParams) => Promise<Response>

• delete

  Performs a DELETE request on the given path.

  (params: GetRequestParams) => Promise<Response>

class RemixRestClient {
  public session: Session;
  private params: AdminClientOptions['params'];
  private handleClientError: AdminClientOptions['handleClientError'];

  constructor({params, session, handleClientError}: AdminClientOptions) {
    this.params = params;
    this.handleClientError = handleClientError;
    this.session = session;
  }

  /**
   * Performs a GET request on the given path.
   *
   * @deprecated In a future major release REST will be removed from this package. Please see [all-in on graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql).
   */
  public async get(params: GetRequestParams) {
    return this.makeRequest({
      method: 'GET' as RequestParams['method'],
      ...params,
    });
  }

  /**
   * Performs a POST request on the given path.
   *
   * @deprecated In a future major release REST will be removed from this package. Please see [all-in on graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql).
   */
  public async post(params: PostRequestParams) {
    return this.makeRequest({
      method: 'POST' as RequestParams['method'],
      ...params,
    });
  }

  /**
   * Performs a PUT request on the given path.
   *
   * @deprecated In a future major release REST will be removed from this package. Please see [all-in on graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql).
   */
  public async put(params: PutRequestParams) {
    return this.makeRequest({
      method: 'PUT' as RequestParams['method'],
      ...params,
    });
  }

  /**
   * Performs a DELETE request on the given path.
   *
   * @deprecated In a future major release REST will be removed from this package. Please see [all-in on graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql).
   */
  public async delete(params: DeleteRequestParams) {
    return this.makeRequest({
      method: 'DELETE' as RequestParams['method'],
      ...params,
    });
  }

  protected async makeRequest(params: RequestParams): Promise<Response> {
    const originalClient = new this.params.api.clients.Rest({
      session: this.session,
    });
    const originalRequest = Reflect.get(originalClient, 'request');

    try {
      const apiResponse = await originalRequest.call(originalClient, params);

      // We use a separate client for REST requests and REST resources because we want to override the API library
      // client class to return a Response object instead.
      return new Response(JSON.stringify(apiResponse.body), {
        headers: apiResponse.headers,
      });
    } catch (error) {
      if (this.handleClientError) {
        throw await this.handleClientError({
          error,
          session: this.session,
          params: this.params,
        });
      } else throw new Error(error);
    }
  }
}