Digital Products

Medusa Digital Products

An installable Medusa v2 plugin for digital products, software licensing, customer entitlements, device activations, and protected file delivery.

The plugin fills the domain gap between selling a non-shippable product and operating a production licensing system. It is built as a native Medusa plugin: module data models, rollback-capable workflows, authenticated Admin and Store APIs, a product-variant module link, subscribers, a scheduled expiry job, migrations, and an Admin extension.

Features

• Digital products linked one-to-one with Medusa product variants.
• Versioned assets backed by Medusa's configured File Module provider.
• Perpetual, time-limited, subscription, and trial license policies.
• A native Medusa Fulfillment Module provider for zero-cost digital delivery.
• Automatic, idempotent fulfillment on Copy to clipboardorder.placed: entitlements, quantity-aware license keys, protected download grants, email delivery, and delivered status.
• Manual grants for support, promotions, migrations, and B2B use cases.
• Automatic revocation when an order is canceled and explicit admin revocation for refunds or chargebacks.
• Quantity-aware, one-time license-key issuance.
• HMAC-hashed license keys and download tokens; plaintext credentials are never persisted.
• Device activation limits, validation, reactivation, and deactivation.
• Short-lived download grants with policy-level, per-asset download limits.
• Immutable audit events for sensitive mutations.
• Hourly expiry of entitlements, licenses, and download grants.
• A read-only Admin overview at Copy to clipboard/app/digital-products.

Compatibility

• Medusa Copy to clipboard>=2.17 <3
• Node.js Copy to clipboard>=20
• PostgreSQL (as required by Medusa)

Installation

1
npm install medusa-plugin-digital-products

Register the plugin in Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
import { defineConfig, loadEnv } from "@medusajs/framework/utils"

loadEnv(process.env.NODE_ENV || "development", process.cwd())

