> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  **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."
</Tip>

## Extension points

* **Modules and providers**: Add payment, fulfillment, tax, notification, file, and other providers. Follow the [Medusa module docs](https://docs.medusajs.com/) for integration patterns.
* **Subscribers**: Vulpy ships a `commerceReporting` subscriber that aggregates order lifecycle metrics without requiring visitor consent. See [Orders](/shop/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](/reference/env-vars).

## Add a subscriber

<Steps>
  <Step title="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.
  </Step>

  <Step title="Register the subscriber">
    Register it per the [Medusa subscriber docs](https://docs.medusajs.com/). This usually means exporting the handler and event config from the file so Medusa discovers it automatically.
  </Step>

  <Step title="Restart the environment">
    Restart Medusa so the new subscriber is loaded:

    ```bash theme={null}
    pnpm vulpy env down <name>
    pnpm vulpy env up <name>
    ```
  </Step>
</Steps>

## Seeds and demo data

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

```bash theme={null}
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.

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

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

<CardGroup cols={2}>
  <Card title="Payments and providers" icon="credit-card" href="/shop/payments">
    Configure payment and fulfillment providers in the Medusa backend.
  </Card>

  <Card title="Storefront blocks" icon="blocks" href="/customize/blocks">
    Register Payload blocks and map them to React components in the storefront.
  </Card>
</CardGroup>