import { Card, Prerequisites, Details, WorkflowDiagram, H3 } from "docs-ui" import { Github } from "@medusajs/icons"

export const metadata = { title: Integrate Payload CMS with Medusa, }

{metadata.title}

In this tutorial, you'll learn how to integrate Payload with Medusa.

When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa also facilitates integrating third-party services that enrich your application with features specific to your unique business use case.

By integrating Payload, you can manage your products' content with powerful content management capabilities, such as managing custom fields, media, localization, and more.

<Note>

This guide was built with Payload v3.54.0. If you're using a different version and you run into issues, consider opening an issue.

</Note>

Summary

By following this tutorial, you'll learn how to:

Install and set up Medusa.
Set up Payload in the Next.js Starter Storefront.
Integrate Payload with Medusa to sync product data.
- You'll sync product data when triggered manually by admin users, or as a result of product events in Medusa.
Display product data from Payload in the Next.js Starter Storefront.

You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer.

Step 1: Install a Medusa Application

Start by installing the Medusa application on your machine with the following command:

bash

npx create-medusa-app@latest

First, you'll be asked for the project's name. Then, when prompted about installing the Next.js Starter Storefront, choose "Yes."

Afterwards, the installation process will start, which will install the Medusa application as a monorepository in a directory with your project's name. The backend is installed in the apps/backend directory, and the Next.js Starter Storefront is installed in the apps/storefront directory.

Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterwards, you can log in with the new user and explore the dashboard.

Check out the troubleshooting guides for help.

</Note> <Note>

In this guide, all file paths of backend customizations are relative to the apps/backend directory of your Medusa project.

</Note>

Step 2: Set Up Payload in the Next.js Starter Storefront

In this step, you'll set up Payload in the Next.js Starter Storefront. This requires installing the necessary dependencies, configuring Payload, and creating collections for products and other types.

a. Install Dependencies

In the directory of the Next.js Starter Storefront, run the following command to install the necessary dependencies:

bash

npm install payload @payloadcms/next @payloadcms/richtext-lexical sharp @payloadcms/db-postgres graphql

b. Add Resolution for `undici`

Payload uses the undici package, but some versions of it cause an error in the Payload CLI.

To avoid these errors, add the following resolution and override to the package.json file of the Next.js Starter Storefront:

json

{
  "resolutions": {
    // other resolutions...
    "undici": "5.20.0"
  },
  "overrides": {
    // other overrides...
    "undici": "5.20.0"
  }
}

Then, re-install the dependencies to ensure the correct version of undici is used:

bash

npm install

c. Copy Payload Template Files

Next, you'll need to copy the Payload template files into the Next.js Starter Storefront. These files allow you to access the Payload admin from the Next.js Starter Storefront.

You can find the files in the examples GitHub repository. Copy these files into a new src/app/(payload) directory in the Next.js Starter Storefront.

Then, move all previous files that were under the src/app directory into a new src/app/(storefront) directory. This will ensure that the Payload admin is accessible at the /admin route, and the storefront is still accessible at the root route.

So, the src/app directory should now only include the (payload) and (storefront) directories, each containing their respective files.

d. Modify Next.js Middleware

The Next.js Starter Storefront uses a middleware to prefix all route paths with the first region's country code. While this is useful for storefront routes, it's unnecessary for the Payload admin routes.

So, you'll modify the middleware to exclude the /admin routes.

In src/middleware.ts, change the config object to include /admin in the matcher regex pattern:

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico|images|assets|png|svg|jpg|jpeg|gif|webp|admin).*)",
  ],
}

e. Add Payload Configuration

Next, you'll add the necessary configuration to run Payload in the Next.js Starter Storefront.

Create the file src/payload.config.ts with the following content:

import sharp from "sharp"
import { lexicalEditor } from "@payloadcms/richtext-lexical"
import { postgresAdapter } from "@payloadcms/db-postgres"
import { buildConfig } from "payload"

export default buildConfig({
  editor: lexicalEditor(),
  collections: [
    // TODO add collections
  ],

  secret: process.env.PAYLOAD_SECRET || "",
  db: postgresAdapter({
    pool: {
      connectionString: process.env.PAYLOAD_DATABASE_URL || "",
    },
  }),
  sharp,
})

The configurations are mostly default Payload configurations. You configure Payload to use PostgreSQL as the database adapter. Later, you'll add collections for products and other types.

Refer to the Payload documentation for more information on configuring Payload.

</Note>

In the configurations, you use two environment variables. To set them, add the following in your storefront's .env.local file:

shell

PAYLOAD_DATABASE_URL=postgres://postgres:@localhost:5432/payload
PAYLOAD_SECRET=supersecret

Where:

PAYLOAD_DATABASE_URL is the connection string to the PostgreSQL database that Payload will use. You don't need to create the database beforehand, as Payload will create it automatically.
PAYLOAD_SECRET is your Payload secret. In production, you should use a complex and secure string.

You also need to add a path alias to the payload.config.ts file, as Payload will try to import it using @payload-config.

In tsconfig.json, add the following path alias:

json

{
  "compilerOptions": {
    // other options...
    "paths": {
      // other paths...
      "@payload-config": ["./payload.config.ts"]
    }
  }
}

The baseUrl in the tsconfig.json file is set to "./src", so the path alias will resolve to src/payload.config.ts.

f. Customize Next.js Configurations

You also need to customize the Next.js configurations to ensure that Payload works correctly with the Next.js Starter Storefront.

In next.config.js, add the following require statement at the top of the file:

const { withPayload } = require("@payloadcms/next/withPayload")

Then, find the module.exports statement and replace it with the following:

module.exports = withPayload(nextConfig)

You wrap the Next.js configuration with the withPayload function to ensure that Payload works correctly with Next.js.

g. Add Collections to Payload

Now that Payload is set up in your storefront, you'll create the following collections:

User: A Payload user with API key authentication, allowing you later to sync product data from Medusa to Payload.
Media: A collection for media files, allowing you to manage product images and other media.
Product: A collection for products, which will be synced with Medusa's product data.

Once you're done, you'll add the collections to src/payload.config.ts.

User Collection

To create the User collection, create the file src/collections/Users.ts with the following content:

import type { CollectionConfig } from "payload"

export const Users: CollectionConfig = {
  slug: "users",
  admin: {
    useAsTitle: "email",
  },
  auth: {
    useAPIKey: true,
  },
  fields: [],
}

The Users collection allows you to manage users that can log into the Payload admin with email and API key authentication.

Refer to the Payload documentation to learn more about API key authentication.

</Note>

Media Collection

To create the Media collection, create the file src/collections/Media.ts with the following content:

import { CollectionConfig } from "payload"

export const Media: CollectionConfig = {
  slug: "media",
  upload: {
    staticDir: "public",
    imageSizes: [
      {
        name: "thumbnail",
        width: 400,
        height: 300,
        position: "centre",
      },
      {
        name: "card",
        width: 768,
        height: 1024,
        position: "centre",
      },
      {
        name: "tablet",
        width: 1024,
        height: undefined,
        position: "centre",
      },
    ],
    adminThumbnail: "thumbnail",
    mimeTypes: ["image/*"],
    pasteURL: {
      allowList: [
        {
          protocol: "http",
          hostname: "localhost",
        },
        {
          protocol: "https",
          hostname: "medusa-public-images.s3.eu-west-1.amazonaws.com",
        },
        {
          protocol: "https",
          hostname: "medusa-server-testing.s3.amazonaws.com",
        },
        {
          protocol: "https",
          hostname: "medusa-server-testing.s3.us-east-1.amazonaws.com",
        },
      ],
    },
  },
  fields: [
    {
      name: "alt",
      type: "text",
      label: "Alt Text",
      required: false,
    },
  ],
}

The Media collection will store media files, such as product images. You can upload files to the Storage Adapters configured in Payload, such as AWS S3 or local storage. The above configurations point to the public directory of the Next.js Starter Storefront as the upload directory.

Note that you allow pasting URLs from specific sources, such as the Medusa public images S3 bucket. This allows you to paste Medusa's stock image URLs in the Payload admin.

Product Collection

Finally, you'll add the Product collection, which will be synced with Medusa's product data.

Create the file src/collections/Products.ts with the following content:

export const productCollectionHighlights = [ ["20", "update", "Only allow updating from Medusa"], ["144", "update", "Only allow updating from Medusa"], ["172", "update", "Only allow updating from Medusa"], ["189", "update", "Only allow updating from Medusa"], ["202", "update", "Only allow updating from Medusa"], ["223", "create", "Only allow creating from Medusa"], ["224", "delete", "Only allow deleting from Medusa"] ]

import { CollectionConfig } from "payload"

