Workflows

acceptProductCategoryRequestWorkflow

This documentation provides a reference to the acceptProductCategoryRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a product category creation request by creating the category and updating the request status to “accepted”. Source code

Examples

API Route (via utility)

packages/modules/requests/src/api/admin/requests/[id]/route.ts

import { getRequestWorkflowByType } from '../../../../workflows/requests/utils/select-workflow'

// ... inside POST handler

const workflow = getRequestWorkflowByType(request.type)

const { result: createdResource } = await workflow(req.scope).run({
  input: {
    id: req.params.id,
    reviewer_id: req.auth_context.actor_id,
    data: request.data,
    ...req.validatedBody
  },
  throwOnError: true
})

Steps

createProductCategoriesWorkflow: Creates the product category using Medusa’s core workflow.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

string

required

The ID of the request to accept.

reviewer_id

string

required

The ID of the admin reviewer.

reviewer_note

string

required

The reviewer’s note.

status

RequestStatus

required

The new status (should be “accepted”).

data

object

required

The product category data.

Show properties

name

string

required

The name of the category.

description

string

The description of the category.

handle

string

The handle (auto-generated from name if empty).

parent_category_id

string

The ID of the parent category.

Output

ProductCategoryDTO

The created product category.

acceptProductCollectionRequestWorkflow

This documentation provides a reference to the acceptProductCollectionRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a product collection creation request by creating the collection and updating the request status to “accepted”. Source code

Steps

createCollectionsWorkflow: Creates the product collection using Medusa’s core workflow.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

data

object

required

The product collection data.

Show properties

title

string

required

The title of the collection.

handle

string

The handle (auto-generated from title if empty).

metadata

Record<string, unknown>

Additional metadata.

Output

ProductCollectionDTO

The created product collection.

acceptProductRequestWorkflow

This documentation provides a reference to the acceptProductRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a product creation request by setting the product status to “published” and updating the request status to “accepted”. Source code

Steps

updateProductStatusStep: Sets the product status to “published”.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

data

object

required

The request data.

Show properties

product_id

string

required

The ID of the product to publish.

Output

ProductDTO

The published product.

acceptProductTagRequestWorkflow

This documentation provides a reference to the acceptProductTagRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a product tag creation request by creating the tag and updating the request status to “accepted”. Source code

Steps

createProductTagsWorkflow: Creates the product tag using Medusa’s core workflow.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

data

object

required

The product tag data.

Show properties

value

string

required

The value of the tag.

Output

ProductTagDTO

The created product tag.

acceptProductTypeRequestWorkflow

This documentation provides a reference to the acceptProductTypeRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a product type creation request by creating the type and updating the request status to “accepted”. Source code

Steps

createProductTypesWorkflow: Creates the product type using Medusa’s core workflow.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

data

object

required

The product type data.

Show properties

value

string

required

The value of the type.

Output

ProductTypeDTO

The created product type.

acceptReviewRemoveRequestWorkflow

This documentation provides a reference to the acceptReviewRemoveRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a review removal request by emitting an event to trigger review deletion and updating the request status to “accepted”. Source code

Steps

emitEventStep: Emits a review removal event.
updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Show properties

data

object

required

The review removal data.

Show properties

review_id

string

required

The ID of the review to remove.

Output

boolean

Returns true after processing.

acceptSellerCreationRequestWorkflow

This documentation provides a reference to the acceptSellerCreationRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow accepts a seller creation request by updating the request status to “accepted”. The actual seller creation is handled separately. Source code

Steps

updateRequestWorkflow: Updates the request status to “accepted”.

Input

input

AcceptRequestDTO

required

The request acceptance details.

Output

object

Returns an empty object.

createProductRequestWorkflow

This documentation provides a reference to the createProductRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates a product creation request, links it to the seller, and emits events for notification and tracking. It exposes a hook for custom extensions. Source code

Examples

Subscriber

packages/modules/requests/src/subscribers/product-request-to-create.ts

import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";
import {
  CreateRequestDTO,
  ProductRequestUpdatedEvent,
} from "@mercurjs/framework";
import {
  createProductRequestWorkflow,
} from "../workflows";

export default async function productRequestToCreateHandler({
  event,
  container,
}: SubscriberArgs<{
  data: CreateRequestDTO;
  seller_id: string;
}>) {
  const input = event.data;

  await createProductRequestWorkflow.run({
    container,
    input,
  });
}

