Choose a version:

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.

Anchor to shopifyApp
shopifyApp(
appConfig
)

Creates an object your app will use to interact with Shopify.

Anchor to shopifyApp-parametersParameters

Anchor to appConfig appConfig <Config> required: Configuration options for your Shopify app, such as the scopes your app needs.

Anchor to shopifyApp-returnsReturns

ShopifyApp An object constructed using your appConfig. It has methods for interacting with Shopify.

Readonly

readonly
```
true
```

ShopifyApp

An object your app can use to interact with Shopify. By default, the app's distribution is `AppStore`.

Config['distribution'] extends AppDistribution.ShopifyAdmin
    ? AdminApp<Config>
    : Config['distribution'] extends AppDistribution.SingleMerchant
      ? EnforceSessionStorage<Config, SingleMerchantApp<Config>>
      : Config['distribution'] extends AppDistribution.AppStore
        ? EnforceSessionStorage<Config, AppStoreApp<Config>>
        : EnforceSessionStorage<Config, AppStoreApp<Config>>

AppDistribution

AppStore
```
app_store
```
SingleMerchant
```
single_merchant
```
ShopifyAdmin
```
shopify_admin
```

AdminApp

addDocumentResponseHeaders
Adds the required Content Security Policy headers for Shopify apps to the given Headers object.
```
AddDocumentResponseHeaders
```
authenticate
Ways to authenticate requests from different surfaces across Shopify.
```
Authenticate<Config>
```
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.
```
RegisterWebhooks
```
sessionStorage
The `SessionStorage` instance you passed in as a config option.
```
SessionStorageType<Config>
```
unauthenticated
Ways to get Contexts from requests that do not originate from Shopify.
```
Unauthenticated
```

AddDocumentResponseHeaders

request
```
Request
```
headers
```
Headers
```

returns

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.
```
AuthenticateAdmin<Config>
```
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.
```
AuthenticateFlow
```
fulfillmentService
Authenticate a request from a fulfillment service and get back an authenticated context.
```
AuthenticateFulfillmentService
```
public
Authenticate a public request and get back a session token.
```
AuthenticatePublic
```
webhook
Authenticate a Shopify webhook request, get back an authenticated admin context and details on the webhook request
```
AuthenticateWebhook<string>
```

AuthenticateAdmin

Authenticates requests coming from the Shopify admin. The shape of the returned object changes depending on the `isEmbeddedApp` config.

request
```
Request
```

returns

Promise<AdminContext<Config>>

AdminContext

EmbeddedTypedAdminContext<Config> & ScopesContext

EmbeddedTypedAdminContext

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

NonEmbeddedAdminContext

admin
Methods for interacting with the GraphQL Admin API for the store that made the request.
```
AdminApiContext
```
billing
Billing methods for this store, based on the plans defined in the `billing` config option.
```
BillingContext<Config>
```
cors
A function that ensures the CORS headers are set correctly for the response.
```
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.
```
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
```
GraphQLClient<AdminOperations>
```

GraphQLClient

query
```
Operation extends keyof Operations
```

options

GraphQLQueryOptions<Operation, Operations>

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

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"]

ApiVersion

October24
```
2024-10
```
January25
```
2025-01
```
April25
```
2025-04
```
July25
```
2025-07
```
October25
```
2025-10
```
January26
```
2026-01
```
April26
```
2026-04
```
July26
```
2026-07
```
October26
```
2026-10
```
Unstable
```
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.

(options: CancelBillingOptions) => Promise<AppSubscription>

check

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

<Options extends CheckBillingOptions<Config>>(options?: Options) => Promise<BillingCheckResponseObject>

createUsageRecord
Creates a usage record for an app subscription.
```
(options: CreateUsageRecordOptions) => Promise<UsageRecord>
```

request

Requests payment for the plan.

(options: RequestBillingOptions<Config>) => Promise<never>

require
Checks if the shop has an active payment for any plan defined in the `billing` config option.
```
(options: RequireBillingOptions<Config>) => Promise<BillingCheckResponseObject>
```
updateUsageCappedAmount
Updates the capped amount for a usage billing plan.
```
(options: UpdateUsageCappedAmountOptions) => Promise<never>
```

CancelBillingOptions

isTest
Whether to use the test mode. This prevents the credit card from being charged.
```
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.
```
boolean
```
subscriptionId
The ID of the subscription to cancel.
```
string
```

