How to Extend a Service

In this document, you’ll learn how to extend a core service in Medusa.

Overview

Medusa’s core services cover a wide range of functionalities related to each domain or entity. You can extend these services to add custom methods or override existing methods.

Word of Caution about Overriding

Extending services to add new methods shouldn't cause any issues within your commerce application. However, if you extend them to override their existing methods, you should be aware that this could have negative implications, such as unanticipated bugs, especially when you try to upgrade the core Medusa package to a newer version.

---

Step 1: Create the Service File

In your Medusa backend, create the file src/services/product.tsCopy to Clipboard. This file will hold your extended service.

Note that the name of the file must be the same as the name of the original service in the core package. So, if you’re extending the ProductServiceCopy to Clipboard, the file’s name should be product.tsCopy to Clipboard. On the other hand, if you’re extending the CustomerServiceCopy to Clipboard, the file’s name should be customer.tsCopy to Clipboard.

---

Step 2: Implementing the Service

In the file, you can import the original service from the Medusa core, then create your service that extends the core service.

For example, to extend the Product service:

src/services/product.ts

import { 
  ProductService as MedusaProductService,
} from "@medusajs/medusa"

class ProductService extends MedusaProductService {
  // TODO add customizations
}

export default ProductService

Report Incorrect CodeCopy to Clipboard

Notice that you alias the ProductServiceCopy to Clipboard of the core to avoid naming conflicts.

Within the service, you can add new methods or extend existing ones.

You can also change the lifetime of the service:

src/services/product.ts

import { Lifetime } from "awilix"
import { 
  ProductService as MedusaProductService,
} from "@medusajs/medusa"

class ProductService extends MedusaProductService {
  // The default life time for a core service is SINGLETON
  static LIFE_TIME = Lifetime.SCOPED
    
  // ...
}

export default ProductService

Report Incorrect CodeCopy to Clipboard

You can learn more details about the service lifetime and other considerations when creating a service in the Create Service documentation.

---

Step 3: Test it Out

To test out your customization, start by transpiling your files by running the following command in the root directory of the Medusa backend:

• npm
• Yarn
• pnpm

npm run build

Report Incorrect CodeCopy to Clipboard

yarn build

Report Incorrect CodeCopy to Clipboard

pnpm run build

Report Incorrect CodeCopy to Clipboard

Then, start the backend:

• npm
• Yarn
• pnpm

npx @medusajs/medusa-cli develop

Report Incorrect CodeCopy to Clipboard

npx @medusajs/medusa-cli develop

Report Incorrect CodeCopy to Clipboard

npx @medusajs/medusa-cli develop

Report Incorrect CodeCopy to Clipboard

You should see the customizations you made in effect.

---

Troubleshooting

AwilixResolutionError: Could Not Resolve X (Service Lifetime)

If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their LIFE_TIMECopy to Clipboard static property either set to Lifetime.SCOPEDCopy to Clipboard or Lifetime.TRANSIENTCopy to Clipboard. This mainly applies for services in the core Medusa package, as, by default, their lifetime is Lifetime.SINGLETONCopy to Clipboard.

For example:

import { Lifetime } from "awilix"
import { 
  ProductService as MedusaProductService,
} from "@medusajs/medusa"

// extending ProductService from the core
class ProductService extends MedusaProductService {
  // The default life time for a core service is SINGLETON
  static LIFE_TIME = Lifetime.SCOPED

  // ...
}

export default ProductService

Report Incorrect CodeCopy to Clipboard

This may require you to extend a service as explained in this documentation if necessary.

If you're unsure which service you need to change its LIFE_TIMECopy to Clipboard property, it should be mentioned along with the AwilixResolutionErrorCopy to Clipboard message. For example:

AwilixResolutionError: Could not resolve 'loggedInUser'.

Resolution path: cartService -> productService -> loggedInUser

As shown in the resolution path, you must change the LIFE_TIMECopy to Clipboard property of both cartServiceCopy to Clipboard and productServiceCopy to Clipboard to Lifetime.SCOPEDCopy to Clipboard or Lifetime.TRANSIENTCopy to Clipboard.

You can learn about the service lifetime in the Create a Service documentation.