export const config: SubscriberConfig = {
  event: ProductRequestUpdatedEvent.TO_CREATE,
  context: {
    subscriberId: "product-request-to-create",
  },
};

Steps

createRequestStep: Creates the request record.
createRemoteLinkStep: Links the request to the seller.
emitMultipleEventsStep: Emits requests.*.created and product_request.created events.

Hooks

productRequestCreated: Hook that fires after a product request is created, providing the requestId and sellerId.

Input

input

object

required

The product request creation details.

Show properties

data

CreateRequestDTO

required

The request data.

Show properties

type

string

required

The request type (should be “product”).

data

any

required

The product data to be created upon approval.

submitter_id

string

required

The ID of the member submitting the request.

status

RequestStatus

The initial status (defaults to “pending”).

seller_id

string

required

The ID of the seller creating the product request.

additional_data

any

Additional data to pass along.

Output

RequestDTO[]

Array containing the created request.

createProductUpdateRequestWorkflow

This documentation provides a reference to the createProductUpdateRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates a product update request by setting the product status to “proposed”, creating the request record, linking it to the seller, and emitting events. It exposes a hook for custom extensions. Source code

Examples

Subscriber

packages/modules/requests/src/subscribers/product-update-request-to-create.ts

import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";
import {
  checkConfigurationRule,
  ConfigurationRuleType,
  CreateRequestDTO,
  ProductUpdateRequestUpdatedEvent,
} from "@mercurjs/framework";
import { createProductUpdateRequestWorkflow } from "../workflows/requests/workflows/create-product-update-request";

export default async function productUpdateRequestToCreateHandler({
  event,
  container,
}: SubscriberArgs<{
  data: CreateRequestDTO;
  seller_id: string;
  additional_data?: any;
}>) {
  const input = event.data;

  if (
    await checkConfigurationRule(
      container,
      ConfigurationRuleType.REQUIRE_PRODUCT_APPROVAL
    )
  ) {
    await createProductUpdateRequestWorkflow.run({
      container,
      input,
    });
  }
}

export const config: SubscriberConfig = {
  event: ProductUpdateRequestUpdatedEvent.TO_CREATE,
  context: {
    subscriberId: "product-update-request-to-create",
  },
};

Steps

updateProductStatusStep: Sets the product status to “proposed”.
createRequestStep: Creates the request record with type “product_update”.
createRemoteLinkStep: Links the request to the seller.
emitMultipleEventsStep: Emits requests.*.created and product_update_request.created events.

Hooks

productUpdateRequestCreated: Hook that fires after a product update request is created, providing the requestId and sellerId.

Input

input

object

required

The product update request creation details.

Show properties

data

CreateRequestDTO

required

The request data.

Show properties

data

object

required

The product update data.

Show properties

product_id

string

required

The ID of the product to update.

submitter_id

string

required

The ID of the member submitting the request.

seller_id

string

required

The ID of the seller.

additional_data

any

Additional data to pass along.

Output

RequestDTO[]

Array containing the created request.

createRequestWorkflow

This documentation provides a reference to the createRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates a general request, links it to the seller, and emits a creation event. It exposes a hook for custom extensions. Source code

Examples

API Route

packages/modules/requests/src/api/vendor/requests/route.ts

import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework";
import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
import { fetchSellerByAuthActorId } from "@mercurjs/framework";
import { createRequestWorkflow } from "../../../workflows/requests/workflows";
import { VendorCreateRequestType } from "./validators";

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorCreateRequestType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);

  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  );

  const { result } = await createRequestWorkflow.run({
    input: {
      data: {
        submitter_id: req.auth_context.actor_id,
        ...req.validatedBody.request,
      },
      seller_id: seller.id,
    },
    container: req.scope,
  });

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

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

Steps

createRequestStep: Creates the request record.
createRemoteLinkStep: Links the request to the seller.
emitEventStep: Emits a requests.*.created event.

Hooks

requestCreated: Hook that fires after a request is created, providing the requestId and sellerId.

Input

input

object

required

The request creation details.

Show properties

data

CreateRequestDTO

required

The request data.

Show properties

type

string

required