Options

layout
Whether to use the shop's theme layout around the Liquid content.
```
boolean
```

CheckBillingOptions

isTest
Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged.
```
boolean
```
plans
The plans to check for. Must be one of the values defined in the `billing` config option.
```
(keyof Config["billing"])[]
```

CreateUsageRecordOptions

description
The description of the app usage record.
```
string
```
idempotencyKey
```
string
```
isTest
Whether to use the test mode. This prevents the credit card from being charged.
```
boolean
```

price

The price of the app usage record.

{ amount: number; currencyCode: string; }

subscriptionLineItemId
```
string
```

RequestBillingOptions

amount
Amount to charge for this plan.
```
number
```
currencyCode
Currency code for this plan.
```
string
```
interval
Interval for this plan. Must be set to `OneTime`.
```
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.
```
boolean
```

lineItems

The line items for this plan.

({ 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.
```
keyof Config["billing"]
```
replacementBehavior
The replacement behavior to use for this plan.
```
BillingReplacementBehavior
```
returnUrl
The URL to return to after the merchant approves the payment.
```
string
```
trialDays
How many trial days to give before charging for this plan.
```
number
```

BillingInterval

OneTime
```
ONE_TIME
```
Every30Days
```
EVERY_30_DAYS
```
Annual
```
ANNUAL
```
Usage
```
USAGE
```

BillingReplacementBehavior

ApplyImmediately
```
APPLY_IMMEDIATELY
```
ApplyOnNextBillingCycle
```
APPLY_ON_NEXT_BILLING_CYCLE
```
Standard
```
STANDARD
```

RequireBillingOptions

isTest
Whether to include charges that were created on test mode. Test shops and demo shops cannot be charged.
```
boolean
```
onFailure
How to handle the request if the shop doesn't have an active payment for any plan.
```
(error: any) => Promise<Response>
```
plans
The plans to check for. Must be one of the values defined in the `billing` config option.
```
(keyof Config["billing"])[]
```

UpdateUsageCappedAmountOptions

cappedAmount
The maximum charge for the usage billing plan.
```
{ amount: number; currencyCode: string; }
```
subscriptionLineItemId
The subscription line item ID to update.
```
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.
```
string
```
shop
The Shopify shop domain, such as `example.myshopify.com`.
```
string
```
state
The state of the session. Used for the OAuth authentication code flow.
```
string
```
isOnline
Whether the access token in the session is online or offline.
```
boolean
```
scope
The desired scopes for the access token, at the time the session was created.
```
string
```
expires
The date the access token expires.
```
Date
```
accessToken
The access token for the session.
```
string
```
refreshToken
The refresh token for the session.
```
string
```
refreshTokenExpires
The date the refresh token expires.
```
Date
```
onlineAccessInfo
Information on the user for the session. Only present for online sessions.
```
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.
```
(scopes: string | string[] | AuthScopes, withinMillisecondsOfExpiry?: number) => boolean
```
isScopeChanged
Whether the access token includes the given scopes if they are provided.
```
(scopes: string | string[] | AuthScopes) => boolean
```
isScopeIncluded
Whether the access token includes the given scopes.
```
(scopes: string | string[] | AuthScopes) => boolean
```

isExpired

Whether the access token is expired.

(withinMillisecondsOfExpiry?: number) => boolean

toObject
Converts an object with data into a Session.
```
() => SessionParams
```
equals
Checks whether the given session is equal to this session.
```
(other: Session) => boolean
```
toPropertyArray
Converts the session into an array of key-value pairs.
```
(returnUserData?: boolean) => [string, string | number | boolean][]
```

OnlineAccessInfo

associated_user
The user associated with the access token.
```
OnlineAccessUser
```
associated_user_scope
The effective set of scopes for the session.
```
string
```
expires_in
How long the access token is valid for, in seconds.
```
number
```

OnlineAccessUser

account_owner
Whether the user is the account owner.
```
boolean
```
collaborator
Whether the user is a collaborator.
```
boolean
```
email
The user's email address.
```
string
```
email_verified
Whether the user has verified their email address.
```
boolean
```
first_name
The user's first name.
```
string
```
id
The user's ID.
```
number
```
last_name
The user's last name.
```
string
```
locale
The user's locale.
```
string
```

AuthScopes

A class that represents a set of access token scopes.

has
Checks whether the current set of scopes includes the given one.
```
(scope: string | string[] | AuthScopes) => boolean
```
equals
Checks whether the current set of scopes equals the given one.
```
(otherScopes: string | string[] | AuthScopes) => boolean
```
toString
Returns a comma-separated string with the current set of scopes.
```
() => string
```
toArray
Returns an array with the current set of scopes.
```
(returnOriginalScopes?: boolean) => any[]
```

SessionParams

[key: string]
```
any
```
accessToken
The access token for the session.
```
string
```
expires
The date the access token expires.
```
Date
```
id
The unique identifier for the session.
```
string
```
isOnline
Whether the access token in the session is online or offline.
```
boolean
```
onlineAccessInfo
Information on the user for the session. Only present for online sessions.
```
OnlineAccessInfo | StoredOnlineAccessInfo
```
refreshToken
The refresh token for the session.
```
string
```
refreshTokenExpires
The date the refresh token expires.
```
Date
```
scope
The scopes for the access token.
```
string
```
shop
The Shopify shop domain.
```
string
```
state
The state of the session. Used for the OAuth authentication code flow.
```
string
```

StoredOnlineAccessInfo

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

EmbeddedAdminContext

admin
Methods for interacting with the GraphQL Admin API for the store that made the request.
```
AdminApiContext
```
billing
Billing methods for this store, based on the plans defined in the `billing` config option.
```
BillingContext<Config>
```
cors
A function that ensures the CORS headers are set correctly for the response.
```
EnsureCORSFunction
```
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`. Request parameters (including `id_token`, `shop`, `host`, and `embedded`) are only copied to the destination when it resolves to the same origin as `appUrl`. This helper does not validate the destination URL — avoid passing unvalidated user input (for example, a raw `?next=` query parameter) and use an allow-list of paths instead.
```
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.
```
Session
```
sessionToken
The decoded and validated session token for the request. Returned only if `isEmbeddedApp` is `true`.
```
JwtPayload
```

RedirectFunction

url
```
string
```
init
```
RedirectInit
```

returns

TypedResponse<never>

RedirectInit

number | (ResponseInit & {target?: RedirectTarget})

RedirectTarget

'_self' | '_parent' | '_top' | '_blank'

ScopesContext

scopes
Methods to manage scopes for the store that made the request.
```
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 to see what scopes have been granted
```
() => Promise<ScopesDetail>
```
request
Requests the merchant grant the provided scopes This method performs a redirect to the grant screen.
```
(scopes: string[]) => Promise<void>
```
revoke
Revokes the provided scopes 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.
```
(scopes: string[]) => Promise<ScopesRevokeResponse>
```

