Announcing the Loyalty Plugin for Medusa

The Loyalty Plugin is now open source and available as part of Medusa v2.14.0. It was previously only available to Medusa Cloud users. It ships with gift cards, gift card products, and store credit accounts, and it gives developers a foundation to build broader loyalty features on top of.

The plugin is built as two standalone Commerce Modules: the Loyalty Module and the Store Credit Module. They provide management features for merchants, and checkout features for customers.

Gift cards

Gift cards are unique codes you issue directly to customers. Each gift card holds a balance that customers can apply at checkout.

With gift cards, you can:

• Issue gift cards from the Medusa Admin
• Set a value, currency, and optional expiry date per card
• Allow customers to claim and redeem their gift card codes at checkout
• Track and manage all issued gift cards from a single view

Gift card products

Gift card products are purchasable storefront products that generate a gift card upon purchase. This lets customers buy and send gift cards, then redeem them during checkout.

Merchants can create a gift card product from the Medusa admin dashboard. Once customers purchase a gift card product, a gift card with a unique code will be generated for them.

Store credit accounts

Store credit accounts are balance accounts tied to individual customers. You can credit a customer's account directly, and customers can apply their balance at checkout.

With store credit accounts, you can:

• Create and manage store credit accounts per customer from the Medusa Admin
• Refund orders directly to a customer's store credit account instead of the original payment method
• Allow customers to claim and apply their store credit balance during checkout
• View full transaction history with credit and debit operations for each account

Installing the Loyalty Plugin

To use the loyalty plugin, make sure you have Medusa installed first.

Then, install the package with the following command:

12
npm install @medusajs/loyalty-plugin

After that, add it to your Copy to clipboardmedusa-config.js:

12345678910
// medusa-config.js
module.exports = defineConfig({
  plugins: [
    {
      resolve: `@medusajs/loyalty-plugin`,
      options: {},
    },
  ],
})

Finally, run migrations:

12
npx medusa db:migrate

When you run the Medusa application and log into your admin dashboard, you can see new pages for gift cards and store credit accounts.

Build Loyalty Features with Claude Code

The Loyalty Plugin provides the underlying data models and workflows for gift cards and store credits. Because it's built on Medusa's composable framework, you can extend it to add features like points systems, reward tiers, or custom redemption rules using custom workflows and API routes.

With the help of our agent skills, you can ask agents like Claude Code to build these loyalty program features for you. They can build the features from end-to-end with the necessary Medusa knowledge.

1234
claude # start claude code
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install medusa-dev@medusa
Add a referral program on top of the loyalty plugin features in Medusa

Get started

The Loyalty Plugin is available now with Medusa v2.14.0. See the full release notes for everything else in this release. For managing loyalty features without code, refer to the Admin User Guide.

If you're new to Medusa, check out the documentation, where you'll get a more in-depth understanding of what Medusa is, the commerce features it provides, and how to deploy Medusa to Cloud.