The type of request (e.g., “product_category”, “product_collection”, “product_type”, “product_tag”, “review_remove”).

data

any

required

The data for the resource to be created upon approval.

submitter_id

string

required

The ID of the member submitting the request.

status

RequestStatus

The initial status (defaults to “pending”).

seller_id

string

required

The ID of the seller creating the request.

Output

RequestDTO[]

Array containing the created request.

createSellerCreationRequestWorkflow

This documentation provides a reference to the createSellerCreationRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates a seller registration request and emits events for notification and tracking. It exposes a hook for custom extensions. Source code

Examples

Subscriber

packages/modules/requests/src/subscribers/seller-creation-request-to-create.ts

import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";
import { CreateRequestDTO, SellerRequest } from "@mercurjs/framework";
import { createSellerCreationRequestWorkflow } from "../workflows";

export default async function sellerCreationRequestToCreateHandler({
  event,
  container,
}: SubscriberArgs<CreateRequestDTO>) {
  const input = event.data;

  await createSellerCreationRequestWorkflow.run({
    container,
    input,
  });
}

export const config: SubscriberConfig = {
  event: SellerRequest.TO_CREATE,
  context: {
    subscriberId: "seller-creation-request-to-create",
  },
};

Steps

createRequestStep: Creates the request record.
emitMultipleEventsStep: Emits seller_request.created and requests.*.created events.

Hooks

sellerCreationRequestCreated: Hook that fires after a seller creation request is created, providing the requestId.

Input

input

CreateRequestDTO

required

The seller creation request data.

Show properties

type

string

required

The request type (should be “seller”).

data

any

required

The seller data to be created upon approval.

submitter_id

string

required

The ID of the user submitting the request.

status

RequestStatus

The initial status (defaults to “pending”).

Output

RequestDTO[]

Array containing the created request.

importSellerProductsRequestWorkflow

This documentation provides a reference to the importSellerProductsRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow creates multiple product requests from a CSV import. It creates request records for each product, links them to the seller, and emits events for each created request. Source code

Examples

Subscriber

packages/modules/requests/src/subscribers/import-seller-products-to-create.ts

import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";
import {
  CreateRequestDTO,
  ImportSellerProductsRequestUpdatedEvent,
} from "@mercurjs/framework";
import {
  importSellerProductsRequestWorkflow,
} from "../workflows";

export default async function sellerCreationRequestToCreateHandler({
  event,
  container,
}: SubscriberArgs<{
  seller_id: string;
  request_payloads: CreateRequestDTO[];
}>) {
  const input = event.data;

  await importSellerProductsRequestWorkflow.run({
    container,
    input,
  });
}

export const config: SubscriberConfig = {
  event: ImportSellerProductsRequestUpdatedEvent.TO_CREATE,
  context: {
    subscriberId: "import-seller-products-to-create",
  },
};

Steps

createRequestStep: Creates multiple request records.
createRemoteLinkStep: Links each request to the seller.
emitMultipleEventsStep: Emits product_request.created events for each request.

Input

input

object

required

The bulk product request creation details.

Show properties

seller_id

string

required

The ID of the seller importing products.

request_payloads

CreateRequestDTO[]

required

Array of request payloads for each imported product.

Output

RequestDTO[]

Array of created requests.

updateRequestDataWorkflow

This documentation provides a reference to the updateRequestDataWorkflow. It belongs to the @mercurjs/requests package. This workflow updates the data field of a pending or draft request. It’s used to modify request details before they’re reviewed. Source code

Steps

updateRequestDataStep: Updates the request data after validation.

Input

input

UpdateRequestDataDTO

required

The request data update details.

Show properties

string

required

The ID of the request to update.

type

string

required

The type of the request (must match existing request type).

data

any

required

The new data to merge with existing request data.

Output

RequestDTO

The updated request.

updateRequestWorkflow

This documentation provides a reference to the updateRequestWorkflow. It belongs to the @mercurjs/requests package. This workflow updates a request’s status and reviewer information, updates related product status if rejected, and emits a status-specific event. It exposes a hook for custom extensions. Source code

Examples

API Route

packages/modules/requests/src/api/admin/requests/[id]/route.ts

import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { updateRequestWorkflow } from '../../../../workflows/requests/workflows'

