Flowobject
object
Contains functions for verifying Shopify Flow extensions.
See the Flow documentation for more information.
Verifies requests coming from Shopify Flow extensions.
Anchor to authenticate.flow-parametersParameters
- Anchor to requestrequestRequestrequired
Promise<>
AuthenticateFlow
- request
Request
Promise<FlowContext>(request: Request) => 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
export interface FlowContext {
/**
* A session with an offline token for the shop.
*
* Returned only if there is a session for the shop.
*
* @example
* <caption>Shopify session for the Flow request.</caption>
* <description>Use the session associated with this request.</description>
* ```ts
* // /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();
* };
* ```
*/
session: Session;
/**
* The payload from the Flow request.
*
* @example
* <caption>Flow payload.</caption>
* <description>Get the request's POST payload.</description>
* ```ts
* // /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();
* };
* ```
*/
payload: any;
/**
* An admin context for the Flow request.
*
* Returned only if there is a session for the shop.
*
* @example
* <caption>Flow admin context.</caption>
* <description>Use the `admin` object in the context to interact with the Admin API.</description>
* ```ts
* // /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 });
* }
* ```
*/
admin: AdminApiContext;
}AdminApiContext
- graphql
Methods for interacting with the Shopify Admin GraphQL API
GraphQLClient<AdminOperations>
export interface AdminApiContext {
/**
* Methods for interacting with the Shopify Admin GraphQL API
*
* {@link https://shopify.dev/docs/api/admin-graphql}
* {@link https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-api/docs/reference/clients/Graphql.md}
*
* @example
* <caption>Querying the GraphQL API.</caption>
* <description>Use `admin.graphql` to make query / mutation requests.</description>
* ```ts
* // /app/routes/**\/*.ts
* import { ActionFunctionArgs } from "react-router";
* import { authenticate } from "../shopify.server";
*
* export const action = async ({ request }: ActionFunctionArgs) => {
* const { admin } = await authenticate.admin(request);
*
* const response = await admin.graphql(
* `#graphql
* mutation populateProduct($input: ProductInput!) {
* productCreate(input: $input) {
* product {
* id
* }
* }
* }`,
* {
* variables: {
* input: { title: "Product Name" },
* },
* },
* );
*
* const productData = await response.json();
* return ({
* productId: productData.data?.productCreate?.product?.id,
* });
* }
* ```
*
* ```ts
* // /app/shopify.server.ts
* import { shopifyApp } from "@shopify/shopify-app-react-router/server";
*
* const shopify = shopifyApp({
* // ...
* });
* export default shopify;
* export const authenticate = shopify.authenticate;
* ```
*
* @example
* <caption>Handling GraphQL errors.</caption>
* <description>Catch `GraphqlQueryError` errors to see error messages from the API.</description>
* ```ts
* // /app/routes/**\/*.ts
* import { ActionFunctionArgs } from "react-router";
* import { authenticate } from "../shopify.server";
*
* export const action = async ({ request }: ActionFunctionArgs) => {
* const { admin } = await authenticate.admin(request);
*
* try {
* const response = await admin.graphql(
* `#graphql
* query incorrectQuery {
* products(first: 10) {
* nodes {
* not_a_field
* }
* }
* }`,
* );
*
* return ({ data: await response.json() });
* } catch (error) {
* if (error instanceof GraphqlQueryError) {
* // error.body.errors:
* // { graphQLErrors: [
* // { message: "Field 'not_a_field' doesn't exist on type 'Product'" }
* // ] }
* return ({ errors: error.body?.errors }, { status: 500 });
* }
* return ({ message: "An error occurred" }, { status: 500 });
* }
* }
* ```
*
* ```ts
* // /app/shopify.server.ts
* import { shopifyApp } from "@shopify/shopify-app-react-router/server";
*
* const shopify = shopifyApp({
* // ...
* });
* export default shopify;
* export const authenticate = shopify.authenticate;
* ```
*/
graphql: GraphQLClient<AdminOperations>;
}GraphQLClient
- query
Operation extends keyof Operations - options
GraphQLQueryOptions<Operation, Operations>
interface Promise<T> {
/**
* Attaches callbacks for the resolution and/or rejection of the Promise.
* @param onfulfilled The callback to execute when the Promise is resolved.
* @param onrejected The callback to execute when the Promise is rejected.
* @returns A Promise for the completion of which ever callback is executed.
*/
then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
/**
* Attaches a callback for only the rejection of the Promise.
* @param onrejected The callback to execute when the Promise is rejected.
* @returns A Promise for the completion of the callback.
*/
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
}, interface Promise<T> {}, Promise: PromiseConstructor, interface Promise<T> {
readonly [Symbol.toStringTag]: string;
}, interface Promise<T> {
/**
* Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
* resolved value cannot be modified from the callback.
* @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
* @returns A Promise for the completion of the callback.
*/
finally(onfinally?: (() => void) | undefined | null): Promise<T>;
}<
Operation extends keyof Operations,
>(
query: Operation,
options?: GraphQLQueryOptions<Operation, Operations>,
) => Promise<GraphQLResponse<Operation, Operations>>GraphQLQueryOptions
- apiVersion
The version of the API to use for the request.
ApiVersion - headers
Additional headers to include in the request.
Record<string, any> - signal
An optional AbortSignal to cancel the request.
AbortSignal - tries
The total number of times to try the request if it fails.
number - variables
The variables to pass to the operation.
ApiClientRequestOptions<Operation, Operations>["variables"]
export interface GraphQLQueryOptions<
Operation extends keyof Operations,
Operations extends AllOperations,
> {
/**
* The variables to pass to the operation.
*/
variables?: ApiClientRequestOptions<Operation, Operations>['variables'];
/**
* The version of the API to use for the request.
*/
apiVersion?: ApiVersion;
/**
* Additional headers to include in the request.
*/
headers?: Record<string, any>;
/**
* The total number of times to try the request if it fails.
*/
tries?: number;
/**
* An optional AbortSignal to cancel the request.
*/
signal?: AbortSignal;
}Was this section helpful?
Set a metafield on a customer after a flow 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();
};
examples
Set a metafield on a customer after a flow call
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(); };
Anchor to examplesExamples
Anchor to example-flow-admin-contextFlow admin context
Use the admin object in the context to interact with the Admin API.
Was this section helpful?
Flow admin context
/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 });
}
examples
Flow admin context
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 }); }
Anchor to example-payloadpayload
Anchor to example-flow-payloadFlow payload
Get the request's POST payload.
Was this section helpful?
Flow 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();
};
examples
Flow payload
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(); };
Anchor to example-sessionsession
Anchor to example-shopify-session-for-the-flow-requestShopify session for the Flow request
Use the session associated with this request.
Was this section helpful?
Shopify session for the Flow 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();
};
examples
Shopify session for the Flow request
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(); };