export const Products: CollectionConfig = {
  slug: "products",
  admin: {
    useAsTitle: "title",
  },
  fields: [
    {
      name: "medusa_id",
      type: "text",
      label: "Medusa Product ID",
      required: true,
      unique: true,
      admin: {
        description: "The unique identifier from Medusa",
        hidden: true, // Hide this field in the admin UI
      },
      access: {
        update: ({ req }) => !!req.query.is_from_medusa,
      },
    },
    {
      name: "title",
      type: "text",
      label: "Title",
      required: true,
      admin: {
        description: "The product title",
      },
    },
    {
      name: "handle",
      type: "text",
      label: "Handle",
      required: true,
      admin: {
        description: "URL-friendly unique identifier",
      },
      validate: (value: any) => {
        // validate URL-friendly handle
        if (typeof value !== "string") {
          return "Handle must be a string"
        }
        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)) {
          return "Handle must be URL-friendly (lowercase letters, numbers, and hyphens only)"
        }
        return true
      },
    },
    {
      name: "subtitle",
      type: "text",
      label: "Subtitle",
      required: false,
      admin: {
        description: "Product subtitle",
      },
    },
    {
      name: "description",
      type: "richText",
      label: "Description",
      required: false,
      admin: {
        description: "Detailed product description",
      },
    },
    {
      name: "thumbnail",
      type: "upload",
      relationTo: "media" as any,
      label: "Thumbnail",
      required: false,
      admin: {
        description: "Product thumbnail image",
      },
    },
    {
      name: "images",
      type: "array",
      label: "Product Images",
      required: false,
      fields: [
        {
          name: "image",
          type: "upload",
          relationTo: "media" as any,
          required: true,
        },
      ],
      admin: {
        description: "Gallery of product images",
      },
    },
    {
      name: "seo",
      type: "group",
      label: "SEO",
      fields: [
        {
          name: "meta_title",
          type: "text",
          label: "Meta Title",
          required: false,
        },
        {
          name: "meta_description",
          type: "textarea",
          label: "Meta Description",
          required: false,
        },
        {
          name: "meta_keywords",
          type: "text",
          label: "Meta Keywords",
          required: false,
        },
      ],
      admin: {
        description: "SEO-related fields for better search visibility",
      },
    },
    {
      name: "options",
      type: "array",
      fields: [
        {
          name: "title",
          type: "text",
          label: "Option Title",
          required: true,
        },
        {
          name: "medusa_id",
          type: "text",
          label: "Medusa Option ID",
          required: true,
          admin: {
            description: "The unique identifier for the option from Medusa",
            hidden: true, // Hide this field in the admin UI
          },
          access: {
            update: ({ req }) => !!req.query.is_from_medusa,
          },
        },
      ],
      validate: (value: any, { req, previousValue }) => {
        // TODO add validation to ensure that the number of options cannot be changed
      },
    },
    {
      name: "variants",
      type: "array",
      fields: [
        {
          name: "title",
          type: "text",
          label: "Variant Title",
          required: true,
        },
        {
          name: "medusa_id",
          type: "text",
          label: "Medusa Variant ID",
          required: true,
          admin: {
            description: "The unique identifier for the variant from Medusa",
            hidden: true, // Hide this field in the admin UI
          },
          access: {
            update: ({ req }) => !!req.query.is_from_medusa,
          },
        },
        {
          name: "option_values",
          type: "array",
          fields: [
            {
              name: "medusa_id",
              type: "text",
              label: "Medusa Option Value ID",
              required: true,
              admin: {
                description: "The unique identifier for the option value from Medusa",
                hidden: true, // Hide this field in the admin UI
              },
              access: {
                update: ({ req }) => !!req.query.is_from_medusa,
              },
            },
            {
              name: "medusa_option_id",
              type: "text",
              label: "Medusa Option ID",
              required: true,
              admin: {
                description: "The unique identifier for the option from Medusa",
                hidden: true, // Hide this field in the admin UI
              },
              access: {
                update: ({ req }) => !!req.query.is_from_medusa,
              },
            },
            {
              name: "value",
              type: "text",
              label: "Value",
              required: true,
            },
          ],
        },
      ],
      validate: (value: any, { req, previousValue }) => {
        // TODO add validation to ensure that the number of variants cannot be changed
      },
    },
  ],
  hooks: {
    // TODO add 
  },
  access: {
    create: ({ req }) => !!req.query.is_from_medusa,
    delete: ({ req }) => !!req.query.is_from_medusa,
  },
}

You create a Products collection having the following fields:

medusa_id: The product's ID in Medusa, which is useful when syncing data between Payload and Medusa.
title: The product's title.
handle: A URL-friendly unique identifier for the product.
subtitle: An optional subtitle for the product.
description: A rich text description of the product.
thumbnail: An optional thumbnail image for the product.
images: An array of images for the product.
seo: A group of fields for SEO-related information, such as meta title, description, and keywords.
options: An array of product options, such as size or color.
variants: An array of product variants, each with its own title and option values.

All of these fields will be filled from Medusa.

In addition, you also add the following access-control configurations:

You disallow creating or deleting products from the Payload admin, as these actions should only be performed from Medusa.
You disallow updating the medusa_id fields from the Payload admin, as these fields are managed by Medusa.

Add Validation for Options and Variants

Payload admin users can only manage the content of product options and variants, but they shouldn't be able to remove or add new options or variants.

To ensure this behavior, you'll add validation to the options and variants fields in the Products collection.

First, replace the validate function in the options field with the following:

export const Products: CollectionConfig = {
  // other configurations...
  fields: [
    // other fields...
    {
      name: "options",
      // other configurations...
      validate: (value: any, { req, previousValue }) => {
        if (req.query.is_from_medusa) {
          return true // Skip validation if the request is from Medusa
        }
        
        if (!Array.isArray(value)) {
          return "Options must be an array"
        }

        const optionsChanged = value.length !== previousValue?.length || value.some((option) => {
          return !option.medusa_id || !previousValue?.some(
            (prevOption) => (prevOption as any).medusa_id === option.medusa_id
          )
        })

        // Prevent update if the number of options is changed
        return !optionsChanged || "Options cannot be changed in number"
      },
    },
  ],
}

If the request is from Medusa (which is indicated by the is_from_medusa query parameter), the validation is skipped.

Otherwise, you only allow updating the options if the number of options remains the same and each option has a medusa_id that matches an existing option in the previous value.

Next, replace the validate function in the variants field with the following:

export const Products: CollectionConfig = {
  // other configurations...
  fields: [
    // other fields...
    {
      name: "variants",
      // other configurations...
      validate: (value: any, { req, previousValue }) => {
        if (req.query.is_from_medusa) {
          return true // Skip validation if the request is from Medusa
        }

        if (!Array.isArray(value)) {
          return "Variants must be an array"
        }

        const changedVariants = value.length !== previousValue?.length || value.some((variant: any) => {
          return !variant.medusa_id || !previousValue?.some(
            (prevVariant: any) => prevVariant.medusa_id === variant.medusa_id
          )
        })

        if (changedVariants) {
          // Prevent update if the number of variants is changed
          return "Variants cannot be changed in number"
        }
        
        const changedOptionValues = value.some((variant: any) => {
          if (!Array.isArray(variant.option_values)) {
            return true // Invalid structure
          }

          const previousVariant = previousValue?.find(
            (v: any) => v.medusa_id === variant.medusa_id
          ) as Record<string, any> | undefined

          return variant.option_values.length !== previousVariant?.option_values.length || 
            variant.option_values.some((optionValue: any) => {
              return !optionValue.medusa_id || !previousVariant?.option_values.some(
                (prevOptionValue: any) => prevOptionValue.medusa_id === optionValue.medusa_id
              )
            })
        })

        return !changedOptionValues || "Option values cannot be changed in number"
      },
    },
  ],
}

If the request is from Medusa, the validation is skipped.

Otherwise, the function validates that:

The number of variants is the same as the previous value.
Each variant has a medusa_id that matches an existing variant in the previous value.
The number of option values for each variant is the same as the previous value.
Each option value has a medusa_id that matches an existing option value in the previous value.

If any of these validations fail, an error message is returned, preventing the update.

Add Hooks to Normalize Product Data

Next, you'll add a beforeChange hook to the Products collection that will normalize incoming description data to rich-text format.

In src/collections/Products.ts, add the following import statement at the top of the file:

import { convertLexicalToMarkdown, convertMarkdownToLexical, editorConfigFactory } from "@payloadcms/richtext-lexical"

Then, in the Products collection, add a beforeChange property to the hooks configuration:

export const Products: CollectionConfig = {
  // other configurations...
  hooks: {
    beforeChange: [
      async ({ data, req }) => {
        if (typeof data.description === "string") {
          data.description = convertMarkdownToLexical({
            editorConfig: await editorConfigFactory.default({
              config: req.payload.config,
            }),
            markdown: data.description,
          })
        }

        return data
      },
    ],
  },
}

This hook checks if the description field is a string and converts it to rich-text format. This ensures that a description coming from Medusa is properly formatted when stored in Payload.

Add Collections to Payload's Configurations

Now that you've created the collections, you need to add them to Payload's configurations.

In src/payload.config.ts, add the following imports at the top of the file:

import { Users } from "./collections/Users"
import { Products } from "./collections/Products"
import { Media } from "./collections/Media"

Then, add the collections to the collections array of the buildConfig function:

export default buildConfig({
  // ...
  collections: [
    Users,
    Products,
    Media,
  ],
  // ...
})

i. Generate Payload Imports Map

Before running the Payload admin, you need to generate the imports map that Payload uses to resolve the collections and other configurations.

Run the following command in the Next.js Starter Storefront directory:

bash

npx payload generate:importmap

This command generates the src/app/(payload)/admin/importMap.js file that Payload needs.

j. Run the Payload Admin

You can now run the Payload admin in the Next.js Starter Storefront and create an admin user.

To start the Next.js Starter Storefront, run the following command in the Next.js Starter Storefront directory:

bash

npm run dev

Then, open the Payload admin in your browser at http://localhost:8000/admin. The first time you access it, Payload will create a database at the connection URL you provided in the .env.local file.

Then, you'll see a form to create a new admin user. Enter the user's credentials and submit the form.

Once you're logged in, you can see the Products, Users, and Media collections in the Payload admin.

Step 3: Integrate Payload with Medusa

Now that Payload is set up in the Next.js Starter Storefront, you'll create a Payload Module to integrate it with Medusa.

A module is a reusable package that provides functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.

<Note>

Refer to the Modules documentation to learn more about modules and their structure.

</Note>

a. Create Module Directory

A module is created under the src/modules directory of your Medusa application. So, create the directory src/modules/payload.

b. Create Types for the Module

Next, you'll create a types file that will hold the types for the module's options and service methods.

Create the file src/modules/payload/types.ts with the following content:

export interface PayloadModuleOptions {
  serverUrl: string;
  apiKey: string;
  userCollection?: string;
}

For now, the file only contains the PayloadModuleOptions interface, which defines the options that the module will receive. It includes:

serverUrl: The URL of the Payload server.
apiKey: The API key for authenticating with the Payload server.
userCollection: The name of the user collection in Payload. This is optional and defaults to users. It's useful for the authentication header when sending requests to the Payload API.

c. Create Service

A module has a service that contains its logic. So, the Payload Module's service will contain the logic to create, update, retrieve, and delete data in Payload.

Create the file src/modules/payload/service.ts with the following content:

import {
  PayloadModuleOptions,
} from "./types"
import { MedusaError } from "@medusajs/framework/utils"

type InjectedDependencies = {
  // inject any dependencies you need here
};

export default class PayloadModuleService {
  private baseUrl: string
  private headers: Record<string, string>
  private defaultOptions: Record<string, any> = {
    is_from_medusa: true,
  }

  constructor(
    container: InjectedDependencies,
    options: PayloadModuleOptions
  ) {
    this.validateOptions(options)
    this.baseUrl = `${options.serverUrl}/api`
    
    this.headers = {
      "Content-Type": "application/json",
      "Authorization": `${
        options.userCollection || "users"
      } API-Key ${options.apiKey}`,
    }
  }

  validateOptions(options: Record<any, any>): void | never {
    if (!options.serverUrl) {
      throw new MedusaError(
        MedusaError.Types.INVALID_ARGUMENT,
        "Payload server URL is required"
      )
    }
    
    if (!options.apiKey) {
      throw new MedusaError(
        MedusaError.Types.INVALID_ARGUMENT,
        "Payload API key is required"
      )
    }
  }
}

The constructor of a module's service receives the following parameters:

The Module container that allows you to resolve module and Framework resources. You don't need to resolve any resources in this module, so you can leave it empty.
The module options, which you'll pass to the module when you register it later in the Medusa application.