// For rejection
await updateRequestWorkflow.run({
  input: {
    id: req.params.id,
    reviewer_id: req.auth_context.actor_id,
    ...req.validatedBody
  },
  container: req.scope
})

Steps

updateRequestStep: Updates the request record.
updateRelatedProductStatusStep: Updates product status to “rejected” if applicable.
emitEventStep: Emits a dynamic event based on request type and status (e.g., requests.product.accepted).

Hooks

requestUpdated: Hook that fires after a request is updated, providing the request id.

Input

input

UpdateRequestDTO

required

The request update details.

Show properties

string

required

The ID of the request to update.

reviewer_id

string

The ID of the reviewer.

reviewer_note

string

The reviewer’s note.

status

RequestStatus

required

The new status (“accepted”, “rejected”, “pending”, or “draft”).

Output

RequestDTO

The updated request.

Show properties

string

The ID of the request.

type

string

The type of request.

status

RequestStatus

The updated status.

reviewer_id

string

The ID of the reviewer.

reviewer_note

string

The reviewer’s note.

Steps

createRequestStep

Creates one or more request records in the database. Accepts either a single request or an array of requests. Source code

Input

input

CreateRequestDTO | CreateRequestDTO[]

required

The request(s) to create.

Output

RequestDTO[]

Array of created requests.

updateRelatedProductStatusStep

Updates the status of a product related to a request. Specifically handles product and product_update request types that have been rejected by setting the product status to “rejected”. Source code

Input

string

required

The ID of the request to check and process.

Output

This step does not return a value.

updateRequestDataStep

Updates the data field of a request. Validates that the request is in “pending” or “draft” status and that the request type matches before merging the new data with existing data. Source code

Input

input

UpdateRequestDataDTO

required

The request data update details.

Output

RequestDTO

The updated request. Throws an INVALID_DATA error if:

Request is not in “pending” or “draft” status
Request type doesn’t match

updateRequestStep

Updates a request record in the database with new status and reviewer information. Source code

Input

input

UpdateRequestDTO

required

The request update details.

Output

RequestDTO

The updated request.

Quick start

Components

Core Concepts

Product

Integrations

Deployment

Development

Help

​Workflows

​acceptProductCategoryRequestWorkflow

​Examples

​Steps

​Input

​Output

​acceptProductCollectionRequestWorkflow

​Steps

​Input

​Output

​acceptProductRequestWorkflow

​Steps

​Input

​Output

​acceptProductTagRequestWorkflow

​Steps

​Input

​Output

​acceptProductTypeRequestWorkflow

​Steps

​Input

​Output

​acceptReviewRemoveRequestWorkflow

​Steps

​Input

​Output

​acceptSellerCreationRequestWorkflow

​Steps

​Input

​Output

​createProductRequestWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​createProductUpdateRequestWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​createRequestWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​createSellerCreationRequestWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​importSellerProductsRequestWorkflow

​Examples

​Steps

​Input

​Output

​updateRequestDataWorkflow

​Steps

​Input

​Output

​updateRequestWorkflow

​Examples

​Steps

​Hooks

​Input

​Output

​Steps

​createRequestStep

​Input

Workflows

acceptProductCategoryRequestWorkflow

Examples

Steps

Input

Output

acceptProductCollectionRequestWorkflow

Steps

Input

Output

acceptProductRequestWorkflow

Steps

Input

Output

acceptProductTagRequestWorkflow

Steps

Input

Output

acceptProductTypeRequestWorkflow

Steps

Input

Output

acceptReviewRemoveRequestWorkflow

Steps

Input

Output

acceptSellerCreationRequestWorkflow

Steps

Input

Output

createProductRequestWorkflow

Examples

Steps

Hooks

Input

Output

createProductUpdateRequestWorkflow

Examples

Steps

Hooks

Input

Output

createRequestWorkflow

Examples

Steps

Hooks

Input

Output

createSellerCreationRequestWorkflow

Examples

Steps

Hooks

Input

Output

importSellerProductsRequestWorkflow

Examples

Steps

Input

Output

updateRequestDataWorkflow

Steps

Input

Output

updateRequestWorkflow

Examples

Steps

Hooks

Input

Output

Steps

createRequestStep

Input

Output

updateRelatedProductStatusStep

Input

Output

updateRequestDataStep

Input

Output

updateRequestStep