Workflows

createReviewWorkflow

This documentation provides a reference to the createReviewWorkflow. It belongs to the @mercurjs/reviews package. This workflow creates a review for a product or seller. It validates that the customer owns the order and hasn’t already reviewed the same reference, creates the review, links it to the product or seller and customer, and emits an event for search index updates. It exposes a hook for custom extensions. Source code

Examples

API Route

packages/modules/reviews/src/api/store/reviews/route.ts

import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework";
import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
import { createReviewWorkflow } from "../../../workflows/review/workflows";
import { StoreCreateReviewType } from "./validators";

export const POST = async (
  req: AuthenticatedMedusaRequest<StoreCreateReviewType>,
  res: MedusaResponse
) => {
  const { result } = await createReviewWorkflow.run({
    container: req.scope,
    input: {
      ...req.validatedBody,
      customer_id: req.auth_context.actor_id,
    },
  });

  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);

  const {
    data: [review],
  } = await query.graph({
    entity: "review",
    fields: req.queryConfig.fields,
    filters: {
      id: result.id,
    },
  });

  res.status(201).json({ review });
};

Steps

validateReviewStep: Validates that the customer owns the order and hasn’t already reviewed this reference.
createReviewStep: Creates the review record and links it to customer and order.
createRemoteLinkStep: Links the review to the product or seller based on the reference type.
emitEventStep: Emits a review.changed event for search index updates.

Hooks

reviewCreated: Hook that fires after a review is created, providing the review_id.

Input

input

CreateReviewDTO

required

The review creation details.

Show properties

order_id

string

required

The ID of the order this review is associated with.

customer_id

string

required

The ID of the customer creating the review.

reference

string

required

The type of entity being reviewed. Available types:

product - Review for a product
seller - Review for a seller

reference_id

string

required

The ID of the product or seller being reviewed.

rating

number

required

The rating value (1-5).

customer_note

string

The customer’s review comment (max 300 characters).

Output

ReviewDTO

The created review.

Show properties

string

The ID of the review.

reference

string

The reference type (product or seller).

rating

number

The rating value (1-5).

customer_note

string

The customer’s review comment.

customer_id

string

The ID of the customer who created the review.

seller_note

string

The seller’s response note (null initially).

created_at

Date

The date the review was created.

updated_at

Date

The date the review was last updated.

deleteReviewWorkflow

This documentation provides a reference to the deleteReviewWorkflow. It belongs to the @mercurjs/reviews package. This workflow soft deletes a review. It exposes a hook for custom extensions. Source code

Examples

API Route
Subscriber

packages/modules/reviews/src/api/store/reviews/[id]/route.ts

import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { deleteReviewWorkflow } from '../../../../workflows/review/workflows'

export const DELETE = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) => {
  const { id } = req.params
  await deleteReviewWorkflow.run({
    container: req.scope,
    input: id
  })

  res.json({
    id,
    object: 'review',
    deleted: true
  })
}

packages/modules/reviews/src/subscribers/remove-review-request-removed.ts

import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";
import { RemoveReviewRequestUpdatedEvent } from "@mercurjs/framework";
import { deleteReviewWorkflow } from "../workflows";

export default async function commissionOrderSetPlacedHandler({
  event,
  container,
}: SubscriberArgs<{ id: string }>) {
  await deleteReviewWorkflow.run({
    container,
    input: {
      id: event.data.id,
    },
  });
}

export const config: SubscriberConfig = {
  event: RemoveReviewRequestUpdatedEvent.REMOVED,
  context: {
    subscriberId: "remove-review-request-removed-handler",
  },
};

Steps

deleteReviewStep: Soft deletes the review.

Hooks

reviewDeleted: Hook that fires after a review is deleted, providing the review_id.

Input

string

required

The ID of the review to delete.

Output

string

The ID of the deleted review.

updateReviewWorkflow

This documentation provides a reference to the updateReviewWorkflow. It belongs to the @mercurjs/reviews package. This workflow updates a review’s rating, customer note, or seller note. It emits an event for search index updates and exposes a hook for custom extensions. Source code

Examples