In the constructor, you validate the module options and set up the Payload base URL and headers that are necessary to send requests to Payload.

c. Add Methods to the Service

Next, you'll add methods to the service that allow you to create, update, retrieve, and delete products in Payload.

makeRequest Method

The makeRequest private method is a utility function that makes HTTP requests to the Payload API. You'll use this method in other public methods that perform operations in Payload.

Add the makeRequest method to the PayloadModuleService class:

export default class PayloadModuleService {
  // ...
  private async makeRequest<T = any>(
    endpoint: string,
    options: RequestInit = {}
  ): Promise<T> {
    const url = `${this.baseUrl}${endpoint}`
    
    try {
      const response = await fetch(url, {
        ...options,
        headers: {
          ...this.headers,
          ...options.headers,
        },
      })

      if (!response.ok) {
        const errorData = await response.json().catch(() => ({}))
        throw new MedusaError(
          MedusaError.Types.UNEXPECTED_STATE,
          `Payload API error: ${response.status} ${response.statusText}. ${
            errorData.message || ""
          }`
        )
      }

      return await response.json()
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        `Failed to communicate with Payload: ${JSON.stringify(error)}`
      )
    }
  }
}

The makeRequest method receives the endpoint to call and the options for the request. It constructs the full URL, makes the request, and returns the response data as JSON.

If the request fails, it throws a MedusaError with the error message.

create Method

The create method will allow you to create an entry in a Payload collection, such as Products.

Before you create the method, you'll need to add necessary types for its parameters and return value.

In src/modules/payload/types.ts, add the following types:

export interface PayloadCollectionItem {
  id: string;
  createdAt: string;
  updatedAt: string;
  medusa_id: string;
  [key: string]: any;
}

export interface PayloadUpsertData {
  [key: string]: any;
}

export interface PayloadQueryOptions {
  depth?: number;
  locale?: string;
  fallbackLocale?: string;
  select?: string;
  populate?: string;
  limit?: number;
  page?: number;
  sort?: string;
  where?: Record<string, any>;
}

export interface PayloadItemResult<T = PayloadCollectionItem> {
  doc: T;
  message: string;
}

You define the following types:

PayloadCollectionItem: an item in a Payload collection.
PayloadUpsertData: the data required to create or update an item in a Payload collection.
PayloadQueryOptions: the options for querying items in a Payload collection, which you can learn more about in the Payload documentation.
PayloadItemResult: the result of a querying or performing an operation on a Payload item, which includes the item and a message.

Next, add the following import statements at the top of the src/modules/payload/service.ts file:

import {
  PayloadCollectionItem,
  PayloadUpsertData,
  PayloadQueryOptions,
  PayloadItemResult,
} from "./types"
import qs from "qs"

You import the types you just defined and the qs library, which you'll use to stringify query options.

Then, add the create method to the PayloadModuleService class:

export default class PayloadModuleService {
  // ... other methods
  async create<T extends PayloadCollectionItem = PayloadCollectionItem>(
    collection: string,
    data: PayloadUpsertData,
    options: PayloadQueryOptions = {}
  ): Promise<PayloadItemResult<T>> {

    const stringifiedQuery = qs.stringify({
      ...options,
      ...this.defaultOptions,
    }, {
      addQueryPrefix: true,
    })

    const endpoint = `/${collection}/${stringifiedQuery}`

    const result = await this.makeRequest<PayloadItemResult<T>>(endpoint, {
      method: "POST",
      body: JSON.stringify(data),
    })
    return result
  }
}

The create method receives the following parameters:

collection: the slug of the collection in Payload where you want to create an item. For example, products.
data: the data for the new item you want to create.
options: optional query options for the request.

In the method, you use the makeRequest method to send a POST request to Payload, passing it the endpoint and request body data.

Finally, you return the result of the request that contains the created item and a message.

update Method

Next, you'll add the update method that allows you to update an existing item in a Payload collection.

Add the update method to the PayloadModuleService class:

export default class PayloadModuleService {
  // ... other methods
  async update<T extends PayloadCollectionItem = PayloadCollectionItem>(
    collection: string,
    data: PayloadUpsertData,
    options: PayloadQueryOptions = {}
  ): Promise<PayloadItemResult<T>> {

    const stringifiedQuery = qs.stringify({
      ...options,
      ...this.defaultOptions,
    }, {
      addQueryPrefix: true,
    })

    const endpoint = `/${collection}/${stringifiedQuery}`

    const result = await this.makeRequest<PayloadItemResult<T>>(endpoint, {
      method: "PATCH",
      body: JSON.stringify(data),
    })

    return result
  }
}

Similar to the create method, the update method receives the collection slug, the data to update, and optional query options.

In the method, you use the makeRequest method to send a PATCH request to Payload, passing it the endpoint and request body data.

Finally, you return the result of the request that contains the updated item and a message.

delete Method

Next, you'll add the delete method that allows you to delete an item from a Payload collection.

First, add the following type to src/modules/payload/types.ts:

export interface PayloadApiResponse<T = any> {
  data?: T;
  errors?: Array<{
    message: string;
    field?: string;
  }>;
  message?: string;
}

This represents a generic response from Payload, which can include data, errors, and a message.

Then, add the following import statement at the top of the src/modules/payload/service.ts file:

import {
  PayloadApiResponse,
} from "./types"

After that, add the delete method to the PayloadModuleService class:

export default class PayloadModuleService {
  // ... other methods
  async delete(
    collection: string,
    options: PayloadQueryOptions = {}
  ): Promise<PayloadApiResponse> {

    const stringifiedQuery = qs.stringify({
      ...options,
      ...this.defaultOptions,
    }, {
      addQueryPrefix: true,
    })

    const endpoint = `/${collection}/${stringifiedQuery}`

    const result = await this.makeRequest<PayloadApiResponse>(endpoint, {
      method: "DELETE",
    })

    return result
  }
}

The delete method receives as parameters the collection slug and optional query options.

In the method, you use the makeRequest method to send a DELETE request to Payload, passing it the endpoint.

Finally, you return the result of the request that contains any data, errors, or a message.

find Method

The last method you'll add for now is the find method, which allows you to retrieve items from a Payload collection.

First, add the following type to src/modules/payload/types.ts:

export interface PayloadBulkResult<T = PayloadCollectionItem> {
  docs: T[];
  totalDocs: number;
  limit: number;
  page: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
  nextPage: number | null;
  prevPage: number | null;
  pagingCounter: number;
}

This type represents the result of a bulk query to a Payload collection, which includes an array of documents and pagination information.

Then, add the following import statement at the top of the src/modules/payload/service.ts file:

import {
  PayloadBulkResult,
} from "./types"

After that, add the find method to the PayloadModuleService class:

export default class PayloadModuleService {
  async find(
    collection: string,
    options: PayloadQueryOptions = {}
  ): Promise<PayloadBulkResult<PayloadCollectionItem>> {

    const stringifiedQuery = qs.stringify({
      ...options,
      ...this.defaultOptions,
    }, {
      addQueryPrefix: true,
    })

    const endpoint = `/${collection}${stringifiedQuery}`

    const result = await this.makeRequest<
      PayloadBulkResult<PayloadCollectionItem>
    >(endpoint)

    return result
  }
}

The find method receives the collection slug and optional query options.

In the method, you use the makeRequest method to send a GET request to Payload, passing it the endpoint with the query options.

Finally, you return the result of the request that contains an array of documents and pagination information.

d. Export Module Definition

The final piece to a module is its definition, which you export in an index.ts file at the module's root directory. This definition tells Medusa the name of the module, its service, and optionally its loaders.

To create the module's definition, create the file src/modules/payload/index.ts with the following content:

import { Module } from "@medusajs/framework/utils"
import PayloadModuleService from "./service"

export const PAYLOAD_MODULE = "payload"

export default Module(PAYLOAD_MODULE, {
  service: PayloadModuleService,
})

You use Module from the Modules SDK to create the module's definition. It accepts two parameters:

The module's name, which is payload.
An object with a required property service indicating the module's service. You also pass the loader you created to ensure it's executed when the application starts.

Aside from the module definition, you export the module's name as PAYLOAD_MODULE so you can reference it later.

e. Add Module to Medusa's Configurations

Once you finish building the module, add it to Medusa's configurations to start using it.

In medusa-config.ts, add a modules property and pass an array with your custom module:

module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "./src/modules/payload",
      options: {
        serverUrl: process.env.PAYLOAD_SERVER_URL || "http://localhost:8000",
        apiKey: process.env.PAYLOAD_API_KEY,
        userCollection: process.env.PAYLOAD_USER_COLLECTION || "users",
      },
    },
  ],
})

Each object in the modules array has a resolve property, whose value is either a path to the module's directory, or an npm package's name.

You also pass an options property with the module's options. You'll set the values of these options next.

f. Set Environment Variables

To use the Payload Module, you need to set the module options in the environment variables of your Medusa application.

One of these options is the API key of a Payload admin user. To get the API key:

Start the Next.js Starter Storefront with the following command:

bash

npm run dev

Open localhost:8000/admin in your browser and log in with the admin user you created earlier.
Click on the "Users" collection in the sidebar.
Choose your admin user from the list.
Click on the "Enable API key" checkbox and copy the API key that appears.
Click the "Save" button to save the changes.

Next, add the following environment variables to your Medusa application's .env file:

shell

PAYLOAD_SERVER_URL=http://localhost:8000
PAYLOAD_API_KEY=your_api_key_here
PAYLOAD_USER_COLLECTION=users

Make sure to replace your_api_key_here with the API key you copied from the Payload admin.

The Payload Module is now ready for use. You'll add customizations next to sync product data between Medusa and Payload.

Step 4: Create Virtual Read-Only Link to Products

Medusa's Module Links feature allows you to virtually link data models from external services to modules in your Medusa application. Then, when you retrieve data from Medusa, you can also retrieve the linked data from the third-party service automatically.

In this step, you'll define a virtual read-only link between the Products collection in Payload and the Product model in Medusa. Later, you'll be able to retrieve products from Payload while retrieving products in Medusa.

a. Define the Link

To define a virtual read-only link, create the file src/links/product-payload.ts with the following content:

import { defineLink } from "@medusajs/framework/utils"
import ProductModule from "@medusajs/medusa/product"
import { PAYLOAD_MODULE } from "../modules/payload"

export default defineLink(
  {
    linkable: ProductModule.linkable.product,
    field: "id",
  },
  {
    linkable: {
      serviceName: PAYLOAD_MODULE,
      alias: "payload_product",
      primaryKey: "product_id",
    },
  },
  {
    readOnly: true,
  }
)

The defineLink function accepts three parameters:

An object of the first data model that is part of the link. In this case, it's the Product model from Medusa's Product Module.
An object of the second data model that is part of the link. In this case, it's the Products collection from the Payload Module. You set the following properties:
- serviceName: the name of the Payload Module, which is payload.
- alias: an alias for the linked data model, which is payload_product. You'll use this alias to reference the linked data model in queries.
- primaryKey: the primary key of the linked data model, which is product_id. Medusa will look for this field in the retrieved Products from payload to match it with the id field of the Product model.
An object with the readOnly property set to true, indicating that this link is read-only. This means you can only retrieve the linked data, but you don't manage the link in the database.

b. Add list Method to the Payload Module Service

When you retrieve products from Medusa with their payload_product link, Medusa will call the list method of the Payload Module's service to retrieve the linked products from Payload.

So, in src/modules/payload/service.ts, add a list method to the PayloadModuleService class:

export default class PayloadModuleService {
  // ... other methods
  async list(
    filter: {
      product_id: string | string[]
    }
  ) {
    const collection = filter.product_id ? "products" : "unknown"
    const ids = Array.isArray(filter.product_id) ? filter.product_id : [filter.product_id]
    const result = await this.find(
      collection,
      {
        where: {
          medusa_id: {
            in: ids.join(","),
          },
        },
        depth: 2,
      }
    )

    return result.docs.map((doc) => ({
      ...doc,
      product_id: doc.medusa_id,
    }))
  }
}

The list method receives a filter object with an product_id property, which is the Medusa product ID(s) to retrieve their corresponding data from Payload.

In the method, you call the find method of the Payload Module's service to retrieve products from the products collection in Payload. You pass a where query parameter to filter products by their medusa_id field.

Finally, you return an array of the payload products. You set the product_id field to the value of the medusa_id field, which is used to match the linked data in Medusa.

You can now retrieve products from Payload while retrieving products in Medusa. You'll learn how to do this in the upcoming steps.

The list method is implemented to be re-usable with different collections and data models. For example, if you add a Categories collection in Payload, you can use the same list method to retrieve categories by their medusa_id field. In that case, the filter object would have a category_id property instead of product_id, and you can set the collection variable to "categories".

</Note>

Step 5: Create Payload Product Workflow

In this step, you'll create the functionality to create a Medusa product in Payload. You'll later execute that functionality either when triggered by an admin user, or automatically when a product is created in Medusa.

You create custom commerce features in workflows. A workflow is a series of queries and actions, called steps, that complete a task. A workflow is similar to a function, but it allows you to track its executions' progress, define roll-back logic, and configure other advanced features.

<Note>

Refer to the Workflows documentation to learn more.

</Note>

The workflow to create a Payload product will have the following steps:

You only need to create the createPayloadItemsStep, as the other two steps are already available in Medusa.

createPayloadItemsStep

The createPayloadItemsStep will create an item in a Payload collection, such as Products.

To create the step, create the file src/workflows/steps/create-payload-items.ts with the following content:

<Note>

If you get a type error on resolving the Payload Module, run the Medusa application once with the npm run dev or yarn dev command to generate the necessary type definitions, as explained in the Automatically Generated Types guide.

</Note>

export const createPayloadItemsStepHighlights = [ ["13", "payloadModuleService", "Resolve the Payload Module's service from the Medusa container."], ["15", "createdItems", "Create items in Payload."], ["23", "items", "Return the created items."], ["25", "ids", "Pass the IDs of the created items to the compensation function."], ["37", "delete", "Delete the created items from Payload if an error occurs."], ]

import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import { PayloadUpsertData } from "../../modules/payload/types"
import { PAYLOAD_MODULE } from "../../modules/payload"

type StepInput = {
  collection: string
  items: PayloadUpsertData[]
}

export const createPayloadItemsStep = createStep(
  "create-payload-items",
  async ({ items, collection }: StepInput, { container }) => {
    const payloadModuleService = container.resolve(PAYLOAD_MODULE)
    
    const createdItems = await Promise.all(
      items.map(async (item) => await payloadModuleService.create(
        collection,
        item
      ))
    )

    return new StepResponse({
      items: createdItems.map((item) => item.doc),
    }, {
      ids: createdItems.map((item) => item.doc.id),
      collection,
    })
  },
  async (data, { container }) => {
    if (!data) {
      return
    }
    const { ids, collection } = data

    const payloadModuleService = container.resolve(PAYLOAD_MODULE)

    await payloadModuleService.delete(
      collection,
      {
        where: {
          id: {
            in: ids.join(","),
          },
        },
      }
    )
  }
)

You create a step with the createStep function. It accepts three parameters:

The step's unique name.
An async function that receives two parameters:
- The step's input, which is an object holding the collection slug and an array of items to create in Payload.
- An object that has properties including the Medusa container, which is a registry of Framework and commerce tools that you can access in the step.
An async compensation function that undoes the actions performed by the step function. This function is only executed if an error occurs during the workflow's execution.

In the step function, you resolve the Payload Module's service from the container. Then, you use its create method to create the items in Payload.

A step function must return a StepResponse instance. The StepResponse constructor accepts two parameters:

The step's output, which is an object that contains the created items.
Data to pass to the step's compensation function.

In the compensation function, you again resolve the Payload Module's service from the Medusa container, then delete the created items from Payload.

Create Payload Product Workflow

You can now create the workflow that creates products in Payload.

To create the workflow, create the file src/workflows/create-payload-products.ts with the following content:

export const createPayloadProductsWorkflowHighlights = [ ["12", "useQueryGraphStep", "Retrieve the products from Medusa using Query."], ["36", "createData", "Prepare the data to create the products in Payload."], ["66", "createPayloadItemsStep", "Create the products in Payload."], ["81", "updateProductsWorkflow", "Update the products in Medusa with the Payload product IDs."], ]

import { createWorkflow, transform, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { createPayloadItemsStep } from "./steps/create-payload-items"
import { updateProductsWorkflow, useQueryGraphStep } from "@medusajs/medusa/core-flows"

type WorkflowInput = {
  product_ids: string[]
}

export const createPayloadProductsWorkflow = createWorkflow(
  "create-payload-products",
  (input: WorkflowInput) => {
    const { data: products } = useQueryGraphStep({
      entity: "product",
      fields: [
        "id",
        "title",
        "handle",
        "subtitle",
        "description",
        "created_at",
        "updated_at",
        "options.*",
        "variants.*",
        "variants.options.*",
        "thumbnail",
        "images.*",
      ],
      filters: {
        id: input.product_ids,
      },
      options: {
        throwIfKeyNotFound: true,
      },
    })

    const createData = transform({
      products,
    }, (data) => {
      return {
        collection: "products",
        items: data.products.map((product) => ({
          medusa_id: product.id,
          createdAt: product.created_at as string,
          updatedAt: product.updated_at as string,
          title: product.title,
          handle: product.handle,
          subtitle: product.subtitle,
          description: product.description || "",
          options: product.options.map((option) => ({
            title: option.title,
            medusa_id: option.id,
          })),
          variants: product.variants.map((variant) => ({
            title: variant.title,
            medusa_id: variant.id,
            option_values: variant.options.map((option) => ({
              medusa_id: option.id,
              medusa_option_id: option.option?.id,
              value: option.value,
            })),
          })),
        })),
      }
    })

    const { items } = createPayloadItemsStep(
      createData
    )

    const updateData = transform({
      items,
    }, (data) => {
      return data.items.map((item) => ({
        id: item.medusa_id,
        metadata: {
          payload_id: item.id,
        },
      }))
    })

    updateProductsWorkflow.runAsStep({
      input: {
        products: updateData,
      },
    })

    return new WorkflowResponse({
      items,
    })
  }
)

You create a workflow using the createWorkflow function. It accepts the workflow's unique name as a first parameter.

It accepts a second parameter: a constructor function that holds the workflow's implementation. The function accepts an input object holding the IDs of the products to create in Payload.

In the workflow, you:

Retrieve the products from Medusa using the useQueryGraphStep.
- This step uses Query to retrieve data across modules.
Prepare the data to create the products in Payload.
- To manipulate data in a workflow, you need to use the transform function. Learn more in the Data Manipulation documentation.
Create the products in Payload using the createPayloadItemsStep you created earlier.
Prepare the data to update the products in Medusa with the Payload product IDs.
- You store the payload ID in the metadata field of the Medusa product.
Update the products in Medusa using the updateProductsWorkflow.

A workflow must return an instance of WorkflowResponse that accepts the data to return to the workflow's executor.

You'll use this workflow in the next steps to create Medusa products in Payload.

Step 6: Trigger Product Creation in Payload

In this step, you'll allow Medusa Admin users to trigger the creation of Medusa products in Payload. To implement this, you'll create:

An API route that emits a products.sync-payload event.
A subscriber that listens to the products.sync-payload event and executes the createPayloadProductsWorkflow.
A setting page in the Medusa Admin that allows admin users to trigger the product creation in Payload.

a. Trigger Product Sync API Route

An API route is a REST endpoint that exposes functionalities to clients, such as storefronts and the Medusa Admin.

An API route is created in a route.ts file under a sub-directory of the src/api directory. The path of the API route is the file's path relative to src/api.

<Note>

Refer to the API routes to learn more about them.

</Note>

Create the file src/api/admin/payload/sync/[collection]/route.ts with the following content:

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const POST = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const { collection } = req.params
  const eventModuleService = req.scope.resolve("event_bus")

  await eventModuleService.emit({
    name: `${collection}.sync-payload`,
    data: {},
  })

  return res.status(200).json({
    message: `Syncing ${collection} with Payload`,
  })
}

Since you export a POST route handler function, you're exposing a POST API route at /admin/payload/sync/[collection], where [collection] is a path parameter that represents the collection slug in Payload.

In the function, you resolve the Event Module's service and emit a {collection}.sync-payload event, where {collection} is the collection slug passed in the request.

Finally, you return a success response with a message indicating that the collection is being synced with Payload.

b. Create Subscriber for the Event

Next, you'll create a subscriber that listens to the products.sync-payload event and executes the createPayloadProductsWorkflow.

A subscriber is an asynchronous function that is executed whenever its associated event is emitted.

<Note>

Refer to the Subscribers documentation to learn more about subscribers.

</Note>

To create a subscriber, create the file src/subscribers/products-sync-payload.ts with the following content:

export const productsSyncPayloadSubscriberHighlights = [ ["15", "products", "Retrieve paginated products from Medusa."], ["31", "filteredProducts", "Filter out the products that are already linked to Payload."], ["37", "createPayloadProductsWorkflow", "Execute the workflow to create products in Payload."] ]

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { createPayloadProductsWorkflow } from "../workflows/create-payload-products"