ScopesDetail

granted
The scopes that have been granted on the shop for this app
```
string[]
```
optional
The optional scopes that the app has declared in its configuration
```
string[]
```
required
The required scopes that the app has declared in its configuration
```
string[]
```

ScopesRevokeResponse

revoked
The scopes that have been revoked on the shop for this app
```
string[]
```

AuthenticateFlow

Verifies requests coming from Shopify Flow extensions.

request
```
Request
```

returns

Promise<FlowContext>

FlowContext

admin
An admin context for the Flow request. Returned only if there is a session for the shop.
```
AdminApiContext
```
payload
The payload from the Flow request.
```
any
```
session
A session with an offline token for the shop. Returned only if there is a session for the shop.
```
Session
```

AuthenticateFulfillmentService

Verifies requests coming from Shopify to fulfillment service apps.

request
```
Request
```

returns

Promise<FulfillmentServiceContext>

FulfillmentServiceContext

admin
An admin context for the fulfillment service request. Returned only if there is a session for the shop.
```
AdminApiContext
```
payload
The payload from the fulfillment service request.
```
FulfillmentServicePayload
```
session
A session with an offline token for the shop. Returned only if there is a session for the shop.
```
Session
```

FulfillmentServicePayload

Record<string, any> & {
  kind: string;
}

AuthenticatePublic

appProxy
Authenticate a request from an app proxy
```
AuthenticateAppProxy
```
checkout
Authenticate a request from a checkout extension
```
AuthenticateCheckout
```
customerAccount
Authenticate a request from a customer account extension
```
AuthenticateCustomerAccount
```
pos
Authenticate a request from a POS UI extension
```
AuthenticatePOS
```

