Customize the Vulpy Medusa v2 backend

Add Medusa v2 modules, subscribers, and admin widgets in apps/medusa-backend, and follow the upstream Medusa module docs for provider integrations.

Vulpy Commerce ships Medusa v2 as a customizable backend at apps/medusa-backend. You extend it the same way you would any Medusa v2 install: by adding modules, subscribers, and admin widgets. This page covers the extension points Vulpy uses and how to add your own.

Ask Fox to wire the extension. Fox knows the Medusa v2 module layout and can scaffold subscribers, providers, and workflows for you.

Try prompts like:

• “Add an order.placed subscriber that posts to a webhook.”
• “Install the Stripe provider and wire it into apps/medusa-backend.”
• “Draft a workflow that tags orders over $500.”

Extension points

• Modules and providers: Add payment, fulfillment, tax, notification, file, and other providers. Follow the Medusa module docs for integration patterns.
• Subscribers: Vulpy ships a commerceReporting subscriber that aggregates order lifecycle metrics without requiring visitor consent. See Orders.
• Admin widgets: Vulpy adds crosslinks from the Medusa admin into the Payload admin and the storefront, so editors can jump between systems.
• Publishable API key sync: Set SYNC_PUBLISHABLE_KEY=1 to keep storefront publishable API keys aligned across deploys. See Environment variables.

Add a subscriber

1. Create the subscriber file

   Add a new file under apps/medusa-backend/src/subscribers/ that exports a subscriber function and the events it listens to.

2. Register the subscriber

   Register it per the Medusa subscriber docs. This usually means exporting the handler and event config from the file so Medusa discovers it automatically.

3. Restart the environment

   Restart Medusa so the new subscriber is loaded:

   pnpm vulpy env down <name>
   pnpm vulpy env up <name>
   

Seeds and demo data

Run the demo catalog seed to create sample products and categories:

pnpm --filter @apps/medusa-backend seed:demo-catalog

Demo records are stamped with metadata.demo_catalog = true so they never mix with real data. You can safely remove them later by filtering on that metadata key.

Keep provider credentials in environments/<name>/.env. Never commit secrets to the repository.

Changing a Medusa entity migration in a non-additive way can break existing data. Test migrations in staging before applying them to live.

Payments and providers

Configure payment and fulfillment providers in the Medusa backend.

Storefront blocks

Register Payload blocks and map them to React components in the storefront.