export default async function productSyncPayloadHandler({
  container,
}: SubscriberArgs) {
  const query = container.resolve("query")

  const limit = 1000
  let offset = 0
  let count = 0
  
  do {
    const { 
      data: products,
      metadata: { count: totalCount } = {},
    } = await query.graph({
      entity: "product",
      fields: [
        "id",
        "metadata",
      ],
      pagination: {
        take: limit,
        skip: offset,
      },
    })

    count = totalCount || 0
    offset += limit
    const filteredProducts = products.filter((product) => !product.metadata?.payload_id)

    if (filteredProducts.length === 0) {
      break
    }

    await createPayloadProductsWorkflow(container)
      .run({
        input: {
          product_ids: filteredProducts.map((product) => product.id),
        },
      })

  } while (count > offset + limit)
}

export const config: SubscriberConfig = {
  event: "products.sync-payload",
}

A subscriber file must export:

An asynchronous function, which is the subscriber function that is executed when the event is emitted.
A configuration object that defines the event the subscriber listens to.

In the subscriber, you use Query to retrieve all products from Medusa.

Then, you filter the products to only include those that don't have a payload product ID set in product.metadata.payload_id, and you execute the createPayloadProductsWorkflow with the filtered products' IDs.

Whenever the products.sync-payload event is emitted, the subscriber will be executed, which will create the products in Payload.

c. Create Setting Page in Medusa Admin

Next, you'll create a setting page in the Medusa Admin that allows admin users to trigger syncing products with Payload.

Initialize JS SDK

To send requests from your Medusa Admin customizations to the Medusa server, you need to initialize the JS SDK.

Create the file src/admin/lib/sdk.ts with the following content:

import Medusa from "@medusajs/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

Refer to the JS SDK documentation to learn more about initializing the SDK.

Create the Setting Page

A setting page is a UI route that adds a custom page to the Medusa Admin under the Settings section. The UI route is a React component that renders the page's content.

<Note>

Refer to the UI Routes documentation to learn more.

</Note>

To create the setting page, create the file src/admin/routes/settings/payload/page.tsx with the following content:

tsx

import { defineRouteConfig } from "@medusajs/admin-sdk"
import { Button, Container, Heading, toast } from "@medusajs/ui"
import { useMutation } from "@tanstack/react-query"
import { sdk } from "../../../lib/sdk"

const PayloadSettingsPage = () => {
  const { 
    mutateAsync: syncProductsToPayload,
    isPending: isSyncingProductsToPayload,
  } = useMutation({
    mutationFn: (collection: string) => 
      sdk.client.fetch(`/admin/payload/sync/${collection}`, {
        method: "POST",
      }),
    onSuccess: () => toast.success(`Triggered syncing collection data with Payload`),
  })

  return (
    <Container className="divide-y p-0">
      <div className="flex items-center justify-between px-6 py-4">
        <Heading level="h1">Payload Settings</Heading>
      </div>
      <div className="flex flex-col gap-4 px-6 py-4">
        <p>
          This page allows you to trigger syncing your Medusa data with Payload. It
          will only create items not in Payload.
        </p>
        <Button
          variant="primary"
          onClick={() => syncProductsToPayload("products")}
          isLoading={isSyncingProductsToPayload}
        >
          Sync Products to Payload
        </Button>
      </div>
    </Container>
  )
}

export const config = defineRouteConfig({
  label: "Payload",
})

export default PayloadSettingsPage

A settings page file must export:

A React component that renders the page. This is the file's default export.
A configuration object created with the defineRouteConfig function. It accepts an object with properties that define the page's configuration, such as its sidebar label.

In the page's component, you define a mutation function using Tanstack Query and the JS SDK. This function will send a POST request to the API route you created earlier to trigger syncing products with Payload.

Then, you render a button that, when clicked, calls the mutation function to trigger the syncing process.

d. Test Product Syncing

You can now test syncing products from Medusa to Payload. To do that:

Start your Medusa application with the following command:

bash

npm run dev

Run the Next.js Starter Storefront with the command:

bash

npm run dev

Open the Medusa Admin at localhost:9000/app and log in with your admin user.
Go to Settings -> Payload.
On the setting page, click the "Sync Products to Payload" button.

You'll see a success message indicating that the products are being synced with Payload. You can also confirm that the event was triggered by checking the Medusa server logs for the following message:

bash

info:    Processing products.sync-payload which has 1 subscribers

To check that the products were created in Payload, open the Payload admin at localhost:8000/admin and go to "Products" from the sidebar. You should see your Medusa products listed there.

If you click on a product, you can edit its details, such as its title or description.

Step 7: Automatically Create Product in Payload

In this step, you'll handle the product.created event to automatically create a product in Payload whenever a product is created in Medusa.

You already have the workflow to create a product in Payload, so you only need to create a subscriber that listens to the product.created event and executes the createPayloadProductsWorkflow.

Create the file src/subscribers/product-created.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { createPayloadProductsWorkflow } from "../workflows/create-payload-products"