AuthenticateAppProxy

Authenticates requests coming to the app from Shopify app proxies.

request
```
Request
```

returns

Promise<AppProxyContext | AppProxyContextWithSession>

AppProxyContext

admin
No session is available for the shop that made this request. Therefore no methods for interacting with the GraphQL Admin API are available.
```
undefined
```
liquid
A utility for creating a Liquid Response.
```
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.
```
undefined
```
storefront
No session is available for the shop that made this request. Therefore no method for interacting with the Storefront API is available.
```
undefined
```

LiquidResponseFunction

body
```
string
```
initAndOptions
```
number | (ResponseInit & Options)
```

returns

Response

AppProxyContextWithSession

admin
Methods for interacting with the GraphQL Admin API for the store that made the request.
```
AdminApiContext
```
liquid
A utility for creating a Liquid Response.
```
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.
```
Session
```
storefront
Method for interacting with the Shopify Storefront Graphql API for the store that made the request.
```
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-remix/tree/main#incorrect-graphql-hints).
```
GraphQLClient<StorefrontOperations>
```

AuthenticateCheckout

Authenticates requests coming from Shopify checkout extensions.

request
```
Request
```
options
```
AuthenticateCheckoutOptions
```

returns

Promise<CheckoutContext>

AuthenticateCheckoutOptions

corsHeaders
```
string[]
```

CheckoutContext

Authenticated Context for a checkout request

cors
A function that ensures the CORS headers are set correctly for the response.
```
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).
```
JwtPayload
```

AuthenticateCustomerAccount

Authenticates requests coming from Shopify customer account extensions.

request
```
Request
```
options
```
AuthenticateCustomerAccountOptions
```

returns

Promise<CustomerAccountContext>

AuthenticateCustomerAccountOptions

corsHeaders
```
string[]
```

CustomerAccountContext

Authenticated Context for a customer account extension request

cors
A function that ensures the CORS headers are set correctly for the response.
```
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).
```
JwtPayload
```

AuthenticateWebhook

Verifies requests coming from Shopify webhooks.

request
```
Request
```

returns

Promise<WebhookContext<Topics>>

WebhookContext

WebhookContextWithoutSession<Topics> | WebhookContextWithSession<Topics>

WebhookContextWithoutSession

action
The action type: 'create', 'update', or 'delete'. Only available for events webhooks.
```
string
```
admin
```
undefined
```
apiVersion
The API version used for the webhook.
```
string
```
eventId
The unique event identifier.
```
string
```
handle
The handle for the webhook subscription. Only available for events webhooks.
```
string
```
name
The name assigned to the webhook subscription. Only available for traditional webhooks.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
resourceId
The GID of the resource that triggered the webhook. Only available for events webhooks.
```
string
```
session
```
undefined
```
shop
The shop where the webhook was triggered.
```
string
```
topic
The topic of the webhook.
```
Topics
```
triggeredAt
The timestamp when the webhook was triggered.
```
string
```
webhookId
A unique ID for the webhook. This is the idempotency key — useful to keep track of which events your app has already processed.
```
string
```
webhookType
The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.
```
WebhookTypeValue
```

WebhookContextWithSession

action
The action type: 'create', 'update', or 'delete'. Only available for events webhooks.
```
string
```
admin
An admin context for the webhook. Returned only if there is a session for the shop.
```
AdminApiContext
```
apiVersion
The API version used for the webhook.
```
string
```
eventId
The unique event identifier.
```
string
```
handle
The handle for the webhook subscription. Only available for events webhooks.
```
string
```
name
The name assigned to the webhook subscription. Only available for traditional webhooks.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
resourceId
The GID of the resource that triggered the webhook. Only available for events webhooks.
```
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.
```
Session
```
shop
The shop where the webhook was triggered.
```
string
```
topic
The topic of the webhook.
```
Topics
```
triggeredAt
The timestamp when the webhook was triggered.
```
string
```
webhookId
A unique ID for the webhook. This is the idempotency key — useful to keep track of which events your app has already processed.
```
string
```
webhookType
The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.
```
WebhookTypeValue
```

RegisterWebhooks

options
```
RegisterWebhooksOptions
```

returns

Promise<RegisterReturn | void>