Customer Update
Vendor Update

packages/modules/reviews/src/api/store/reviews/[id]/route.ts

import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { updateReviewWorkflow } from '../../../../workflows/review/workflows'
import { StoreUpdateReviewType } from '../validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<StoreUpdateReviewType>,
  res: MedusaResponse
) => {
  const { id } = req.params
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  await updateReviewWorkflow.run({
    container: req.scope,
    input: { id, ...req.validatedBody }
  })

  const {
    data: [review]
  } = await query.graph({
    entity: 'review',
    fields: req.queryConfig.fields,
    filters: {
      id
    }
  })

  res.json({
    review
  })
}

packages/modules/reviews/src/api/vendor/sellers/me/reviews/[id]/route.ts

import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { updateReviewWorkflow } from '../../../../../../workflows/review/workflows'
import { VendorUpdateReviewType } from '../../../validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorUpdateReviewType>,
  res: MedusaResponse
) => {
  const { id } = req.params
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)

  await updateReviewWorkflow.run({
    container: req.scope,
    input: { id, ...req.validatedBody }
  })

  const {
    data: [review]
  } = await query.graph({
    entity: 'review',
    fields: req.queryConfig.fields,
    filters: {
      id
    }
  })

  res.json({
    review
  })
}

Steps

updateReviewStep: Updates the review record.
emitEventStep: Emits a review.changed event for search index updates.

Hooks

reviewUpdated: Hook that fires after a review is updated, providing the review_id.

Input

input

UpdateReviewDTO

required

The review update details.

Show properties

string

required

The ID of the review to update.

rating

number

The new rating value (1-5).

customer_note

string

The updated customer comment (max 300 characters).

seller_note

string

The seller’s response to the review.

Output

ReviewDTO

The updated review.

Show properties

string

The ID of the review.

rating

number

The rating value.

customer_note

string

The customer’s comment.

seller_note

string

The seller’s response.

updated_at

Date

The date the review was last updated.

Steps

createReviewStep

Creates a review record and links it to the customer and order. The step creates the links using the Link service to establish relationships with the customer and order entities. Source code

Input

input

CreateReviewDTO

required

The review creation details.

Output

ReviewDTO

The created review.

deleteReviewStep

Soft deletes a review record from the database. Source code

Input

string

required

The ID of the review to delete.

Output

string

The ID of the deleted review.

updateReviewStep

Updates a review record with new rating, customer note, or seller note. Source code

Input

input

UpdateReviewDTO

required

The review update details.

Output

ReviewDTO

The updated review.

validateReviewStep

Validates a review creation by checking:

The customer owns the order being reviewed
The customer hasn’t already reviewed the same product or seller for this order

Source code

Input

reviewToCreate

CreateReviewDTO

required

The review data to validate.

Output

void

Throws an INVALID_DATA error if:

Order doesn’t belong to the customer
Review already exists for this reference on this order

Quick start

Components

Core Concepts

Product

Integrations

Deployment

Help

Review Workflows

Workflows

createReviewWorkflow

Examples

Steps

Hooks

Input

Output

deleteReviewWorkflow

Examples

Steps

Hooks

Input

Output

updateReviewWorkflow

Examples

Steps

Hooks

Input

Output

Steps

createReviewStep

Input

Output

deleteReviewStep

Input

Output

updateReviewStep

Input

Output

validateReviewStep

Input

Output

Quick start

Components

Core Concepts

Product

Integrations

Deployment

Help

​Workflows

​createReviewWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​deleteReviewWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​updateReviewWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​Steps

​createReviewStep

​Input

​Output

​deleteReviewStep

​Input

​Output

​updateReviewStep

​Input

​Output

​validateReviewStep

​Input

​Output

Workflows

createReviewWorkflow

Examples

Steps

Hooks

Input

Output

deleteReviewWorkflow

Examples

Steps

Hooks

Input

Output

updateReviewWorkflow

Examples

Steps

Hooks

Input

Output

Steps

createReviewStep

Input

Output

deleteReviewStep

Input

Output

updateReviewStep

Input

Output

validateReviewStep

Input

Output