module.exports = defineConfig({
  // your existing projectConfig
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "medusa-plugin-digital-products/providers/digital-fulfillment",
            id: "digital-products",
          },
        ],
      },
    },
  ],
  plugins: [

Configure a secret of at least 32 characters. Treat this as production key material and keep it stable; changing it invalidates credential lookups.

12345
DIGITAL_PRODUCTS_SECRET=replace-with-a-random-secret-at-least-32-characters
MEDUSA_BACKEND_URL=https://api.example.com
DIGITAL_PRODUCTS_ACCOUNT_URL=https://shop.example.com/account/digital-products
# Optional; defaults to seven days and is capped at thirty days.
DIGITAL_PRODUCTS_DELIVERY_TOKEN_TTL_SECONDS=604800

Run the plugin migrations from the host application:

1
npx medusa db:migrate

Use an S3-compatible File Module provider in production. Medusa's local provider is intended for development.

Configure an email-capable Notification Module provider that supports direct Copy to clipboardcontent. Raw license keys and download tokens are only placed in the transient provider payload, never in the plugin database, fulfillment metadata, audit log, or notification Copy to clipboarddata record.

Fulfillment setup

After registering the provider, add Copy to clipboardfp_digital-products_digital-products to the stock location that sells digital products. Create a fixed-price shipping option from its Copy to clipboarddigital-delivery service, price it at zero, and make it available in the relevant service zone. Digital carts must select that option during checkout. This is especially important for mixed carts: the plugin explicitly selects the digital shipping option for the digital line items and leaves physical items to their own provider.

Configure linked variants as non-physical (Copy to clipboardrequires_shipping: false) and do not manage inventory unless you intentionally impose digital stock limits. The order must still contain the zero-priced digital shipping method so Medusa can associate its fulfillment with this provider.

Domain flow

1. Create a license policy.
2. Create a digital product linked to an existing product variant.
3. Upload the binary with Medusa's File API, then attach its Copy to clipboardfile_id as a digital asset.
4. Publish the digital product by setting its status to Copy to clipboardactive.
5. When the linked variant is purchased, the Copy to clipboardorder.placed subscriber runs one rollback-capable delivery workflow.
6. The workflow grants entitlements, issues one key per purchased quantity, creates protected asset links, creates the Medusa fulfillment through this provider, marks it delivered, and emails the buyer.
7. Authenticated customers can later issue any remaining keys or fresh short-lived download grants from their account.
8. License clients activate and validate keys using a stable device identifier.

For non-shippable catalog configuration, set the Medusa product/variant inventory and shipping requirements according to the official selling-products guide.

Admin API

All Admin endpoints use Medusa's standard Admin authentication.

Method Route Purpose Copy to clipboardGET, Copy to clipboardPOST Copy to clipboard/admin/digital-products List or create digital products Copy to clipboardGET, Copy to clipboardPOST, Copy to clipboardDELETE Copy to clipboard/admin/digital-products/:id Retrieve, update, or archive a digital product Copy to clipboardPOST Copy to clipboard/admin/digital-products/:id/assets Attach a File Module asset Copy to clipboardGET, Copy to clipboardPOST Copy to clipboard/admin/digital-products/license-policies List or create policies Copy to clipboardGET, Copy to clipboardPOST Copy to clipboard/admin/digital-products/entitlements List or manually grant entitlements Copy to clipboardPOST Copy to clipboard/admin/digital-products/entitlements/:id/revoke Revoke an entitlement Copy to clipboardPOST Copy to clipboard/admin/digital-products/entitlements/:id/licenses Issue a license key once Copy to clipboardPOST Copy to clipboard/admin/digital-products/orders/:id/fulfill Safely retry or manually trigger digital fulfillment

Store API

Use the Medusa JS SDK so customer authentication and publishable API keys are included automatically.

Method Route Purpose Copy to clipboardGET Copy to clipboard/store/customers/me/digital-products List the authenticated customer's entitlements Copy to clipboardPOST Copy to clipboard/store/customers/me/digital-products/:id/licenses Issue a license key owned by the customer Copy to clipboardPOST Copy to clipboard/store/customers/me/digital-products/:id/downloads Create a short-lived download token Copy to clipboardPOST Copy to clipboard/store/digital-products/downloads/redeem Consume a token and return the provider URL to an SDK client Copy to clipboardPOST Copy to clipboard/store/digital-products/licenses/activate Activate a license for a device Copy to clipboardPOST Copy to clipboard/store/digital-products/licenses/validate Validate a license/device pair Copy to clipboardPOST Copy to clipboard/store/digital-products/licenses/deactivate Release a device activation

Example SDK request:

1234567
const result = await sdk.client.fetch(
  `/store/customers/me/digital-products/${entitlementId}/downloads`,
  {
    method: "POST",
    body: { asset_id: assetId },
  }
)

Emailed download links use Copy to clipboardGET /digital-products/downloads/redeem?token=.... This browser-facing route is outside Medusa's publishable-key-protected Copy to clipboard/store namespace because normal link navigation cannot attach SDK headers. The high-entropy, expiring, usage-limited token is the authorization credential; successful redemption redirects to the File Module provider URL.

Security model

• License keys and download tokens are returned only at issuance and stored as HMAC-SHA-256 hashes.
• Customer ownership checks run inside workflows, not route handlers.
• Download grants expire after five minutes by default, are capped at one hour, and are one-use.
• File URLs come from the configured Medusa File Module provider only after grant consumption.
• Device identifiers are HMAC-hashed before persistence.
• API responses use Copy to clipboardCache-Control: no-store for redeemed links.
• Never put raw license keys or download tokens in logs, metadata, analytics, or audit events.

Guest buyers receive their license keys and protected download links at the order email. Their entitlement remains email-bound until the host application associates or claims it for a customer account.

If delivery fails—for example because the email provider is unavailable—the workflow compensates the fulfillment, licenses, grants, and newly created entitlements. Fix the provider configuration and retry with Copy to clipboardPOST /admin/digital-products/orders/:id/fulfill. Completed deliveries are detected from fulfillment metadata and are not duplicated.

Local development

123456789
npm install
npm run build
npm run lint
npm test
# Requires PostgreSQL and the DB_HOST, DB_PORT, DB_USERNAME, and DB_PASSWORD variables.
npm run test:integration:modules
npm run test:package
# Requires Docker; installs the packed plugin into an isolated Medusa host.
npm run test:acceptance

Publish to Medusa's local plugin registry:

1
npx medusa plugin:publish

Then add it to a Medusa application with Copy to clipboardnpx medusa plugin:add medusa-plugin-digital-products, register it in Copy to clipboardmedusa-config.ts, run Copy to clipboardnpx medusa db:migrate, and start the host with Copy to clipboardnpm run dev.

Publishing and Medusa listing

Build and inspect the package before publishing:

123
npm run release:check
npm run test:integration:modules
npm pack --dry-run

Releases are published through the GitHub release workflow with npm provenance. The Git tag must exactly match Copy to clipboardv<package-version>. See RELEASING.md for first-release and trusted-publishing setup.

This plugin targets the Other category in Medusa's npm-curated Integrations Directory. The live category includes reusable commerce-feature plugins as well as third-party services, so the package uses the current Copy to clipboardmedusa-plugin-integration and Copy to clipboardmedusa-plugin-other discovery metadata. See the listing strategy for the evidence, sync checklist, and escalation path. Directory inclusion remains Medusa's decision.

Support and security

Use GitHub issues for reproducible bugs and feature requests. Read SUPPORT.md before requesting help and report vulnerabilities privately as described in SECURITY.md.

License

MIT