RegisterWebhooksOptions

session
The Shopify session used to register webhooks using the Admin API.
```
Session
```

SessionStorageType

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.
```
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.
```
GetUnauthenticatedStorefrontContext
```

GetUnauthenticatedAdminContext

Creates an unauthenticated Admin context.

shop
```
string
```

returns

Promise<UnauthenticatedAdminContext>

UnauthenticatedAdminContext

admin
Methods for interacting with the GraphQL Admin API for the given store.
```
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.
```
Session
```

GetUnauthenticatedStorefrontContext

Creates an unauthenticated Storefront context.

shop
```
string
```

returns

Promise<UnauthenticatedStorefrontContext>

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.
```
Session
```
storefront
Method for interacting with the Shopify GraphQL Storefront API for the given store.
```
StorefrontContext
```

EnforceSessionStorage

Base & {
  sessionStorage: SessionStorageType<Config>;
}

Base

#session
```
Session
```
session
```
Session
```

save

({ update }?: SaveArgs) => Promise<void>

saveAndUpdate
```
() => Promise<void>
```
delete
```
() => Promise<void>
```
serialize
```
(saving?: boolean) => Body
```
toJSON
```
() => Body
```

request

<T = unknown>(args: RequestArgs) => Promise<RestRequestReturn<T>>

SaveArgs

update
```
boolean
```

Body

RequestArgs

body
```
Body | null
```
entity
```
Base | null
```
http_method
```
string
```
operation
```
string
```
params
```
ParamSet
```
requireIds
```
boolean
```
session
```
Session
```
urlIds
```
IdSet
```

ParamSet

IdSet

RestRequestReturn

body
```
T
```
headers
```
Headers
```
pageInfo
```
PageInfo
```

PageInfo

fields
```
string[]
```
limit
```
string
```
nextPage
```
PageInfoParams
```
nextPageUrl
```
string
```
previousPageUrl
```
string
```
prevPage
```
PageInfoParams
```

PageInfoParams

path
```
string
```
query
```
SearchParams
```

SingleMerchantApp

ShopifyAppBase<Config> & ShopifyAppLogin

ShopifyAppBase

