--- title: shopifyApp description: >- Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests. api_version: v1 latest api_name: shopify-app-react-router source_url: html: >- https://shopify.dev/docs/api/shopify-app-react-router/latest/entrypoints/shopifyapp md: >- https://shopify.dev/docs/api/shopify-app-react-router/latest/entrypoints/shopifyapp.md --- # shopifyApp Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests. The shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included. ## shopify​App(**[appConfig](#shopifyapp-propertydetail-appconfig)**​) Creates an object your app will use to interact with Shopify. ### Parameters * **appConfig** **Readonly\** **required** Configuration options for your Shopify app, such as the scopes your app needs. ### Returns * **ShopifyApp\>** `ShopifyApp` An object constructed using your appConfig. It has methods for interacting with Shopify. ### ShopifyApp An object your app can use to interact with Shopify. By default, the app's distribution is \`AppStore\`. ```ts Config['distribution'] extends AppDistribution.ShopifyAdmin ? AdminApp : Config['distribution'] extends AppDistribution.SingleMerchant ? EnforceSessionStorage> : Config['distribution'] extends AppDistribution.AppStore ? EnforceSessionStorage> : EnforceSessionStorage> ``` ### AppDistribution * AppStore ```ts app_store ``` * SingleMerchant ```ts single_merchant ``` * ShopifyAdmin ```ts shopify_admin ``` ### AdminApp * addDocumentResponseHeaders Adds the required Content Security Policy headers for Shopify apps to the given Headers object. ```ts AddDocumentResponseHeaders ``` * authenticate Ways to authenticate requests from different surfaces across Shopify. ```ts Authenticate ``` * registerWebhooks Register shop-specific webhook subscriptions using the Admin GraphQL API. In many cases defining app-specific webhooks in the \`shopify.app.toml\` will be sufficient and easier to manage. Please see: You should only use this if you need shop-specific webhooks. ```ts RegisterWebhooks ``` * sessionStorage The \`SessionStorage\` instance you passed in as a config option. ```ts SessionStorageType ``` * unauthenticated Ways to get Contexts from requests that do not originate from Shopify. ```ts Unauthenticated ``` ### AddDocumentResponseHeaders * request ```ts Request ``` * headers ```ts Headers ``` returns ```ts void ``` ### Authenticate * admin Authenticate an admin Request and get back an authenticated admin context. Use the authenticated admin context to interact with Shopify. Examples of when to use this are requests from your app's UI, or requests from admin extensions. If there is no session for the Request, this will redirect the merchant to correct auth flows. ```ts AuthenticateAdmin ``` * flow Authenticate a Flow extension Request and get back an authenticated context, containing an admin context to access the API, and the payload of the request. If there is no session for the Request, this will return an HTTP 400 error. Note that this will always be a POST request. ```ts AuthenticateFlow ``` * fulfillmentService Authenticate a request from a fulfillment service and get back an authenticated context. ```ts AuthenticateFulfillmentService ``` * pos Authenticate a request from a POS UI extension ```ts AuthenticatePOS ``` * public Authenticate a public request and get back a session token. ```ts AuthenticatePublic ``` * webhook Authenticate a Shopify webhook request, get back an authenticated admin context and details on the webhook request ```ts AuthenticateWebhook ``` ### AuthenticateAdmin 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. * request ```ts Request ``` returns ```ts Promise> ``` ### AdminContext ```ts EmbeddedTypedAdminContext & ScopesContext ``` ### EmbeddedTypedAdminContext ```ts Config['distribution'] extends AppDistribution.ShopifyAdmin ? NonEmbeddedAdminContext : EmbeddedAdminContext ``` ### NonEmbeddedAdminContext * admin Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request. ```ts AdminApiContext ``` * billing Billing methods for this store, based on the plans defined in the \`billing\` config option. ```ts BillingContext ``` * cors A function that ensures the CORS headers are set correctly for the response. ```ts EnsureCORSFunction ``` * 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. ```ts Session ``` ### AdminApiContext Provides utilities that apps can use to make requests to the Admin API. * graphql Methods for interacting with the Shopify Admin GraphQL API ```ts GraphQLClient ``` ### GraphQLClient * query ```ts Operation extends keyof Operations ``` * options ```ts GraphQLQueryOptions ``` returns ```ts interface Promise { /** * 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(onfulfilled?: ((value: T) => TResult1 | PromiseLike) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike) | undefined | null): Promise; /** * 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(onrejected?: ((reason: any) => TResult | PromiseLike) | undefined | null): Promise; }, interface Promise {}, Promise: PromiseConstructor, interface Promise { readonly [Symbol.toStringTag]: string; }, interface Promise { /** * 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; } ``` ### GraphQLQueryOptions * apiVersion The version of the API to use for the request. ```ts ApiVersion ``` * headers Additional headers to include in the request. ```ts Record ``` * signal An optional AbortSignal to cancel the request. ```ts AbortSignal ``` * tries The total number of times to try the request if it fails. ```ts number ``` * variables The variables to pass to the operation. ```ts ApiClientRequestOptions ``` ### ApiVersion * October24 ```ts 2024-10 ``` * January25 ```ts 2025-01 ``` * April25 ```ts 2025-04 ``` * July25 ```ts 2025-07 ``` * October25 ```ts 2025-10 ``` * January26 ```ts 2026-01 ``` * April26 ```ts 2026-04 ``` * Unstable ```ts unstable ``` ### BillingContext Provides utilities that apps can use to request billing for the app using the Admin API. * cancel Cancels an ongoing subscription, given its ID. ```ts (options: CancelBillingOptions) => Promise ``` * check Checks if the shop has an active payment for any plan defined in the \`billing\` config option. ```ts >(options?: Options) => Promise ``` * createUsageRecord Creates a usage record for an app subscription. ```ts (options: CreateUsageRecordOptions) => Promise ``` * request Requests payment for the plan. ```ts (options: RequestBillingOptions) => Promise ``` * require Checks if the shop has an active payment for any plan defined in the \`billing\` config option. ```ts (options: RequireBillingOptions) => Promise ``` * updateUsageCappedAmount Updates the capped amount for a usage billing plan. ```ts (options: UpdateUsageCappedAmountOptions) => Promise ``` ### CancelBillingOptions * isTest Whether to use the test mode. This prevents the credit card from being charged. ```ts boolean ``` * 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. ```ts boolean ``` * subscriptionId The ID of the subscription to cancel. ```ts string ``` ### Options * layout Whether to use the shop's theme layout around the Liquid content. ```ts boolean ``` ### CheckBillingOptions * isTest Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged. ```ts boolean ``` * plans The plans to check for. Must be one of the values defined in the \`billing\` config option. ```ts (keyof Config["billing"])[] ``` ### CreateUsageRecordOptions * description The description of the app usage record. ```ts string ``` * idempotencyKey ```ts string ``` * isTest Whether to use the test mode. This prevents the credit card from being charged. ```ts boolean ``` * price The price of the app usage record. ```ts { amount: number; currencyCode: string; } ``` * subscriptionLineItemId ```ts string ``` ### RequestBillingOptions * amount Amount to charge for this plan. ```ts number ``` * currencyCode Currency code for this plan. ```ts string ``` * interval Interval for this plan. Must be set to \`OneTime\`. ```ts BillingInterval.OneTime ``` * isTest Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged. ```ts boolean ``` * lineItems The line items for this plan. ```ts ({ interval?: BillingInterval.Every30Days | BillingInterval.Annual; discount?: { durationLimitInIntervals?: number; value?: { amount?: number; percentage?: never; } | { amount?: never; percentage?: number; }; }; amount?: number; currencyCode?: string; } | { interval?: BillingInterval.Usage; amount?: number; terms?: string; currencyCode?: string; })[] ``` * plan The plan to request. Must be one of the values defined in the \`billing\` config option. ```ts keyof Config["billing"] ``` * replacementBehavior The replacement behavior to use for this plan. ```ts BillingReplacementBehavior ``` * returnUrl The URL to return to after the merchant approves the payment. ```ts string ``` * trialDays How many trial days to give before charging for this plan. ```ts number ``` ### RequireBillingOptions * isTest Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged. ```ts boolean ``` * onFailure How to handle the request if the shop doesn't have an active payment for any plan. ```ts (error: any) => Promise ``` * plans The plans to check for. Must be one of the values defined in the \`billing\` config option. ```ts (keyof Config["billing"])[] ``` ### UpdateUsageCappedAmountOptions * cappedAmount The maximum charge for the usage billing plan. ```ts { amount: number; currencyCode: string; } ``` * subscriptionLineItemId The subscription line item ID to update. ```ts string ``` ### EnsureCORSFunction ### 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. ```ts string ``` * shop The Shopify shop domain, such as \`example.myshopify.com\`. ```ts string ``` * state The state of the session. Used for the OAuth authentication code flow. ```ts string ``` * isOnline Whether the access token in the session is online or offline. ```ts boolean ``` * scope The desired scopes for the access token, at the time the session was created. ```ts string ``` * expires The date the access token expires. ```ts Date ``` * accessToken The access token for the session. ```ts string ``` * refreshToken The refresh token for the session. ```ts string ``` * refreshTokenExpires The date the refresh token expires. ```ts Date ``` * onlineAccessInfo Information on the user for the session. Only present for online sessions. ```ts OnlineAccessInfo ``` * isActive Whether the session is active. Active sessions have an access token that is not expired, and has has the given scopes if scopes is equal to a truthy value. ```ts (scopes: string | string[] | AuthScopes, withinMillisecondsOfExpiry?: number) => boolean ``` * isScopeChanged Whether the access token includes the given scopes if they are provided. ```ts (scopes: string | string[] | AuthScopes) => boolean ``` * isScopeIncluded Whether the access token includes the given scopes. ```ts (scopes: string | string[] | AuthScopes) => boolean ``` * isExpired Whether the access token is expired. ```ts (withinMillisecondsOfExpiry?: number) => boolean ``` * toObject Converts an object with data into a Session. ```ts () => SessionParams ``` * equals Checks whether the given session is equal to this session. ```ts (other: Session) => boolean ``` * toPropertyArray Converts the session into an array of key-value pairs. ```ts (returnUserData?: boolean) => [string, string | number | boolean][] ``` ### OnlineAccessInfo * associated\_user The user associated with the access token. ```ts OnlineAccessUser ``` * associated\_user\_scope The effective set of scopes for the session. ```ts string ``` * expires\_in How long the access token is valid for, in seconds. ```ts number ``` ### OnlineAccessUser * account\_owner Whether the user is the account owner. ```ts boolean ``` * collaborator Whether the user is a collaborator. ```ts boolean ``` * email The user's email address. ```ts string ``` * email\_verified Whether the user has verified their email address. ```ts boolean ``` * first\_name The user's first name. ```ts string ``` * id The user's ID. ```ts number ``` * last\_name The user's last name. ```ts string ``` * locale The user's locale. ```ts string ``` ### AuthScopes A class that represents a set of access token scopes. * has Checks whether the current set of scopes includes the given one. ```ts (scope: string | string[] | AuthScopes) => boolean ``` * equals Checks whether the current set of scopes equals the given one. ```ts (otherScopes: string | string[] | AuthScopes) => boolean ``` * toString Returns a comma-separated string with the current set of scopes. ```ts () => string ``` * toArray Returns an array with the current set of scopes. ```ts (returnOriginalScopes?: boolean) => any[] ``` ### SessionParams * \[key: string] ```ts any ``` * accessToken The access token for the session. ```ts string ``` * expires The date the access token expires. ```ts Date ``` * id The unique identifier for the session. ```ts string ``` * isOnline Whether the access token in the session is online or offline. ```ts boolean ``` * onlineAccessInfo Information on the user for the session. Only present for online sessions. ```ts OnlineAccessInfo | StoredOnlineAccessInfo ``` * refreshToken The refresh token for the session. ```ts string ``` * refreshTokenExpires The date the refresh token expires. ```ts Date ``` * scope The scopes for the access token. ```ts string ``` * shop The Shopify shop domain. ```ts string ``` * state The state of the session. Used for the OAuth authentication code flow. ```ts string ``` ### StoredOnlineAccessInfo ```ts Omit & { associated_user: Partial; } ``` ### EmbeddedAdminContext * admin Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request. ```ts AdminApiContext ``` * billing Billing methods for this store, based on the plans defined in the \`billing\` config option. ```ts BillingContext ``` * cors A function that ensures the CORS headers are set correctly for the response. ```ts EnsureCORSFunction ``` * redirect A function that redirects the user to a new page, ensuring that the appropriate parameters are set for embedded apps. Returned only for embedded apps (all apps except merchant custom apps). ```ts RedirectFunction ``` * 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. ```ts Session ``` * sessionToken The decoded and validated session token for the request. Returned only for embedded apps (all distribution types except merchant custom apps) ```ts JwtPayload ``` ### RedirectFunction * url ```ts string ``` * init ```ts RedirectInit ``` returns ```ts Response ``` ### RedirectInit ```ts number | (ResponseInit & {target?: RedirectTarget}) ``` ### RedirectTarget ```ts '_self' | '_parent' | '_top' | '_blank' ``` ### ScopesContext * scopes Methods to manage scopes for the store that made the request. ```ts ScopesApiContext ``` ### ScopesApiContext Provides utilities that apps can use to \[manage scopes]\(https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes) for the app using the Admin API. * query Queries Shopify for the scopes for this app on this shop ```ts () => Promise ``` * request Requests the merchant to grant the provided scopes for this app on this shop Warning: This method performs a server-side redirect. ```ts (scopes: string[]) => Promise ``` * 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. ```ts (scopes: string[]) => Promise ``` ### ScopesDetail * granted The scopes that have been granted on the shop for this app ```ts string[] ``` * optional The optional scopes that the app has declared in its configuration ```ts string[] ``` * required The required scopes that the app has declared in its configuration ```ts string[] ``` ### ScopesRevokeResponse * revoked The scopes that have been revoked on the shop for this app ```ts string[] ``` ### AuthenticateFlow Verifies requests coming from Shopify Flow extensions. * request ```ts Request ``` returns ```ts Promise ``` ### FlowContext * admin An admin context for the Flow request. Returned only if there is a session for the shop. ```ts AdminApiContext ``` * payload The payload from the Flow request. ```ts any ``` * session A session with an offline token for the shop. Returned only if there is a session for the shop. ```ts Session ``` ### AuthenticateFulfillmentService Verifies requests coming from Shopify to fulfillment service apps. * request ```ts Request ``` returns ```ts Promise ``` ### FulfillmentServiceContext * admin An admin context for the fulfillment service request. Returned only if there is a session for the shop. ```ts AdminApiContext ``` * payload The payload from the fulfillment service request. ```ts FulfillmentServicePayload ``` * session A session with an offline token for the shop. Returned only if there is a session for the shop. ```ts Session ``` ### FulfillmentServicePayload ```ts Record & { kind: string; } ``` ### AuthenticatePublic * appProxy Authenticate a request from an app proxy ```ts AuthenticateAppProxy ``` * checkout Authenticate a request from a checkout extension ```ts AuthenticateCheckout ``` * customerAccount Authenticate a request from a customer account extension ```ts AuthenticateCustomerAccount ``` ### AuthenticateAppProxy Authenticates requests coming to the app from Shopify app proxies. * request ```ts Request ``` returns ```ts Promise ``` ### AppProxyContext * admin No session is available for the shop that made this request. Therefore no methods for interacting with the GraphQL / REST Admin APIs are available. ```ts undefined ``` * liquid A utility for creating a Liquid Response. ```ts LiquidResponseFunction ``` * session No session is available for the shop that made this request. This comes from the session storage which \`shopifyApp\` uses to store sessions in your database of choice. ```ts undefined ``` * storefront No session is available for the shop that made this request. Therefore no method for interacting with the Storefront API is available. ```ts undefined ``` ### LiquidResponseFunction * body ```ts string ``` * initAndOptions ```ts number | (ResponseInit & Options) ``` returns ```ts Response ``` ### AppProxyContextWithSession * admin Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request. ```ts AdminApiContext ``` * liquid A utility for creating a Liquid Response. ```ts LiquidResponseFunction ``` * session The session for the shop that 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. ```ts Session ``` * storefront Method for interacting with the Shopify Storefront Graphql API for the store that made the request. ```ts StorefrontContext ``` ### StorefrontContext Provides utilities that apps can use to make requests to the Storefront API. * graphql Method for interacting with the Shopify Storefront GraphQL API If you're getting incorrect type hints in the Shopify template, follow \[these instructions]\(https://github.com/Shopify/shopify-app-template-react-router/tree/main#incorrect-graphql-hints). ```ts GraphQLClient ``` ### AuthenticateCheckout Authenticates requests coming from Shopify checkout extensions. * request ```ts Request ``` * options ```ts AuthenticateCheckoutOptions ``` returns ```ts Promise ``` ### AuthenticateCheckoutOptions * corsHeaders ```ts string[] ``` ### CheckoutContext Authenticated Context for a checkout request * cors A function that ensures the CORS headers are set correctly for the response. ```ts EnsureCORSFunction ``` * sessionToken The decoded and validated session token for the request Refer to the OAuth docs for the \[session token payload]\(https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload). ```ts JwtPayload ``` ### AuthenticateCustomerAccount Authenticates requests coming from Shopify customer account extensions. * request ```ts Request ``` * options ```ts AuthenticateCustomerAccountOptions ``` returns ```ts Promise ``` ### AuthenticateCustomerAccountOptions * corsHeaders ```ts string[] ``` ### CustomerAccountContext Authenticated Context for a customer account extension request * cors A function that ensures the CORS headers are set correctly for the response. ```ts EnsureCORSFunction ``` * sessionToken The decoded and validated session token for the request Refer to the OAuth docs for the \[session token payload]\(https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload). ```ts JwtPayload ``` ### AuthenticateWebhook Verifies requests coming from Shopify webhooks. * request ```ts Request ``` returns ```ts Promise> ``` ### WebhookContext ```ts WebhookContextWithoutSession | WebhookContextWithSession ``` ### WebhookContextWithoutSession * action The action type: 'create', 'update', or 'delete'. Only available for events webhooks. ```ts string ``` * admin ```ts undefined ``` * apiVersion The API version used for the webhook. ```ts string ``` * eventId The unique event identifier. ```ts string ``` * handle The handle for the webhook subscription. Only available for events webhooks. ```ts string ``` * name The name assigned to the webhook subscription. Only available for traditional webhooks. ```ts string ``` * payload The payload from the webhook request. ```ts Record ``` * resourceId The GID of the resource that triggered the webhook. Only available for events webhooks. ```ts string ``` * session ```ts undefined ``` * shop The shop where the webhook was triggered. ```ts string ``` * subTopic The sub-topic of the webhook. Only available for traditional webhooks. ```ts string ``` * topic The topic of the webhook. ```ts Topics ``` * triggeredAt The timestamp when the webhook was triggered. ```ts string ``` * webhookId A unique ID for the webhook. Useful to keep track of which events your app has already processed. For events webhooks (\`webhookType === 'events'\`), this is set to the \`eventId\` value for backwards compatibility. Prefer using \`eventId\` directly for events webhooks — \`webhookId\` will be removed from events webhooks in the next major version. ```ts string ``` * webhookType The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks. ```ts WebhookTypeValue ``` ### WebhookContextWithSession * action The action type: 'create', 'update', or 'delete'. Only available for events webhooks. ```ts string ``` * admin An admin context for the webhook. Returned only if there is a session for the shop. ```ts AdminApiContext ``` * apiVersion The API version used for the webhook. ```ts string ``` * eventId The unique event identifier. ```ts string ``` * handle The handle for the webhook subscription. Only available for events webhooks. ```ts string ``` * name The name assigned to the webhook subscription. Only available for traditional webhooks. ```ts string ``` * payload The payload from the webhook request. ```ts Record ``` * resourceId The GID of the resource that triggered the webhook. Only available for events webhooks. ```ts string ``` * session A session with an offline token for the shop. Returned only if there is a session for the shop. Webhook requests can trigger after an app is uninstalled If the app is already uninstalled, the session may be undefined. Therefore, you should check for the session before using it. ```ts Session ``` * shop The shop where the webhook was triggered. ```ts string ``` * subTopic The sub-topic of the webhook. Only available for traditional webhooks. ```ts string ``` * topic The topic of the webhook. ```ts Topics ``` * triggeredAt The timestamp when the webhook was triggered. ```ts string ``` * webhookId A unique ID for the webhook. Useful to keep track of which events your app has already processed. For events webhooks (\`webhookType === 'events'\`), this is set to the \`eventId\` value for backwards compatibility. Prefer using \`eventId\` directly for events webhooks — \`webhookId\` will be removed from events webhooks in the next major version. ```ts string ``` * webhookType The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks. ```ts WebhookTypeValue ``` ### RegisterWebhooks * options ```ts RegisterWebhooksOptions ``` returns ```ts Promise ``` ### RegisterWebhooksOptions * session The Shopify session used to register webhooks using the Admin API. ```ts Session ``` ### SessionStorageType ```ts Config['sessionStorage'] extends SessionStorage ? Config['sessionStorage'] : SessionStorage ``` ### Unauthenticated * admin Get an admin context by passing a shop \*\*Warning\*\* This should only be used for Requests that do not originate from Shopify. You must do your own authentication before using this method. This method throws an error if there is no session for the shop. ```ts GetUnauthenticatedAdminContext ``` * storefront Get a storefront context by passing a shop \*\*Warning\*\* This should only be used for Requests that do not originate from Shopify. You must do your own authentication before using this method. This method throws an error if there is no session for the shop. ```ts GetUnauthenticatedStorefrontContext ``` ### GetUnauthenticatedAdminContext Creates an unauthenticated Admin context. * shop ```ts string ``` returns ```ts Promise ``` ### UnauthenticatedAdminContext * admin Methods for interacting with the GraphQL Admin API for the given store. ```ts AdminApiContext ``` * session The session for the given shop. This comes from the session storage which \`shopifyApp\` uses to store sessions in your database of choice. This will always be an offline session. You can use to get shop-specific data. ```ts Session ``` ### GetUnauthenticatedStorefrontContext Creates an unauthenticated Storefront context. * shop ```ts string ``` returns ```ts Promise ``` ### UnauthenticatedStorefrontContext * session The session for the given shop. This comes from the session storage which \`shopifyApp\` uses to store sessions in your database of choice. This will always be an offline session. You can use this to get shop specific data. ```ts Session ``` * storefront Method for interacting with the Shopify GraphQL Storefront API for the given store. ```ts StorefrontContext ``` ### EnforceSessionStorage ```ts Base & { sessionStorage: SessionStorageType; } ``` ### Base * \#session ```ts Session ``` * session ```ts Session ``` * save ```ts ({ update }?: SaveArgs) => Promise ``` * saveAndUpdate ```ts () => Promise ``` * delete ```ts () => Promise ``` * serialize ```ts (saving?: boolean) => Body ``` * toJSON ```ts () => Body ``` * request ```ts (args: RequestArgs) => Promise> ``` ### SaveArgs * update ```ts boolean ``` ### Body ### RequestArgs * body ```ts Body | null ``` * entity ```ts Base | null ``` * http\_method ```ts string ``` * operation ```ts string ``` * params ```ts ParamSet ``` * requireIds ```ts boolean ``` * session ```ts Session ``` * urlIds ```ts IdSet ``` ### ParamSet ### IdSet ### RestRequestReturn * body ```ts T ``` * headers ```ts Headers ``` * pageInfo ```ts PageInfo ``` ### PageInfo * fields ```ts string[] ``` * limit ```ts string ``` * nextPage ```ts PageInfoParams ``` * nextPageUrl ```ts string ``` * previousPageUrl ```ts string ``` * prevPage ```ts PageInfoParams ``` ### PageInfoParams * path ```ts string ``` * query ```ts SearchParams ``` ### SingleMerchantApp ```ts ShopifyAppBase & ShopifyAppLogin ``` ### ShopifyAppBase * addDocumentResponseHeaders Adds the required Content Security Policy headers for Shopify apps to the given Headers object. ```ts AddDocumentResponseHeaders ``` * authenticate Ways to authenticate requests from different surfaces across Shopify. ```ts Authenticate ``` * registerWebhooks Register shop-specific webhook subscriptions using the Admin GraphQL API. In many cases defining app-specific webhooks in the \`shopify.app.toml\` will be sufficient and easier to manage. Please see: You should only use this if you need shop-specific webhooks. ```ts RegisterWebhooks ``` * sessionStorage The \`SessionStorage\` instance you passed in as a config option. ```ts SessionStorageType ``` * unauthenticated Ways to get Contexts from requests that do not originate from Shopify. ```ts Unauthenticated ``` ### ShopifyAppLogin * login Log a merchant in, and redirect them to the app root. Will redirect the merchant to authentication if a shop is present in the URL search parameters or form data. This function won't be present when the \`distribution\` config option is set to \`AppDistribution.ShopifyAdmin\`, because Admin apps aren't allowed to show a login page. ```ts Login ``` ### Login * request ```ts Request ``` returns ```ts Promise ``` ### LoginError * shop ```ts LoginErrorType ``` ### LoginErrorType * MissingShop ```ts MISSING_SHOP ``` * InvalidShop ```ts INVALID_SHOP ``` ### AppStoreApp ```ts ShopifyAppBase & ShopifyAppLogin ``` ### AppConfigArg * \_logDisabledFutureFlags Whether to log disabled future flags at startup. ```ts boolean ``` * adminApiAccessToken An app-wide API access token. Only applies to custom apps. ```ts string ``` * apiKey The API key for your app. Also known as Client ID in your Partner Dashboard. ```ts string ``` * apiSecretKey The API secret key for your app. Also known as Client Secret in your Partner Dashboard. ```ts string ``` * apiVersion What version of Shopify's Admin API's would you like to use. ```ts ApiVersion ``` * appUrl The URL your app is running on. The \`@shopify/cli\` provides this URL as \`process.env.SHOPIFY\_APP\_URL\`. For development this is probably a tunnel URL that points to your local machine. If this is a production app, this is your production URL. ```ts string ``` * authPathPrefix A path that Shopify can reserve for auth related endpoints. This must match a $ route in your React Router app. That route must export a loader function that calls \`shopify.authenticate.admin(request)\`. ```ts string ``` * billing Billing configurations for the app. Uses the new line item billing format that allows for more complex billing structures. ```ts BillingConfigWithLineItems ``` * distribution How your app is distributed. Default is \`AppDistribution.AppStore\`. AppStore should be used for public apps that are distributed in the Shopify App Store. SingleMerchant should be used for custom apps managed in the Partner Dashboard. ShopifyAdmin should be used for apps that are managed in the merchant's Shopify Admin. ```ts AppDistribution ``` * domainTransformations Custom domain transformations for split-domain architectures. Transformations are applied in order. The first matching transformation is used. If no transformation matches, the domain is validated as-is. ```ts DomainTransformation[] ``` * future Features that will be introduced in future releases of this package. You can opt in to these features by setting the corresponding flags. By doing so, you can prepare for future releases in advance and provide feedback on the new features. ```ts Future ``` * hooks Functions to call at key places during your apps lifecycle. These functions are called in the context of the request that triggered them. This means you can access the session. ```ts HooksConfig ``` * isTesting Whether the app is initialised for local testing. ```ts boolean ``` * logger Customization options for Shopify logs. ```ts { log?: LogFunction; level?: LogSeverity; httpRequests?: boolean; timestamps?: boolean; } ``` * privateAppStorefrontAccessToken An app-wide API access token for the storefront API. Only applies to custom apps. ```ts string ``` * scopes The scopes your app needs to access the API. Not required if using Shopify managed installation. ```ts string[] | AuthScopes ``` * sessionStorage An adaptor for storing sessions in your database of choice. Shopify provides multiple session storage adaptors and you can create your own. Optional for apps created in the Shopify Admin. ```ts Storage ``` * useOnlineTokens Whether your app use online or offline tokens. If your app uses online tokens, then both online and offline tokens will be saved to your database. This ensures your app can perform background jobs. ```ts boolean ``` * userAgentPrefix The user agent prefix to use for API requests. ```ts string ``` * webhooks The config for the shop-specific webhooks your app needs. Use this to configure shop-specific webhooks. In many cases defining app-specific webhooks in the \`shopify.app.toml\` will be sufficient and easier to manage. Please see: You should only use this if you need shop-specific webhooks. If you do need shop-specific webhooks this can be in used in conjunction with the afterAuth hook, loaders or processes such as background jobs. ```ts WebhookConfig ``` ### BillingConfigWithLineItems * \[plan: string] ```ts | BillingConfigOneTimePlan | BillingConfigSubscriptionLineItemPlan ``` ### DomainTransformation Configuration for transforming shop domains in split-domain architectures. * includeHost Whether this transformation should also apply to host validation. ```ts boolean ``` * match Pattern to match against shop domains (source domain). Can be a RegExp or string (converted to RegExp internally). ```ts RegExp | string ``` * transform Transformation function or template string. - Template string: Uses $1, $2, etc. for capture group substitution - Function: Receives regex match groups and returns transformed domain ```ts ((matches: RegExpMatchArray) => string | null) | string ``` ### HooksConfig * afterAuth A function to call after a merchant installs your app ```ts (options: AfterAuthOptions) => void | Promise ``` ### AfterAuthOptions * admin ```ts AdminApiContext ``` * session ```ts Session ``` ### LogSeverity * Error ```ts 0 ``` * Warning ```ts 1 ``` * Info ```ts 2 ``` * Debug ```ts 3 ``` ### WebhookConfig ### Future flags Set future flags using the `future` configuration field to opt in to upcoming breaking changes. With this feature, you can prepare for major releases ahead of time, as well as try out new features before they are released. Examples ### Examples * #### ##### /shopify.server.ts ```ts import { shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ apiKey: process.env.SHOPIFY_API_KEY!, apiSecretKey: process.env.SHOPIFY_API_SECRET!, scopes: process.env.SCOPES?.split(",")!, appUrl: process.env.SHOPIFY_APP_URL!, }); export default shopify; ``` * #### Return headers on all requests ##### Description Add headers to all HTML requests by calling \`shopify.addDocumentResponseHeaders\` in \`entry.server.tsx\`. ##### \~/shopify.server.ts ```ts import { shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ // ...etc }); export default shopify; export const addDocumentResponseheaders = shopify.addDocumentResponseheaders; ``` ##### entry.server.tsx ```ts import { addDocumentResponseHeaders } from "~/shopify.server"; export default function handleRequest( request: Request, responseStatusCode: number, responseHeaders: Headers, reactRouterContext: EntryContext ) { const markup = renderToString( ); responseHeaders.set("Content-Type", "text/html"); addDocumentResponseHeaders(request, responseHeaders); return new Response("" + markup, { status: responseStatusCode, headers: responseHeaders, }); } ``` * #### Authenticate Shopify requests ##### Description Use the functions in \`authenticate\` to validate requests coming from Shopify. ##### /app/shopify.server.ts ```ts import { ApiVersion, shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ // ...etc }); export default shopify; ``` ##### /app/routes/\*\*\\/\*.jsx ```ts import { LoaderFunctionArgs, json } from "react-router"; import shopify from "../../shopify.server"; export async function loader({ request }: LoaderFunctionArgs) { const {admin, session, sessionToken, billing} = shopify.authenticate.admin(request); const response = admin.graphql(`{ shop { name } }`) return (await response.json()); } ``` * #### ##### Description Trigger the registration to create the shop-specific webhook subscriptions after a merchant installs your app using the \`afterAuth\` hook. Learn more about \[subscribing to webhooks.]\(https://shopify.dev/docs/api/shopify-app-react-router/v3/guide-webhooks) ##### app/shopify.server.ts ```ts import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ webhooks: { PRODUCTS_CREATE: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks/products/create", }, }, hooks: { afterAuth: async ({ session }) => { // Register webhooks for the shop // In this example, every shop will have these webhooks // You could wrap this in some custom shop specific conditional logic if needed shopify.registerWebhooks({ session }); }, }, // ...etc }); ``` * #### ##### Description Import the \`@shopify/shopify-app-session-storage-prisma\` package to store sessions in your Prisma database. ##### /app/shopify.server.ts ```ts import { shopifyApp } from "@shopify/shopify-app-react-router/server"; import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma"; import prisma from "~/db.server"; const shopify = shopifyApp({ sessionStorage: new PrismaSessionStorage(prisma), // ...etc }) // shopify.sessionStorage is an instance of PrismaSessionStorage ``` * #### Using unauthenticated contexts ##### Description Create contexts for requests that don't come from Shopify. ##### /app/shopify.server.ts ```ts import { ApiVersion, shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ // ...etc }); export default shopify; ``` ##### /app/routes/\*\*\\/\*.jsx ```ts import { LoaderFunctionArgs, json } from "react-router"; import { authenticateExternal } from "~/helpers/authenticate" import shopify from "../../shopify.server"; export async function loader({ request }: LoaderFunctionArgs) { const shop = await authenticateExternal(request) const {admin} = await shopify.unauthenticated.admin(shop); const response = admin.graphql(`{ shop { currencyCode } }`) return (await response.json()); } ``` * #### Creating a login page ##### Description Use \`shopify.login\` to create a login form, in a route that can handle GET and POST requests. ##### /app/shopify.server.ts ```ts import { ApiVersion, shopifyApp } from "@shopify/shopify-app-react-router/server"; const shopify = shopifyApp({ // ...etc }); export default shopify; ``` ##### /app/routes/auth/login.tsx ```ts import shopify from "../../shopify.server"; export async function loader({ request }: LoaderFunctionArgs) { const errors = shopify.login(request); return (errors); } export async function action({ request }: ActionFunctionArgs) { const errors = shopify.login(request); return (errors); } export default function Auth() { const actionData = useActionData(); const [shop, setShop] = useState(""); return (
Login
); } ``` *** ## Related [Authenticate requests coming from Shopify. - Authenticated contexts](https://shopify.dev/docs/api/shopify-app-react-router/v1/authenticate) [Interact with the API on non-Shopify requests. - Unauthenticated contexts](https://shopify.dev/docs/api/shopify-app-react-router/v1/unauthenticated) ***