Medusa Recommend Product Plugin

The Medusa Recommend Product Plugin is a powerful tool for managing product recommendations within your Medusa e-commerce platform. This plugin allows you to add, view, and manage product recommendations easily, enhancing the user experience by suggesting related or popular products to your customers.

Table of Contents

1. Installation
2. Usage
   • Register the Plugin
   • Run Migrations
   • Admin Panel Features
3. API Reference
   • Store API
   • Admin API
4. Error Handling
5. License

Installation

To install the plugin, use the following command:

npm install medusa-recommend-product-plugin

Usage

Register the Plugin

To activate the plugin, you need to add it to the list of plugins in your Medusa configuration file (medusa-config.js).

1. Open medusa-config.js.
2. Locate the plugins array.
3. Add the plugin configuration as shown below:

const plugins = [
  // other plugins
  {
    resolve: "medusa-recommend-product-plugin",
    options: {
      enableUI: true, // Enables the admin UI for managing recommendations
    },
  },
];

Run Migrations

After registering the plugin, run the migrations to set up the necessary database tables:

npx medusa migrations run

Admin Panel Features

Once the plugin is set up and migrations are run, you can manage product recommendations directly from the Medusa admin panel:

• View Recommendations: On the product details page, you can view the list of current recommendations.
• Add New Recommendations: Easily add new product recommendations through a simple interface.

API Reference

Store API

The Store API provides endpoints for retrieving product recommendations for customers.

Get Product Recommendations

Retrieve the list of recommendations for a specific product.

• URL: /api/store/products/{productId}/recommendations
• Method: GET
• Content-Type: application/json

Query Parameters

| Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------ | | productId | string | The ID of the product for which to retrieve recommendations. |

Response

| Name | Type | Description | | ------------------------ | ------ | ----------------------------- | | Array of Recommendations | object | List of recommended products. |

Example Request

curl -X GET "https://your-medusa-url.com/api/store/products/123/recommendations"

Example Response

[
 [
    {
      "id": "recommendation_.....",
      "recommendedProduct": [{
        "id": "prod1",
        "name": "Product 1",
        "description": "This is product 1",
        ...
      }],
      "forProductId":"product_1"
    },
  ]
]

Admin API

The Admin API provides endpoints for managing product recommendations from the admin panel.

Create Product Recommendations

Create new recommendations for a specific product.

• URL: /api/admin/recommendations
• Method: POST
• Content-Type: application/json

Request Body

| Name | Type | Description | | --------------------- | -------- | ------------------------------------------------- | | forProductId | string | The ID of the product to add recommendations for. | | recommendedProducts | string[] | A list of product IDs to recommend. |

Example Request

curl -X POST "https://your-medusa-url.com/api/admin/recommendations" \
-H "Content-Type: application/json" \
-d '{
  "forProductId": "prod1",
  "recommendedProducts": ["prod2", "prod3"]
}'

Example Response

{
  "data": [
    {
      "id": "recommendation_.....",
      "recommendedProduct": [{
        "id": "prod1",
        "name": "Product 1",
        "description": "This is product 1",
        ...
      }],
      "forProductId":"product_1"
    },
  ]
}

Delete Product Recommendations

Delete specific recommendations for a product.

• URL: /api/admin/recommendations
• Method: DELETE
• Content-Type: application/json

Request Body

| Name | Type | Description | | ------------------- | -------- | ----------------------------------------- | | recommendationIds | string[] | The list of recommendation IDs to delete. |

Example Request

curl -X DELETE "https://your-medusa-url.com/api/admin/recommendations" \
-H "Content-Type: application/json" \
-d '{
  "recommendationIds": ["rec1", "rec2"]
}'

Example Response

{
  "success": true
}

Error Handling

All API responses include standardized error handling to help you debug and handle errors effectively.

Error Response Format

Error responses are structured in the following format:

{
  "message": "Error message describing the issue.",
  "code": "Error code",
  "errors": [
    {
      "field": "Field that caused the error",
      "message": "Detailed message about the error"
    }
  ],
  "payload": {
    // Additional error-related data, if applicable
  }
}

Common Error Codes

• INTERNAL_SERVER_ERROR: An unexpected error occurred on the server.
• VALIDATION_ERROR: Input data failed validation.
• BAD_REQUEST: The request was malformed or invalid.
• NOT_FOUND: The requested resource was not found.
• UNPROCESSABLE_ENTITY_ERROR: The server understood the request but could not process it.

Example Error Messages

• recommendationAlreadyExist: "This product already has a recommendation associated with the recommended product."
• recommendationNotFound: "Recommendation not found for the provided ID."
• noDuplicateProdRecommendation: "You cannot create multiple recommendations for the same product with the same recommended product."

License

This plugin is licensed under the MIT License. For more details, refer to the LICENSE file.