# medusa-recommend-product-plugin

> Plugin for product recommandation management

Latest version **1.0.0** (published 2025-06-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install medusa-recommend-product-plugin
pnpm add medusa-recommend-product-plugin
yarn add medusa-recommend-product-plugin
bun add medusa-recommend-product-plugin
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2025-06-23 |
| First published | 2024-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=20.x.x |
| Dependencies | 7 |
| Unpacked size | 146.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | LaZone |
| Maintainers | lazone |
| Keywords | postgres, typescript, ecommerce, headless, medusa, products recommendation, lazonedev, medusa-recommend-product-plugin, medusa-plugin, medusa-plugin-other |

## Links

- npm: https://www.npmjs.com/package/medusa-recommend-product-plugin
- npm.io page: https://npm.io/package/medusa-recommend-product-plugin

## Dependencies (7)

- [yup](https://npm.io/package/yup.md) ^1.3.3
- [formik](https://npm.io/package/formik.md) ^2.4.5
- [@medusajs/ui](https://npm.io/package/@medusajs/ui.md) ^4.0.4
- [@medusajs/icons](https://npm.io/package/@medusajs/icons.md) ^2.8.3
- [@medusajs/medusa](https://npm.io/package/@medusajs/medusa.md) ^2.8.3
- [@medusajs/admin-sdk](https://npm.io/package/@medusajs/admin-sdk.md) ^2.8.3
- [@medusajs/framework](https://npm.io/package/@medusajs/framework.md) ^2.8.3

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2025-06-23
- 0.1.4 — 2024-09-06
- 0.1.3 — 2024-04-27
- 0.1.2 — 2024-04-26
- 0.1.2-alpha-3 — 2024-04-23
- 0.1.2-alpha-2 — 2024-04-23
- 0.1.2-alpha — 2024-04-23
- 0.1.1 — 2024-04-19

## README

# Medusa Recommend Product Plugin

[![npm version](https://badge.fury.io/js/medusa-recommend-product-plugin.svg)](https://badge.fury.io/js/medusa-recommend-product-plugin)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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](#installation)
2. [Usage](#usage)
   - [Register the Plugin](#register-the-plugin)
   - [Run Migrations](#run-migrations)
   - [Admin Panel Features](#admin-panel-features)
3. [API Reference](#api-reference)
   - [Store API](#store-api)
   - [Admin API](#admin-api)
4. [Error Handling](#error-handling)
5. [License](#license)

## Installation

To install the plugin, use the following command:

```bash
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:

```js
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:

```bash
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**

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

**Example Response**

```json
[
 [
    {
      "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**

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

**Example Response**

```json
{
  "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**

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

**Example Response**

```json
{
  "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:

```json
{
  "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](https://opensource.org/licenses/MIT) file.

---
_Source: https://npm.io/package/medusa-recommend-product-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