addDocumentResponseHeaders
Adds the required Content Security Policy headers for Shopify apps to the given Headers object.
```
AddDocumentResponseHeaders
```
authenticate
Ways to authenticate requests from different surfaces across Shopify.
```
Authenticate<Config>
```
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.
```
RegisterWebhooks
```
sessionStorage
The `SessionStorage` instance you passed in as a config option.
```
SessionStorageType<Config>
```
unauthenticated
Ways to get Contexts from requests that do not originate from Shopify.
```
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.
```
Login
```

Login

request
```
Request
```

returns

Promise<LoginError | never>

LoginError

shop
```
LoginErrorType
```

LoginErrorType

MissingShop
```
MISSING_SHOP
```
InvalidShop
```
INVALID_SHOP
```

AppStoreApp

ShopifyAppBase<Config> & ShopifyAppLogin

AppConfigArg

_logDisabledFutureFlags
Whether to log disabled future flags at startup.
```
boolean
```
adminApiAccessToken
An app-wide API access token. Only applies to custom apps.
```
string
```
apiKey
The API key for your app. Also known as Client ID in your Partner Dashboard.
```
string
```
apiSecretKey
The API secret key for your app. Also known as Client Secret in your Partner Dashboard.
```
string
```
apiVersion
What version of Shopify's Admin API's would you like to use.
```
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.
```
string
```
authPathPrefix
A path that Shopify can reserve for auth related endpoints. This must match a $ route in your Remix app. That route must export a loader function that calls `shopify.authenticate.admin(request)`.
```
string
```
billing
Billing configurations for the app.
```
BillingConfig
```
cookiePath
The path to use for the OAuth session cookie in non-embedded apps. By default the cookie is written with `path: '/'`, making it domain-wide. This means that when a user authenticates multiple shops in separate tabs, each OAuth callback overwrites the previous cookie, causing all tabs to use the most-recently-authenticated shop. Set this to a string or a function returning a string to scope the cookie to a URL path prefix that is unique per shop. The browser will then maintain one cookie per shop and deliver only the matching one per request. **Requirement:** the configured path must match the actual URL structure of your app — e.g. if each shop lives under `/shops/:shop/`, use that prefix. The library cannot derive this automatically.
```
string | ((session: Session) => string)
```
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.
```
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.
```
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.
```
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.
```
HooksConfig
```
isEmbeddedApp
Does your app render embedded inside the Shopify Admin or on its own. Unless you have very specific needs, this should be true.
```
boolean
```
isTesting
Whether the app is initialised for local testing.
```
boolean
```

logger

Customization options for Shopify logs.

{ log?: LogFunction; level?: LogSeverity; httpRequests?: boolean; timestamps?: boolean; }

privateAppStorefrontAccessToken
An app-wide API access token for the storefront API. Only applies to custom apps.
```
string
```
restResources
REST resources to access the Admin API. You can import these from `@shopify/shopify-api/rest/admin/*`.
```
Resources
```
scopes
The scopes your app needs to access the API. Not required if using Shopify managed installation.
```
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.
```
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.
```
boolean
```
userAgentPrefix
The user agent prefix to use for API requests.
```
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.
```
WebhookConfig
```

BillingConfig

Billing configuration options, indexed by an app-specific plan name.

[plan: string]
```
BillingConfigItem
```

BillingConfigItem

BillingConfigOneTimePlan | BillingConfigSubscriptionLineItemPlan

BillingConfigOneTimePlan

amount
Amount to charge for this plan.
```
number
```
currencyCode
Currency code for this plan.
```
string
```
interval
Interval for this plan. Must be set to `OneTime`.
```
BillingInterval.OneTime
```

BillingConfigSubscriptionLineItemPlan

lineItems

The line items for this plan.

(BillingConfigRecurringLineItem | BillingConfigUsageLineItem)[]

replacementBehavior
The replacement behavior to use for this plan.
```
BillingReplacementBehavior
```
trialDays
How many trial days to give before charging for this plan.
```
number
```

BillingConfigRecurringLineItem

amount
The amount to charge for this line item.
```
number
```
currencyCode
The currency code for this line item.
```
string
```
discount
An optional discount to apply for this line item.
```
BillingConfigSubscriptionPlanDiscount
```
interval
The recurring interval for this line item. Must be either `Every30Days` or `Annual`.
```
BillingInterval.Every30Days | BillingInterval.Annual
```

BillingConfigSubscriptionPlanDiscount

durationLimitInIntervals
The number of intervals to apply the discount for.
```
number
```

value

The discount to apply.

BillingConfigSubscriptionPlanDiscountAmount | BillingConfigSubscriptionPlanDiscountPercentage

BillingConfigSubscriptionPlanDiscountAmount

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

BillingConfigSubscriptionPlanDiscountPercentage

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

BillingConfigUsageLineItem

amount
The capped amount or the maximum amount to be charged in the interval.
```
number
```
currencyCode
The currency code for this line item.
```
string
```
interval
The usage interval for this line item. Must be set to `Usage`.
```
BillingInterval.Usage
```
terms
Usage terms for this line item.
```
string
```

DomainTransformation

Configuration for transforming shop domains in split-domain architectures.

includeHost
Whether this transformation should also apply to host validation.
```
boolean
```
match
Pattern to match against shop domains (source domain). Can be a RegExp or string (converted to RegExp internally).
```
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
```
((matches: RegExpMatchArray) => string | null) | string
```

HooksConfig

afterAuth
A function to call after a merchant installs your app
```
(options: AfterAuthOptions) => void | Promise<void>
```

AfterAuthOptions

admin
```
AdminApiContext
```
session
```
Session
```

LogSeverity

Error
```
0
```
Warning
```
1
```
Info
```
2
```
Debug
```
3
```

WebhookConfig

Anchor to future flagsFuture flags

Future flags are used to enable features that are not yet available by default.

Anchor to customerAddressDefaultFix customerAddressDefaultFix boolean: Change the CustomerAddress classes to expose a is_default property instead of default when fetching data. This resolves a conflict with the default() method in that class.
Anchor to unstable_managedPricingSupport unstable_managedPricingSupport boolean: Enable support for managed pricing, so apps can check for payments without needing a billing config.

Examples

/shopify.server.ts

import { shopifyApp } from "@shopify/shopify-app-remix/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;

Examples

/shopify.server.ts

import { shopifyApp } from "@shopify/shopify-app-remix/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

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

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

entry.server.tsx

import { addDocumentResponseHeaders } from "~/shopify.server";

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  const markup = renderToString(
    <RemixServer context={remixContext} url={request.url} />
  );

  responseHeaders.set("Content-Type", "text/html");
  addDocumentResponseHeaders(request, responseHeaders);

  return new Response("<!DOCTYPE html>" + markup, {
    status: responseStatusCode,
    headers: responseHeaders,
  });
}

Authenticate Shopify requests

Description

Use the functions in `authenticate` to validate requests coming from Shopify.

/app/shopify.server.ts

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

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

/app/routes/**\/*.jsx

import { LoaderFunctionArgs, json } from "@remix-run/node";
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 json(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-remix/v3/guide-webhooks)

app/shopify.server.ts

import { DeliveryMethod, shopifyApp } from "@shopify/shopify-app-remix/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

import { shopifyApp } from "@shopify/shopify-app-remix/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

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

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

/app/routes/**\/*.jsx

import { LoaderFunctionArgs, json } from "@remix-run/node";
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 json(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

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

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

/app/routes/auth/login.tsx

import shopify from "../../shopify.server";

export async function loader({ request }: LoaderFunctionArgs) {
  const errors = shopify.login(request);

  return json(errors);
}

export async function action({ request }: ActionFunctionArgs) {
  const errors = shopify.login(request);

  return json(errors);
}

export default function Auth() {
  const actionData = useActionData<typeof action>();
  const [shop, setShop] = useState("");

  return (
    <Page>
      <Card>
        <Form method="post">
          <FormLayout>
            <Text variant="headingMd" as="h2">
              Login
            </Text>
            <TextField
              type="text"
              name="shop"
              label="Shop domain"
              helpText="e.g: my-shop-domain.myshopify.com"
              value={shop}
              onChange={setShop}
              autoComplete="on"
              error={actionData?.errors.shop}
            />
            <Button submit primary>
              Submit
            </Button>
          </FormLayout>
        </Form>
      </Card>
    </Page>
  );
}

Anchor to RelatedRelated

Authenticate requests coming from Shopify.Authenticated contexts

Interact with the API on non-Shopify requests.Unauthenticated contexts

Was this page helpful?

Anchor to shopifyAppshopifyApp(appConfigappConfig)

Anchor to shopifyApp-parametersParameters

Anchor to shopifyApp-returnsReturns

Readonly

ShopifyApp

AppDistribution

AdminApp

AddDocumentResponseHeaders

Authenticate

AuthenticateAdmin

AdminContext

EmbeddedTypedAdminContext

NonEmbeddedAdminContext

AdminApiContext

GraphQLClient

GraphQLQueryOptions

ApiVersion

BillingContext

CancelBillingOptions

Options

CheckBillingOptions

CreateUsageRecordOptions

RequestBillingOptions

BillingInterval

BillingReplacementBehavior

RequireBillingOptions

UpdateUsageCappedAmountOptions

EnsureCORSFunction

Session

OnlineAccessInfo

OnlineAccessUser

AuthScopes

SessionParams

StoredOnlineAccessInfo

EmbeddedAdminContext

RedirectFunction

RedirectInit

RedirectTarget

ScopesContext

ScopesApiContext

ScopesDetail

ScopesRevokeResponse

AuthenticateFlow

FlowContext

AuthenticateFulfillmentService

FulfillmentServiceContext

FulfillmentServicePayload

AuthenticatePublic

AuthenticateAppProxy

AppProxyContext

LiquidResponseFunction

AppProxyContextWithSession

StorefrontContext

AuthenticateCheckout

AuthenticateCheckoutOptions

CheckoutContext

AuthenticateCustomerAccount

AuthenticateCustomerAccountOptions

CustomerAccountContext

AuthenticateWebhook

WebhookContext

WebhookContextWithoutSession

WebhookContextWithSession

RegisterWebhooks

RegisterWebhooksOptions

SessionStorageType

Unauthenticated

GetUnauthenticatedAdminContext

UnauthenticatedAdminContext

GetUnauthenticatedStorefrontContext

UnauthenticatedStorefrontContext

EnforceSessionStorage

Base

SaveArgs

Body

RequestArgs

ParamSet

IdSet

RestRequestReturn

PageInfo

Anchor to shopifyApp
shopifyApp(
appConfig
)