Integrate Payload with Medusa

Today, we are making an official Medusa and Payload integration tutorial available to our community. The new tutorial lets you build storefronts with a best-of-both-worlds approach: Medusa for commerce logic and Payload for rich content management.

A powerful open-source commerce stack

Medusa gives you a digital commerce platform with a built-in Framework for customization. Payload gives your team a flexible CMS with rich editors, media handling, and localization. Plug them together to manage content in Payload while handling in Medusa catalog, pricing, variants, inventory, carts, and checkout. The official tutorial walks you through setup and shows how to sync data between the two systems.

• Sync product data with workflows and events: Medusa’s workflow engine and event system make it straightforward to keep Payload in step with product changes. The tutorial demonstrates both manual syncs and automatic syncs that run on product lifecycle events in Medusa. That means when a merchant creates a product, a Payload record is created right away. 
• Ship content-rich product pages: On your storefront, you can fetch a product from Medusa and, in the same call, retrieve its linked content from Payload. Use Payload’s rich text editor for long descriptions and its media library for images, while relying on Medusa for price, availability, and options.

How it works under the hood

• Virtual linking: Medusa’s framework supports virtual links between data models, including read-only links to external systems. You can represent a Payload record as a virtual data model and link it to a Medusa product. This lets you join across systems using Medusa’s Query without coupling modules or duplicating data. 
• One query for both: With a virtual link in place, the storefront or a workflow can request Copy to clipboardproduct and Copy to clipboardpayload_product together. Medusa resolves the link and returns a combined shape, so your UI can render editorial content and commercial attributes side by side with minimal client code. The Payload integration tutorial shows this pattern directly in the Next.js Starter Storefront.
• Workflows that keep everything in sync: Medusa’s durable workflows orchestrate cross-system operations. The workflows in the tutorial retrieve product and variant details from Medusa, prepare the Payload data, perform updates in Payload, and return results. This approach is resilient and easy to extend for categories, collections, or media. 

How to Integrate Payload with Medusa

In this step-by-step tutorial on integrating Payload with Medusa, you'll learn how to:

• Set up Payload in the Next.js Starter Storefront for your open source ecommerce project.
• Automate syncing product data from Medusa to Payload whenever product-related events occur.
• Customize the Next.js Starter Storefront to display product data from Payload.

By the end of the tutorial, you'll have the foundation to expand the integration by adding localization, managing data for other models like categories, and handling custom content fields in Payload. This approach enables developers to build a custom ecommerce backend using modern JavaScript frameworks and a flexible, self-hosted CMS.