export default async function productCreatedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await createPayloadProductsWorkflow(container)
    .run({
      input: {
        product_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product.created",
}

This subscriber listens to the product.created event and executes the createPayloadProductsWorkflow with the created product's ID.

Test Automatic Product Creation

To test out the automatic product creation in Payload, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, create a product in Medusa using the Medusa Admin. If you check the Products collection in the Payload admin, you should see the newly created product there as well.

Step 8: Customize Storefront to Display Payload Products

Now that you've integrated Payload with Medusa, you can customize the Next.js Starter Storefront to display product content from Payload. By doing so, you can show product content and assets that are optimized for the storefront.

In this step, you'll customize the Next.js Starter Storefront to show the product title, description, images, and option values from Payload.

a. Fetch Payload Data with Product Data

When you fetch product data in the Next.js Starter Storefront from the Medusa server, you can also retrieve the linked product data from Payload.

To do this, go to src/lib/data/products.ts in your Next.js Starter Storefront. You'll find a listProducts function that uses the JS SDK to fetch products from the Medusa server.

Find the sdk.client.fetch call and add *payload_product to the fields query parameter:

export const listProducts = async ({
  // ...
}: {
  //...
}): Promise<{
  // ...
}> => {
  // ...
  return sdk.client
    .fetch<{ products: HttpTypes.StoreProduct[]; count: number }>(
      `/store/products`,
      {
        method: "GET",
        query: {
          limit,
          offset,
          region_id: region?.id,
          fields:
            "*variants.calculated_price,+variants.inventory_quantity,+metadata,+tags,*payload_product",
          ...queryParams,
        },
        headers,
        next,
        cache: "force-cache",
      }
    )
  // ...
}

Passing this field is possible because you defined the virtual read-only link between the Product model in Medusa and the Products collection in Payload.

Medusa will now return the payload data of a product from Payload and include it in the payload_product field of the product object.

b. Define Payload Product Type

Next, you'll define a TypeScript type that adds the payload_product property to Medusa's StoreProduct type.

In src/types/global.ts, add the following imports at the top of the file:

import { StoreProduct } from "@medusajs/types"
// @ts-ignore
import type { SerializedEditorState } from "@payloadcms/richtext-lexical/lexical"

Then, add the following type definition at the end of the file:

export type StoreProductWithPayload = StoreProduct & {
  payload_product?: {
    medusa_id: string
    title: string
    handle: string
    subtitle?: string
    description?: SerializedEditorState
    thumbnail?: {
      id: string
      url: string
    }
    images: {
      id: string
      image: {
        id: string
        url: string
      }
    }[]
    options: {
      medusa_id: string
      title: string
    }[]
    variants: {
      medusa_id: string
      title: string
      option_values: {
        medusa_option_id: string
        value: string
      }[]
    }[]
  }
}

The StoreProductWithPayload type extends the StoreProduct type from Medusa and adds the payload_product property. This property contains the product data from Payload, including its title, description, images, options, and variants.

c. Display Payload Product Title and Description

Next, you'll customize the product details page to display the product title and description from Payload.

To do that, you need to customize the ProductInfo component in src/modules/products/templates/product-info/index.tsx.

First, add the following import statement at the top of the file:

tsx

import { StoreProductWithPayload } from "../../../../types/global"
// @ts-ignore
import { RichText } from "@payloadcms/richtext-lexical/react"

Then, change the type of the product prop to StoreProductWithPayload:

tsx

type ProductInfoProps = {
  product: StoreProductWithPayload
}

Next, find in the ProductInfo component's return statement where the product title is displayed and replace it with the following:

tsx

return (
  <div id="product-info">
    <div className="flex flex-col...">
      <Heading
        level="h2"
        className="text-3xl leading-10 text-ui-fg-base"
        data-testid="product-title"
      >
        {product?.payload_product?.title || product.title}
      </Heading>
    </div>
  </div>
)

Also, find where the product description is displayed and replace it with the following:

tsx

return (
  <div id="product-info">
    <div className="flex flex-col...">
      {product?.payload_product?.description !== undefined && 
        <RichText data={product.payload_product.description} />
      }
      
      {product?.payload_product?.description === undefined && (
        <Text
          className="text-medium text-ui-fg-subtle whitespace-pre-line"
          data-testid="product-description"
        >
          {product.description}
        </Text>
      )}
    </div>
  </div>
)

If the product has a description in Payload, it will be displayed using Payload's RichText component, which renders the rich text content. Otherwise, it will display the product description from Medusa.

d. Display Payload Product Images

Next, you'll display the product images from Payload in the product details page and in the product preview component that is shown in the product list.

Add Image Utility Functions

You'll first create utility functions useful for retrieving the images of a product.

Create the file src/lib/util/payload-images.ts with the following content:

import { StoreProductWithPayload } from "../../types/global"

export function getProductImages(product: StoreProductWithPayload) {
  return product?.payload_product?.images?.map((image) => ({
    id: image.id,
    url: formatPayloadImageUrl(image.image.url),
  })) || product.images || []
}

export function formatPayloadImageUrl(url: string): string {
  return url.replace(/^\/api\/media\/file/, "")
}

You define two functions:

getProductImages: This function accepts a product and returns either the images from Payload or the images from Medusa if the product doesn't have images in Payload.
formatPayloadImageUrl: This function formats the image URL from Payload by removing the /api/media/file prefix, which is not needed for displaying the image in the storefront.

Update ImageGallery Props

Next, you'll update the type of the ImageGallery component's props to receive an array of objects rather than an array of Medusa images. This ensures the component can accept images from Payload.

In src/modules/products/components/image-gallery/index.tsx, update the ImageGalleryProps type to the following:

tsx

type ImageGalleryProps = {
  images: {
    id: string
    url: string
  }[]
}

The ImageGallery component can now accept an array of image objects, each with an id and a url.

Display Images in Product Details Page

To display the product images in the product details page, add the following imports at the top of src/modules/products/templates/index.tsx:

tsx

import { StoreProductWithPayload } from "../../../types/global"
import { getProductImages } from "../../../lib/util/payload-images"

Next, change the type of the product prop to StoreProductWithPayload:

tsx

type ProductTemplateProps = {
  product: StoreProductWithPayload
  // ...
}

Then, add the following before the ProductTemplate component's return statement:

tsx

const ProductTemplate: React.FC<ProductTemplateProps> = ({
  product,
  region,
  countryCode,
}) => {
  // ...
  const productImages = getProductImages(product)
  // ...
}

You retrieve the images to display using the getProductImages function you created earlier.

Finally, update the images prop of the ImageGallery component in the return statement:

tsx

return (
  <>
    <ImageGallery images={productImages} />
  </>
)

The images on the product's details page will now be the images from Payload if available, or the images from Medusa if not.

Display Images in Product Preview

To display the product images in the product preview component that is displayed in the product list, add the following imports at the top of src/modules/products/components/product-preview/index.tsx:

tsx

import { StoreProductWithPayload } from "../../../../types/global"
import { formatPayloadImageUrl, getProductImages } from "../../../../lib/util/payload-images"

Then, change the type of the product prop to StoreProductWithPayload:

tsx

export default async function ProductPreview({
  product,
  // ...
}: {
  product: StoreProductWithPayload
  // ...
}) {
  // ...
}

Next, add the following before the return statement:

tsx

export default async function ProductPreview({
  // ...
}: {
  // ...
}) {
  // ...

  const productImages = getProductImages(product)

  // ...
}

You retrieve the images to display using the getProductImages function you created earlier.

After that, update the thumbnail and images props of the Thumbnail component in the return statement:

tsx

return (
  <LocalizedClientLink href={`/products/${product.handle}`} className="group">
    <Thumbnail
      thumbnail={product.payload_product?.thumbnail ? 
        formatPayloadImageUrl(product.payload_product.thumbnail.url) : 
        product.thumbnail
      }
      images={productImages}
      size="full"
      isFeatured={isFeatured}
    />
  </LocalizedClientLink>
)

The thumbnail shown in the product listing will now use the thumbnail from Payload if available, or the thumbnail from Medusa if not.

You'll also display the product title from Payload in the product preview. Find the following lines in the return statement:

tsx

return (
  <LocalizedClientLink href={`/products/${product.handle}`} className="group">
    <Text className="text-ui-fg-subtle" data-testid="product-title">
      {product.title}
    </Text>
  </LocalizedClientLink>
)

And replace them with the following:

tsx

return (
  <LocalizedClientLink href={`/products/${product.handle}`} className="group">
    <Text className="text-ui-fg-subtle" data-testid="product-title">
      {product.payload_product?.title || product.title}
    </Text>
  </LocalizedClientLink>
)

The product title in the product preview will now be the title from Payload if available, or the title from Medusa if not.

e. Display Product Options and Values

The last change you'll make is to display the title of product options and their values from Payload in the product details page.

In src/modules/products/components/product-actions/index.tsx, add the following import at the top of the file:

tsx

import { StoreProductWithPayload } from "../../../../types/global"

Then, change the type of the product prop to StoreProductWithPayload:

tsx

type ProductActionsProps = {
  product: StoreProductWithPayload
  // ...
}

Next, find the optionsAsKeymap function and replace it with the following:

tsx

const optionsAsKeymap = (
  variantOptions: HttpTypes.StoreProductVariant["options"],
  payloadData: StoreProductWithPayload["payload_product"]
) => {
  const firstVariant = payloadData?.variants?.[0]
  return variantOptions?.reduce((acc: Record<string, string>, varopt: any) => {
    acc[varopt.option_id] = firstVariant?.option_values.find(
      (v) => v.medusa_option_id === varopt.id
    )?.value || varopt.value
    return acc
  }, {})
}

You update the function to receive a payloadData parameter, which is the product data from Payload. This allows you to retrieve the option values from Payload instead of Medusa.

Then, in the ProductActions component, update all usages of the optionsAsKeymap function to pass the product.payload_product data:

tsx

// update all usages of optionsAsKeymap
const variantOptions = optionsAsKeymap(
  product.variants[0].options,
  product.payload_product
)

Finally, in the return statement, find the loop over product.options and replace it with the following:

export const productActionsComponentHighlights = [ ["5", "payloadOption", "Retrieve the Payload option data if available."], ["14", "title", "Use the Payload option title if available, otherwise use the Medusa option title."] ]

tsx

return (
  <>
    {(product.options || []).map((option) => {
      const payloadOption = product.payload_product?.options?.find(
        (o) => o.medusa_id === option.id
      )
      return (
        <div key={option.id}>
          <OptionSelect
            option={option}
            current={options[option.id]}
            updateOption={setOptionValue}
            title={payloadOption?.title || option.title || ""}
            data-testid="product-options"
            disabled={!!disabled || isAdding}
          />
        </div>
      )
    })}
  </>
)

You change the title prop of the OptionSelect component to use the title from Payload if available, or the Medusa option title if not.

Now, the product options and values will be displayed using the data from Payload, if available.

Test Storefront Customization

To test out the storefront customization, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the storefront at localhost:8000 and click on Menu -> Store. In the products listing page, you'll see thumbnails and titles of the products from Payload.

If you click on a product, you'll see the product details page with the product title, description, images, and options from Payload.

Step 9: Handle Medusa Product Events

In this step, you'll create subscribers and workflows to handle the following Medusa product events:

product.deleted: Delete the product in Payload when a product is deleted in Medusa.
product-variant.created: Add a product variant to a product in Payload when a product variant is created in Medusa.
product-variant.updated: Update a product variant's option values in Payload when a product variant is updated in Medusa.
product-variant.deleted: Remove a product's variant in Payload when a product variant is deleted in Medusa.
product-option.created: Add a product option to a product in Payload when a product option is created in Medusa.
product-option.deleted: Remove a product's option in Payload when a product option is deleted in Medusa.

a. Handle Product Deletions

To handle the product.deleted event, you'll create a workflow that deletes the product from Payload, then create a subscriber that executes the workflow when the event is emitted.

The workflow will have the following steps:

deletePayloadItemsStep

First, you need to create the deletePayloadItemsStep that allows you to delete items from a Payload collection.

Create the file src/workflows/steps/delete-payload-items.ts with the following content:

import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import { PAYLOAD_MODULE } from "../../modules/payload"

type StepInput = {
  collection: string;
  where: Record<string, any>;
}

export const deletePayloadItemsStep = createStep(
  "delete-payload-items",
  async ({ where, collection }: StepInput, { container }) => {
    const payloadModuleService = container.resolve(PAYLOAD_MODULE)

    const prevData = await payloadModuleService.find(collection, {
      where,
    })

    await payloadModuleService.delete(collection, {
      where,
    })

    return new StepResponse({}, {
      prevData,
      collection,
    })
  },
  async (data, { container }) => {
    if (!data) {
      return
    }
    const { prevData, collection } = data

    const payloadModuleService = container.resolve(PAYLOAD_MODULE)

    for (const item of prevData.docs) {
      await payloadModuleService.create(
        collection,
        item
      )
    }
  }
)

This step accepts a collection slug and a where condition to specify which items to delete from Payload.

In the step, you first retrieve the existing items that match the where condition using the find method in the Payload Module's service. You pass these items to the compensation function so that you can restore them if an error occurs in the workflow.

Then, you delete the items using the delete method of the Payload Module's service.

Delete Payload Products Workflow

Next, to create the workflow that deletes products from Payload, create the file src/workflows/delete-payload-products.ts with the following content:

import { createWorkflow, transform, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { deletePayloadItemsStep } from "./steps/delete-payload-items"

type WorkflowInput = {
  product_ids: string[]
}

export const deletePayloadProductsWorkflow = createWorkflow(
  "delete-payload-products",
  ({ product_ids }: WorkflowInput) => {
    const deleteProductsData = transform({
      product_ids,
    }, (data) => {
      return {
        collection: "products",
        where: {
          medusa_id: {
            in: data.product_ids.join(","),
          },
        },
      }
    })

    deletePayloadItemsStep(deleteProductsData)

    return new WorkflowResponse(void 0)
  }
)

This workflow receives the IDs of the products to delete from Payload.

In the workflow, you prepare the data to delete from Payload using the transform function, then call the deletePayloadItemsStep to delete the products from Payload where the medusa_id matches one of the provided product IDs.

Product Deleted Subscriber

Finally, you'll create the subscriber that executes the workflow when the product.deleted event is emitted.

Create the file src/subscribers/product-deleted.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { deletePayloadProductsWorkflow } from "../workflows/delete-payload-products"

export default async function productDeletedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await deletePayloadProductsWorkflow(container)
    .run({
      input: {
        product_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product.deleted",
}

This subscriber listens to the product.deleted event and executes the deletePayloadProductsWorkflow with the deleted product's ID.

Test Product Deletion Handling

To test the product deletion handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and go to the products list. Delete a product that exists in Payload.

If you check the Products collection in Payload, you should see that the product has been removed from there as well.

b. Handle Product Variant Creation

To handle the product-variant.created event, you'll create a workflow that adds the new variant to the corresponding product in Payload.

The workflow will have the following steps:

You only need to create the updatePayloadItemsStep step.

updatePayloadItemsStep

The updatePayloadItemsStep will update an item in a Payload collection, such as Products.

To create the step, create the file src/workflows/steps/update-payload-items.ts with the following content:

import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import { PayloadItemResult, PayloadUpsertData } from "../../modules/payload/types"
import { PAYLOAD_MODULE } from "../../modules/payload"

type StepInput = {
  collection: string;
  items: PayloadUpsertData[];
}

export const updatePayloadItemsStep = createStep(
  "update-payload-items",
  async ({ items, collection }: StepInput, { container }) => {
    const payloadModuleService = container.resolve(PAYLOAD_MODULE)
    const ids: string[] = items.map((item) => item.id)

    const prevData = await payloadModuleService.find(collection, {
      where: {
        id: {
          in: ids.join(","),
        },
      },
    })

    const updatedItems: PayloadItemResult[] = []

    for (const item of items) {
      const { id, ...data } = item
      updatedItems.push(
        await payloadModuleService.update(
          collection,
          data,
          {
            where: {
              id: {
                equals: id,
              },
            },
          }
        )
      )
    }

    return new StepResponse({
      items: updatedItems.map((item) => item.doc),
    }, {
      prevData,
      collection,
    })
  },
  async (data, { container }) => {
    if (!data) {
      return
    }
    const { prevData, collection } = data

    const payloadModuleService = container.resolve(PAYLOAD_MODULE)

    await Promise.all(
      prevData.docs.map(async ({
        id,
        ...item
      }) => {
        await payloadModuleService.update(
          collection,
          item,
          {
            where: {
              id: {
                equals: id,
              },
            },
          }
        )
      })
    )
  }
)

In the step function, you retrieve the existing data from Payload to pass it to the compensation function. Then, you update the items in Payload.

In the compensation function, you revert the changes made in the step function if an error occurs.

Create Payload Product Variant Workflow

Create the file src/workflows/create-payload-product-variant.ts with the following content:

import { createWorkflow, transform, when, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { PayloadCollectionItem, PayloadUpsertData } from "../modules/payload/types"
import { updatePayloadItemsStep } from "./steps/update-payload-items"

type WorkflowInput = {
  variant_ids: string[]; 
}

export const createPayloadProductVariantWorkflow = createWorkflow(
  "create-payload-product-variant",
  ({ variant_ids }: WorkflowInput) => {
    const { data: productVariants } = useQueryGraphStep({
      entity: "product_variant",
      fields: [
        "id",
        "title",
        "options.*",
        "options.option.*",
        "product.payload_product.*",
      ],
      filters: {
        id: variant_ids,
      },
      options: {
        throwIfKeyNotFound: true,
      },
    })

    const updateData = transform({
      productVariants,
    }, (data) => {
      const items: Record<string, PayloadUpsertData> = {}

      data.productVariants.forEach((variant) => {
        // @ts-expect-error
        const payloadProduct = variant.product?.payload_product as PayloadCollectionItem
        if (!payloadProduct) {return}
        if (!items[payloadProduct.id]) {
          items[payloadProduct.id] = {
            variants: payloadProduct.variants || [],
          }
        }

        items[payloadProduct.id].variants.push({
          title: variant.title,
          medusa_id: variant.id,
          option_values: variant.options.map((option) => ({
            medusa_id: option.id,
            medusa_option_id: option.option?.id,
            value: option.value,
          })),
        })
      })
      
      return {
        collection: "products",
        items: Object.keys(items).map((id) => ({
          id,
          ...items[id],
        })),
      }
    })

    const result = when({ updateData }, (data) => data.updateData.items.length > 0)
      .then(() => {
        return updatePayloadItemsStep(updateData)
      })

    const items = transform({ result }, (data) => data.result?.items || [])

    return new WorkflowResponse({
      items,
    })
  }
)

This workflow receives the IDs of the product variants to add to Payload.

In the workflow, you:

Retrieve the product variant details from Medusa using the useQueryGraphStep, including the linked product data from Payload.
Prepare the data to update the product in Payload by adding the new variant to the existing variants array.
Update the product in Payload using the updatePayloadItemsStep if there are any items to update.
Return the updated items from the workflow.

Product Variant Created Subscriber

Finally, you'll create the subscriber that executes the workflow when the product-variant.created event is emitted.

Create the file src/subscribers/variant-created.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { createPayloadProductVariantWorkflow } from "../workflows/create-payload-product-variant"

export default async function productVariantCreatedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await createPayloadProductVariantWorkflow(container)
    .run({
      input: {
        variant_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product-variant.created",
}

This subscriber listens to the product-variant.created event and executes the createPayloadProductVariantWorkflow with the created variant's ID.

Test Product Variant Creation Handling

To test the product variant creation handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and open a product's details page. Add a new variant to the product and save the changes.

If you check the product in Payload, you should see that the new variant has been added to the product's variants array.

c. Handle Product Variant Updates

To handle the product-variant.updated event, you'll create a workflow that updates the variant in the corresponding product in Payload.

The workflow will have the following steps:

Update Payload Product Variants Workflow

Since you already have the necessary steps, you only need to create the workflow that uses these steps.

Create the file src/workflows/update-payload-product-variants.ts with the following content:

import { createWorkflow, transform, when, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { PayloadCollectionItem, PayloadUpsertData } from "../modules/payload/types"
import { updatePayloadItemsStep } from "./steps/update-payload-items"

type WorkflowInput = {
  variant_ids: string[]; 
}

export const updatePayloadProductVariantsWorkflow = createWorkflow(
  "update-payload-product-variants",
  ({ variant_ids }: WorkflowInput) => {
    const { data: productVariants } = useQueryGraphStep({
      entity: "product_variant",
      fields: [
        "id",
        "title",
        "options.*",
        "options.option.*",
        "product.payload_product.*",
      ],
      filters: {
        id: variant_ids,
      },
      options: {
        throwIfKeyNotFound: true,
      },
    })

    const updateData = transform({
      productVariants,
    }, (data) => {
      const items: Record<string, PayloadUpsertData> = {}

      data.productVariants.forEach((variant) => {
        // @ts-expect-error
        const payloadProduct = variant.product?.payload_product as PayloadCollectionItem
        if (!payloadProduct) {return}
        
        if (!items[payloadProduct.id]) {
          items[payloadProduct.id] = {
            variants: payloadProduct.variants || [],
          }
        }

        // Find and update the existing variant in the payload product
        const existingVariantIndex = items[payloadProduct.id].variants.findIndex(
          (v: any) => v.medusa_id === variant.id
        )

        if (existingVariantIndex >= 0) {
          // check if option values need to be updated
          const existingVariant = items[payloadProduct.id].variants[existingVariantIndex]
          const updatedOptionValues = variant.options.map((option) => ({
            medusa_id: option.id,
            medusa_option_id: option.option?.id,
            value: existingVariant.option_values.find((ov: any) => ov.medusa_id === option.id)?.value || 
              option.value,
          }))

          items[payloadProduct.id].variants[existingVariantIndex] = {
            ...existingVariant,
            option_values: updatedOptionValues,
          }
        } else {
          // Add the new variant to the payload product
          items[payloadProduct.id].variants.push({
            title: variant.title,
            medusa_id: variant.id,
            option_values: variant.options.map((option) => ({
              medusa_id: option.id,
              medusa_option_id: option.option?.id,
              value: option.value,
            })),
          })
        }
      })
      
      return {
        collection: "products",
        items: Object.keys(items).map((id) => ({
          id,
          ...items[id],
        })),
      }
    })

    const result = when({ updateData }, (data) => data.updateData.items.length > 0)
      .then(() => {
        return updatePayloadItemsStep(updateData)
      })

    const items = transform({ result }, (data) => data.result?.items || [])

    return new WorkflowResponse({
      items,
    })
  }
)

This workflow receives the IDs of the product variants to update in Payload.

In the workflow, you:

Retrieve the product variant details from Medusa using the useQueryGraphStep, including the linked product data from Payload.
Prepare the data to update the product in Payload by finding and updating the existing variant in the variants array. You only update the variant's option values, in case a new one is added.
Update the product in Payload using the updatePayloadItemsStep if there are any items to update.
Return the updated items from the workflow.

Product Variant Updated Subscriber

Finally, you'll create the subscriber that executes the workflow.

Create the file src/subscribers/variant-updated.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { updatePayloadProductVariantsWorkflow } from "../workflows/update-payload-product-variants"

export default async function productVariantUpdatedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await updatePayloadProductVariantsWorkflow(container)
    .run({
      input: {
        variant_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product-variant.updated",
}

This subscriber listens to the product-variant.updated event and executes the updatePayloadProductVariantsWorkflow with the updated variant's ID.

Test Product Variant Update Handling

To test the product variant update handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and open a product's details page. Edit an existing variant's title and save the changes.

If you check the product in Payload, you should see that the variant's option values have been updated in the product's variants array.

d. Handle Product Variant Deletions

To handle the product-variant.deleted event, you'll create a workflow that removes the variant from the corresponding product in Payload.

The workflow will have the following steps:

retrievePayloadItemsStep

Since the deletePayloadProductVariantsWorkflow is executed after a product variant is deleted, you can't retrieve the product variant data from Medusa.

Instead, you'll create a step that retrieves the products containing the variants from Payload. You'll then use this data to update the products in Payload.

To create the step, create the file src/workflows/steps/retrieve-payload-items.ts with the following content:

import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import { PAYLOAD_MODULE } from "../../modules/payload"

type StepInput = {
  collection: string;
  where: Record<string, any>;
}

export const retrievePayloadItemsStep = createStep(
  "retrieve-payload-items",
  async ({ where, collection }: StepInput, { container }) => {
    const payloadModuleService = container.resolve(PAYLOAD_MODULE)

    const items = await payloadModuleService.find(collection, {
      where,
    })

    return new StepResponse({
      items: items.docs,
    })
  }
)

This step accepts a collection slug and a where condition to specify which items to retrieve from Payload, then returns the found items.

Delete Payload Product Variants Workflow

To create the workflow, create the file src/workflows/delete-payload-product-variants.ts with the following content:

import { createWorkflow, transform, when, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { updatePayloadItemsStep } from "./steps/update-payload-items"
import { retrievePayloadItemsStep } from "./steps/retrieve-payload-items"

type WorkflowInput = {
  variant_ids: string[]
}

export const deletePayloadProductVariantsWorkflow = createWorkflow(
  "delete-payload-product-variants",
  ({ variant_ids }: WorkflowInput) => {
    const retrieveData = transform({
      variant_ids,
    }, (data) => {
      return {
        collection: "products",
        where: {
          "variants.medusa_id": {
            in: data.variant_ids.join(","),
          },
        },
      }
    })

    const { items: payloadProducts } = retrievePayloadItemsStep(retrieveData)

    const updateData = transform({
      payloadProducts,
      variant_ids,
    }, (data) => {
      const items = data.payloadProducts.map((payloadProduct) => ({
        id: payloadProduct.id,
        variants: payloadProduct.variants.filter((v: any) => !data.variant_ids.includes(v.medusa_id)),
      }))
      
      return {
        collection: "products",
        items,
      }
    })

    const result = when({ updateData }, (data) => data.updateData.items.length > 0)
      .then(() => {
        // Call the step to update the payload items
        return updatePayloadItemsStep(updateData)
      })

    const items = transform({ result }, (data) => data.result?.items || [])

    return new WorkflowResponse({
      items,
    })
  }
)

This workflow receives the IDs of the product variants to delete from Payload.

In the workflow, you:

Retrieve the Payload data of the products that the variants belong to using retrievePayloadItemsStep.
Prepare the data to update the products in Payload by filtering out the variants that should be deleted.
Update the products in Payload using the updatePayloadItemsStep if there are any items to update.
Return the updated items from the workflow.

Product Variant Deleted Subscriber

Finally, you'll create the subscriber that executes the workflow when the product-variant.deleted event is emitted.

Create the file src/subscribers/variant-deleted.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { deletePayloadProductVariantsWorkflow } from "../workflows/delete-payload-product-variants"

export default async function productVariantDeletedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await deletePayloadProductVariantsWorkflow(container)
    .run({
      input: {
        variant_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product-variant.deleted",
}

This subscriber listens to the product-variant.deleted event and executes the deletePayloadProductVariantsWorkflow with the deleted variant's ID.

Test Product Variant Deletion Handling

To test the product variant deletion handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and open a product's details page. Delete an existing variant from the product.

If you check the product in Payload, you should see that the variant has been removed from the product's variants array.

e. Handle Product Option Creation

To handle the product-option.created event, you'll create a workflow that adds the new option to the corresponding product in Payload.

The workflow will have the following steps:

Create Payload Product Options Workflow

You already have the necessary steps, so you only need to create the workflow that uses these steps.

Create the file src/workflows/create-payload-product-options.ts with the following content:

import { createWorkflow, transform, when, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { PayloadCollectionItem, PayloadUpsertData } from "../modules/payload/types"
import { updatePayloadItemsStep } from "./steps/update-payload-items"

type WorkflowInput = {
  option_ids: string[]; 
}

export const createPayloadProductOptionsWorkflow = createWorkflow(
  "create-payload-product-options",
  ({ option_ids }: WorkflowInput) => {
    const { data: productOptions } = useQueryGraphStep({
      entity: "product_option",
      fields: [
        "id",
        "title",
        "product.payload_product.*",
      ],
      filters: {
        id: option_ids,
      },
      options: {
        throwIfKeyNotFound: true,
      },
    })

    const updateData = transform({
      productOptions,
    }, (data) => {
      const items: Record<string, PayloadUpsertData> = {}

      data.productOptions.forEach((option) => {
        // @ts-expect-error
        const payloadProduct = option.product?.payload_product as PayloadCollectionItem
        if (!payloadProduct) {return}
        
        if (!items[payloadProduct.id]) {
          items[payloadProduct.id] = {
            options: payloadProduct.options || [],
          }
        }

        // Add the new option to the payload product
        const newOption = {
          title: option.title,
          medusa_id: option.id,
        }

        // Check if option already exists, if not add it
        const existingOptionIndex = items[payloadProduct.id].options.findIndex(
          (o: any) => o.medusa_id === option.id
        )
        
        if (existingOptionIndex === -1) {
          items[payloadProduct.id].options.push(newOption)
        }
      })
      
      return {
        collection: "products",
        items: Object.keys(items).map((id) => ({
          id,
          ...items[id],
        })),
      }
    })

    const result = when({ updateData }, (data) => data.updateData.items.length > 0)
      .then(() => {
        return updatePayloadItemsStep(updateData)
      })

    const items = transform({ result }, (data) => data.result?.items || [])

    return new WorkflowResponse({
      items,
    })
  }
)

This workflow receives the IDs of the product options to add to Payload.

In the workflow, you:

Retrieve the product option details from Medusa using the useQueryGraphStep, including the linked product data from Payload.
Prepare the data to update the product in Payload by adding the new option to the existing options array, checking if it doesn't already exist.
Update the product in Payload using the updatePayloadItemsStep if there are any items to update.
Return the updated items from the workflow.

Product Option Created Subscriber

Finally, you'll create the subscriber that executes the workflow when the product-option.created event is emitted.

Create the file src/subscribers/option-created.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { createPayloadProductOptionsWorkflow } from "../workflows/create-payload-product-options"

export default async function productOptionCreatedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await createPayloadProductOptionsWorkflow(container)
    .run({
      input: {
        option_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product-option.created",
}

This subscriber listens to the product-option.created event and executes the createPayloadProductOptionsWorkflow with the created option's ID.

Test Product Option Creation Handling

To test the product option creation handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and open a product's details page. Add a new option to the product and save the changes.

If you check the product in Payload, you should see that the new option has been added to the product's options array.

f. Handle Product Option Deletions

To handle the product-option.deleted event, you'll create a workflow that removes the option from the corresponding product in Payload.

The workflow will have the following steps:

Delete Payload Product Options Workflow

You already have the necessary steps, so you only need to create the workflow that uses these steps.

Create the file src/workflows/delete-payload-product-options.ts with the following content:

import { createWorkflow, transform, when, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { updatePayloadItemsStep } from "./steps/update-payload-items"
import { retrievePayloadItemsStep } from "./steps/retrieve-payload-items"

type WorkflowInput = {
  option_ids: string[]
}

export const deletePayloadProductOptionsWorkflow = createWorkflow(
  "delete-payload-product-options",
  ({ option_ids }: WorkflowInput) => {
    const retrieveData = transform({
      option_ids,
    }, (data) => {
      return {
        collection: "products",
        where: {
          "options.medusa_id": {
            in: data.option_ids.join(","),
          },
        },
      }
    })

    const { items: payloadProducts } = retrievePayloadItemsStep(retrieveData)

    const updateData = transform({
      payloadProducts,
      option_ids,
    }, (data) => {
      const items = data.payloadProducts.map((payloadProducts) => ({
        id: payloadProducts.id,
        options: payloadProducts.options.filter((o: any) => !data.option_ids.includes(o.medusa_id)),
        variants: payloadProducts.variants.map((variant: any) => ({
          ...variant,
          option_values: variant.option_values.filter((ov: any) => !data.option_ids.includes(ov.medusa_option_id)),
        })),
      }))
      
      return {
        collection: "products",
        items,
      }
    })

    const result = when({ updateData }, (data) => data.updateData.items.length > 0)
      .then(() => {
        return updatePayloadItemsStep(updateData)
      })

    const items = transform({ result }, (data) => data.result?.items || [])

    return new WorkflowResponse({
      items,
    })
  }
)

This workflow receives the IDs of the product options to delete from Payload.

In the workflow, you:

Retrieve the products that contain the options to be deleted using the retrievePayloadItemsStep.
Prepare the data to update the products in Payload by filtering out the options that should be deleted.
Update the products in Payload using the updatePayloadItemsStep if there are any items to update.
Return the updated items from the workflow.

Product Option Deleted Subscriber

Finally, you'll create the subscriber that executes the workflow when the product-option.deleted event is emitted.

Create the file src/subscribers/option-deleted.ts with the following content:

import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { deletePayloadProductOptionsWorkflow } from "../workflows/delete-payload-product-options"

export default async function productOptionDeletedHandler({
  event: { data },
  container,
}: SubscriberArgs<{
  id: string
}>) {
  await deletePayloadProductOptionsWorkflow(container)
    .run({
      input: {
        option_ids: [data.id],
      },
    })
}

export const config: SubscriberConfig = {
  event: "product-option.deleted",
}

This subscriber listens to the product-option.deleted event and executes the deletePayloadProductOptionsWorkflow with the deleted option's ID.

Test Product Option Deletion Handling

To test the product option deletion handling, make sure that both the Medusa application and the Next.js Starter Storefront are running.

Then, open the Medusa Admin at localhost:9000/app and open a product's details page. Delete an existing option from the product.

If you check the product in Payload, you should see that the option has been removed from the product's options array.

Next Steps

You've successfully integrated Medusa with Payload to manage content related to products, variants, and options. You can expand on this integration by adding more features, such as:

Managing the content of other entities, like categories or collections. The process is similar to what you've done for products:
1. Create a collection in Payload for the entity.
2. Create Medusa workflows and subscribers to handle the creation, update, and deletion of the entity.
3. Display the payload data in your Next.js Starter Storefront.
Enable localization in Payload to support multiple languages.
- You only need to manage the localized content in Payload. Only the default locale will be synced with Medusa.
- You can show the localized content in your Next.js Starter Storefront based on the customer's locale.
Add custom fields to the Payload collections that are relevant for the storefront, such as SEO metadata or promotional banners.

Learn More about Medusa

If you're new to Medusa, check out the main documentation, where you'll get a more in-depth understanding of all the concepts you've used in this guide and more.

To learn more about the commerce features that Medusa provides, check out Medusa's Commerce Modules.

Troubleshooting

If you encounter issues during your development, check out the troubleshooting guides.

Getting Help

If you encounter issues not covered in the troubleshooting guides:

Visit the Medusa GitHub repository to report issues or ask questions.
Join the Medusa Discord community for real-time support from community members.

{metadata.title}

{metadata.title}

Summary

Step 1: Install a Medusa Application

Step 2: Set Up Payload in the Next.js Starter Storefront

a. Install Dependencies

b. Add Resolution for undici

c. Copy Payload Template Files

d. Modify Next.js Middleware

e. Add Payload Configuration

f. Customize Next.js Configurations

g. Add Collections to Payload

User Collection

Media Collection

Product Collection

Add Validation for Options and Variants

Add Hooks to Normalize Product Data

Add Collections to Payload's Configurations

i. Generate Payload Imports Map

j. Run the Payload Admin

Step 3: Integrate Payload with Medusa

a. Create Module Directory

b. Create Types for the Module

c. Create Service

c. Add Methods to the Service

makeRequest Method

create Method

update Method

delete Method

find Method

d. Export Module Definition

e. Add Module to Medusa's Configurations

f. Set Environment Variables

Step 4: Create Virtual Read-Only Link to Products

a. Define the Link

b. Add list Method to the Payload Module Service

Step 5: Create Payload Product Workflow

createPayloadItemsStep

Create Payload Product Workflow

Step 6: Trigger Product Creation in Payload

a. Trigger Product Sync API Route

b. Create Subscriber for the Event

c. Create Setting Page in Medusa Admin

Initialize JS SDK

Create the Setting Page

d. Test Product Syncing

Step 7: Automatically Create Product in Payload

Test Automatic Product Creation

Step 8: Customize Storefront to Display Payload Products

a. Fetch Payload Data with Product Data

b. Define Payload Product Type

c. Display Payload Product Title and Description

d. Display Payload Product Images

Add Image Utility Functions

Update ImageGallery Props

Display Images in Product Details Page

Display Images in Product Preview

e. Display Product Options and Values

Test Storefront Customization

Step 9: Handle Medusa Product Events

a. Handle Product Deletions

deletePayloadItemsStep

Delete Payload Products Workflow

Product Deleted Subscriber

Test Product Deletion Handling

b. Handle Product Variant Creation

updatePayloadItemsStep

Create Payload Product Variant Workflow

Product Variant Created Subscriber

Test Product Variant Creation Handling

c. Handle Product Variant Updates

Update Payload Product Variants Workflow

Product Variant Updated Subscriber

Test Product Variant Update Handling

d. Handle Product Variant Deletions

retrievePayloadItemsStep

Delete Payload Product Variants Workflow

Product Variant Deleted Subscriber

Test Product Variant Deletion Handling

e. Handle Product Option Creation

b. Add Resolution for `undici`