@agilo/medusa-plugin-store-credit

Medusa Store Credit

Give store credit to customers that they can spend in your shop.

Features

• Give store credit to customers that they can spend in your shop.
• Store credit allows customers to make multiple purchases until the credit is exhausted.
• It can be used as a personal refund or compensation card in case there’s a problem with your product or service.

---

Prerequisites

• Medusa backend

---

How to Install

1. Run the following command in the directory of the Medusa backend:

npm i @agilo/medusa-plugin-store-credit

2. In medusa-config.js add the following at the end of the plugins array:

const plugins = [
  // ...
  {
    resolve: "@agilo/medusa-plugin-store-credit",
    options: {
      enableUI: true,
    },
  },
];

3. Run the following command in the directory of the Medusa backend to run the migrations:

npx medusa migrations run

---

Test the Plugin

1. Start your Medusa backend and admin dashboard, eg.:

npm run dev

2. Visit Store Credit screen in the admin dashboard to assign store credit to a customer.

3. Implement your storefront.

The plugin extends the storefront Cart, Customer and Order models with store credit information you can use to implement your storefront, eg.:

• /store/carts/{id} - cart will contain store_credit_total field which is the total store credit available to be used in that cart
• /store/customers/me - customer will contain store_credits array with all store credits available per region for the logged in customer
• /store/customers/me/orders - order will contain store_credit_total, store_credit_transactions and store_credits which were used in the order

An example storefront implementation can be found in https://github.com/Agilo/medusa-plugin-store-credit/tree/master/packages/medusa-storefront

Contributing

We welcome contributions from the community to help make this project even better. Please feel free to open pull requests or issues. Thank you for considering contributing, and we look forward to collaborating with you!

Below you can find the plugin development guide that will help you get started with running Medusa Store Credit in your local environment.

Plugin Development

Prerequisites

• Docker
• Node.js v20
  • We suggest using nvm or fnm to manage your Node.js versions.
• Yarn v3
• Yalc

Running Locally

Follow these step-by-step instructions to run the project locally:

1. git clone https://github.com/Agilo/medusa-plugin-store-credit.git - clone the monorepo
2. cd medusa-plugin-store-credit - position into the project directory
3. cp .env.example .env - set up docker-compose environment variables
4. docker compose up - start Medusa Docker containers
5. Open a new terminal tab
6. yarn install && yarn run setup - install dependencies in all packages
7. cd packages/medusa && medusa migrations run && cd ../.. - run the migrations
8. cd packages/medusa && yarn run seed:plugin && cd ../.. - seed the database
9. yarn run start - build the packages and start the Medusa dev server and plugin watcher

Medusa Admin is now available at http://localhost:7001 and Medusa Storefront at http://localhost:8000

Default credentials for Medusa Admin are:

[e-mail]
supersecret

Once you have the project running locally you can start making changes to the plugin in packages/medusa-plugin-store-credit/src and see them reflected in the Medusa Admin and Storefront.

Generating migrations

Unfortunately DX when generating migrations which extend or relate to core entities is not great, but here's a workflow that works:

1. yarn run start - make sure workflow is running
2. cp packages/medusa-plugin-store-credit/.env.example packages/medusa-plugin-store-credit/.env - copy and edit environment variables
3. cd packages/medusa-plugin-store-credit/src/migrations - navigate to the plugin dir
4. npx typeorm migration:generate -d datasource.js src/migrations/StoreCreditUpdate - this will generate a migration file with a bunch of migrations in src/migrations/<timestamp>-StoreCreditUpdate.ts, the migration file will contain migrations for both core medusa entities and your plugin entities. You can now cherry pick the migrations you want to run and delete the rest.
5. In the packages/medusa dir run medusa migrations run

Available Commands

• yarn run setup - install dependencies in all packages
• yarn run start - build the packages and start the Medusa dev server and plugin watcher
• yarn run sync - use yalc to publish and push medusa-plugin-store-credit to Medusa backend

Docker Services

Docker services are defined in docker-compose.yml file.

• postgres - PostgreSQL database server for Medusa available on localhost:5432, you can change credentials and port in .env and packages/medusa/.env files
• redis - Redis server for Medusa available on localhost:6379

Additional Resources

• Medusa Documentation
• Medusa Development Documentation

License

This project is licensed under the MIT License.

Credits

MedusaWP is developed and maintained by AGILO.
Huge thanks to all contributors.