Choose a version:

Flow

Contains functions for verifying Shopify Flow extensions.

See the Flow documentation for more information.

Anchor to authenticate.flow
authenticate.flow(
request
)

Verifies requests coming from Shopify Flow extensions.

Anchor to authenticate.flow-parametersParameters

Anchor to request request Request required

Anchor to authenticate.flow-returnsReturns

Promise<>

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

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

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

Examples

/app/routes/**.ts

import {type ActionFunctionArgs} from 'react-router';

import {authenticate} from '../shopify.server';

export const action = async ({request}: ActionFunctionArgs) => {

const {admin, payload} = await authenticate.flow(request);

const customerId = payload.properties.customer_id;

const response = await admin.graphql(

`#graphql

mutation setMetafield($customerId: ID!, $time: String!) {

metafieldsSet(metafields: {

ownerId: $customerId

namespace: "my-app",

key: "last_flow_update",

value: $time,

type: "string",

}) {

metafields {

key

value

}

{

variables: {

customerId,

time: new Date().toISOString(),

);

const body = await response.json();

console.log('Updated value', body.data!.metafieldsSet!.metafields![0].value);

return new Response();

};

Examples

Description

Handle a flow action call

/app/routes/**.ts

import {type ActionFunctionArgs} from 'react-router';

import {authenticate} from '../shopify.server';

export const action = async ({request}: ActionFunctionArgs) => {
  const {admin, payload} = await authenticate.flow(request);

  const customerId = payload.properties.customer_id;

  const response = await admin.graphql(
    `#graphql
    mutation setMetafield($customerId: ID!, $time: String!) {
      metafieldsSet(metafields: {
        ownerId: $customerId
        namespace: "my-app",
        key: "last_flow_update",
        value: $time,
        type: "string",
      }) {
        metafields {
          key
          value
        }
      }
    }
    `,
    {
      variables: {
        customerId,
        time: new Date().toISOString(),
      },
    },
  );
  const body = await response.json();

  console.log('Updated value', body.data!.metafieldsSet!.metafields![0].value);

  return new Response();
};

Description

Use the `admin` object in the context to interact with the Admin API.

/app/routes/flow.tsx

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

export async function action({ request }: ActionFunctionArgs) {
  const { admin } = await authenticate.flow(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 ({ data: productData.data });
}

Description

Get the request's POST payload.

/app/routes/flow.tsx

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

export const action = async ({ request }: ActionFunctionArgs) => {
  const { payload } = await authenticate.flow(request);
  return new Response();
};

Description

Use the session associated with this request.

/app/routes/flow.tsx

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

export const action = async ({ request }: ActionFunctionArgs) => {
  const { session, admin } = await authenticate.flow(request);

  console.log(session.id)

  return new Response();
};