Skip to main content

Workflows

acceptMemberInvitesWorkflow

This documentation provides a reference to the acceptMemberInvitesWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow accepts a member invitation by validating the invite token, creating a new member, updating the invite status, and linking the new member to the authentication system. Source code

Examples

packages/modules/b2c-core/src/api/vendor/invites/accept/route.ts
import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework";
import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
import { acceptMemberInvitesWorkflow } from "../../../../workflows/seller/workflows";
import { VendorAcceptMemberInviteType } from "../validators";

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

  const { result } = await acceptMemberInvitesWorkflow(req.scope).run({
    input: {
      invite: req.validatedBody,
      authIdentityId: req.auth_context.auth_identity_id,
    },
  });

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

  res.json({ invite });
};

Steps

Input

input
object
required
The invite acceptance details.

Output

MemberInviteDTO
MemberInviteDTO
The accepted member invite.

createOnboardingForSellerWorkflow

This documentation provides a reference to the createOnboardingForSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow creates a payout onboarding flow for a seller. It validates that the seller has a payout account and then initializes the onboarding process with the payment provider. Source code

Examples

packages/modules/b2c-core/src/api/vendor/payout-account/onboarding/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../../shared/infra/http/utils'
import { createOnboardingForSellerWorkflow } from '../../../../workflows/seller/workflows'
import { VendorCreateOnboardingType } from '../validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorCreateOnboardingType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  )

  const { result } = await createOnboardingForSellerWorkflow(req.scope).run({
    context: { transactionId: seller.id },
    input: {
      seller_id: seller.id,
      context: req.validatedBody.context ?? {}
    }
  })

  const {
    data: [payoutAccount]
  } = await query.graph(
    {
      entity: 'payout_account',
      fields: req.queryConfig.fields,
      filters: {
        id: result.payout_account_id
      }
    },
    { throwIfKeyNotFound: true }
  )

  res.status(200).json({
    payout_account: payoutAccount
  })
}

Steps

Input

input
object
required
The onboarding creation details.

Output

OnboardingDTO
OnboardingDTO
The created onboarding.

createPayoutAccountForSellerWorkflow

This documentation provides a reference to the createPayoutAccountForSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow creates a payout account for a seller and links it to the seller. It validates that no payout account already exists for the seller and then creates the account with the payment provider. This workflow is idempotent. Source code

Examples

packages/modules/b2c-core/src/api/vendor/payout-account/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../shared/infra/http/utils'
import {
  createPayoutAccountForSellerWorkflow,
} from '../../../workflows/seller/workflows'
import { VendorCreatePayoutAccountType } from './validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorCreatePayoutAccountType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  )

  const { result } = await createPayoutAccountForSellerWorkflow(req.scope).run({
    context: { transactionId: seller.id },
    input: {
      seller_id: seller.id,
      context: req.validatedBody.context ?? {}
    }
  })

  const {
    data: [payoutAccount]
  } = await query.graph(
    {
      entity: 'payout_account',
      fields: req.queryConfig.fields,
      filters: {
        id: result.id
      }
    },
    { throwIfKeyNotFound: true }
  )

  res.status(201).json({
    payout_account: payoutAccount
  })
}

Steps

Input

input
object
required
The payout account creation details.

Output

PayoutAccountDTO
PayoutAccountDTO
The created payout account.

createSellerWorkflow

This documentation provides a reference to the createSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow creates a new seller in the marketplace, including creating the initial member, setting up seller onboarding, linking to authentication, and creating a default shipping profile. It exposes a sellerCreated hook for custom extensions. Source code

Steps

Hooks

  • sellerCreated: Hook that fires after a seller is created, providing the sellerId.

Input

input
object
required
The seller creation details.

Output

SellerDTO
SellerDTO
The created seller.

createVendorPromotionWorkflow

This documentation provides a reference to the createVendorPromotionWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow creates a promotion for a seller. It validates that the campaign belongs to the seller, that the target type is items only, and that all targeted products belong to the seller. Source code

Examples

packages/modules/b2c-core/src/api/vendor/promotions/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../shared/infra/http/utils'
import { createVendorPromotionWorkflow } from '../../../workflows/promotions/workflows'
import { VendorCreatePromotionType } from './validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorCreatePromotionType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const seller = await fetchSellerByAuthActorId(
    req.auth_context?.actor_id,
    req.scope
  )

  const { result } = await createVendorPromotionWorkflow.run({
    container: req.scope,
    input: { promotion: req.validatedBody, seller_id: seller.id }
  })

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

  res.status(201).json({ promotion })
}

Steps

Input

input
object
required
The promotion creation details.

Output

PromotionDTO[]
PromotionDTO[]
Array containing the created promotion.

deleteMemberInvitesWorkflow

This documentation provides a reference to the deleteMemberInvitesWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow deletes a member invitation. Source code

Steps

Input

id
string
required
The ID of the member invite to delete.

Output

This workflow does not return a value.

deleteMemberWorkflow

This documentation provides a reference to the deleteMemberWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow deletes a member from a seller’s team. Source code

Steps

Input

id
string
required
The ID of the member to delete.

Output

This workflow does not return a value.

deleteSellerWorkflow

This documentation provides a reference to the deleteSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow deletes a seller from the marketplace. Source code

Steps

Input

id
string
required
The ID of the seller to delete.

Output

This workflow does not return a value.

exportSellerProductsWorkflow

This documentation provides a reference to the exportSellerProductsWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow exports all products for a seller to a CSV file. It retrieves the seller’s products and generates a downloadable CSV file containing product details, variants, and pricing information. Source code

Examples

packages/modules/b2c-core/src/api/vendor/products/export/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { fetchSellerByAuthActorId } from '../../../../shared/infra/http/utils'
import { exportSellerProductsWorkflow } from '../../../../workflows/seller/workflows'

export const POST = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) => {
  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  )

  const { result: fileData } = await exportSellerProductsWorkflow.run({
    container: req.scope,
    input: seller.id
  })

  res.json({
    url: fileData.url
  })
}

Steps

  • getSellerProductsStep: Retrieves all products for the seller.
  • generateProductCsvStep: Generates a CSV file from the product data using Medusa’s core step.
  • useRemoteQueryStep: Retrieves the file details including the download URL.

Input

seller_id
string
required
The ID of the seller whose products to export.

Output

FileDTO
FileDTO
The generated CSV file details.

importSellerProductsWorkflow

This documentation provides a reference to the importSellerProductsWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow imports products from a CSV file for a seller. It parses the CSV, validates the products, creates them with “proposed” status, and emits an event to create product requests for admin approval. Source code

Examples

packages/modules/b2c-core/src/api/vendor/products/import/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { MedusaError } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../../shared/infra/http/utils'
import { importSellerProductsWorkflow } from '../../../../workflows/seller/workflows'

export const POST = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) => {
  const input = (req as any).file

  if (!input) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      'No file was uploaded for importing'
    )
  }

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

  const { result: products } = await importSellerProductsWorkflow.run({
    container: req.scope,
    input: {
      file_content: input.buffer.toString('utf-8'),
      seller_id: seller.id,
      submitter_id: req.auth_context.actor_id
    }
  })

  res.status(201).json({ products })
}

Steps

  • parseProductCsvStep: Parses the CSV file into product objects using Medusa’s core step.
  • validateProductsToImportStep: Validates and transforms products, setting status to “proposed”.
  • createProductsWorkflow: Creates the products using Medusa’s core workflow.
  • emitEventStep: Emits an event to trigger product request creation.

Input

input
object
required
The product import details.

Output

ProductDTO[]
ProductDTO[]
Array of created products (in proposed status).

inviteMemberWorkflow

This documentation provides a reference to the inviteMemberWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow creates a member invitation for a seller’s team. Source code

Examples

packages/modules/b2c-core/src/api/vendor/invites/route.ts
import {
  AuthenticatedMedusaRequest,
  MedusaResponse,
} from "@medusajs/framework";
import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
import { fetchSellerByAuthActorId } from "../../../shared/infra/http/utils";
import { inviteMemberWorkflow } from "../../../workflows/seller/workflows";
import { VendorInviteMemberType } from "./validators";

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

  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope,
    ["id", "name"]
  );

  const { result: created } = await inviteMemberWorkflow(req.scope).run({
    input: {
      ...req.validatedBody,
      seller_id: seller.id,
    },
  });

  // ... query invite and emit event

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

Steps

Input

input
CreateMemberInviteDTO
required
The invitation details.

Output

MemberInviteDTO
MemberInviteDTO
The created member invitation.

inviteSellerWorkflow

This documentation provides a reference to the inviteSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow sends an invitation email to a potential seller to join the marketplace platform. Source code

Examples

packages/modules/b2c-core/src/api/admin/sellers/invite/route.ts
import { MedusaRequest, MedusaResponse } from '@medusajs/framework'
import { inviteSellerWorkflow } from '../../../../workflows/seller/workflows'
import { AdminInviteSellerType } from '../validators'

export async function POST(
  req: MedusaRequest<AdminInviteSellerType>,
  res: MedusaResponse
): Promise<void> {
  const { result: invitation } = await inviteSellerWorkflow.run({
    container: req.scope,
    input: req.validatedBody
  })

  res.status(201).json({ invitation })
}

Steps

Input

input
CreateSellerInvitationDTO
required
The invitation details.

Output

NotificationDTO
NotificationDTO
The notification details for the sent invitation email.

recalculateOnboardingWorkflow

This documentation provides a reference to the recalculateOnboardingWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow recalculates a seller’s onboarding status by checking various completion criteria including store information, products added, shipping locations configured, and Stripe connection established. Source code

Examples

packages/modules/b2c-core/src/api/vendor/sellers/me/onboarding/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../../../shared/infra/http/utils'
import { recalculateOnboardingWorkflow } from '../../../../../workflows/seller/workflows'

export const POST = async (
  req: AuthenticatedMedusaRequest,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const seller = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  )

  await recalculateOnboardingWorkflow.run({
    container: req.scope,
    input: seller.id
  })

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

  res.json({ onboarding })
}

Steps

Input

seller_id
string
required
The ID of the seller to recalculate onboarding for.

Output

SellerOnboardingDTO
SellerOnboardingDTO
The updated onboarding status.

syncStripeAccountWorkflow

This documentation provides a reference to the syncStripeAccountWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow synchronizes the status of a payout account with the payment provider (Stripe Connect). It retrieves the latest account status from the provider and updates the local record. Source code

Examples

packages/modules/b2c-core/src/api/vendor/payout-account/route.ts
import { syncStripeAccountWorkflow } from '../../../workflows/seller/workflows'

// Inside GET handler
if (payout_account.status !== 'active') {
  await syncStripeAccountWorkflow.run({
    container: req.scope,
    input: payout_account.id
  })

  // Refresh payout account data
}

Steps

Input

account_id
string
required
The ID of the payout account to synchronize.

Output

PayoutAccountDTO
PayoutAccountDTO
The synchronized payout account.

updateMemberWorkflow

This documentation provides a reference to the updateMemberWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow updates a member’s details. Source code

Steps

Input

input
UpdateMemberDTO
required
The member update details.

Output

MemberDTO
MemberDTO
The updated member.

updateSellerWorkflow

This documentation provides a reference to the updateSellerWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow updates a seller’s details. Source code

Examples

packages/modules/b2c-core/src/api/vendor/sellers/me/route.ts
import { AuthenticatedMedusaRequest, MedusaResponse } from '@medusajs/framework'
import { ContainerRegistrationKeys } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../../shared/infra/http/utils/seller'
import { updateSellerWorkflow } from '../../../../workflows/seller/workflows'
import { VendorUpdateSellerType } from '../validators'

export const POST = async (
  req: AuthenticatedMedusaRequest<VendorUpdateSellerType>,
  res: MedusaResponse
) => {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const { id } = await fetchSellerByAuthActorId(
    req.auth_context.actor_id,
    req.scope
  )

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

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

  res.json({ seller })
}

Steps

Input

input
UpdateSellerDTO
required
The seller update details.

Output

SellerDTO
SellerDTO
The updated seller.

Steps

createMemberInviteStep

Creates a member invitation record. If an error occurs after creation, the step’s compensation function automatically deletes the created invite. Source code

Input

input
CreateMemberInviteDTO
required
The invitation details.

Output

MemberInviteDTO
MemberInviteDTO
The created member invitation.

createMemberStep

Creates a member for a seller. If an error occurs after creation, the step’s compensation function automatically deletes the created member. Source code

Input

input
CreateMemberDTO
required
The member details.

Output

MemberDTO
MemberDTO
The created member.

createPayoutAccountStep

Creates a payout account with the payment provider. If an error occurs after creation, the step’s compensation function automatically deletes the created account. Source code

Input

input
CreatePayoutAccountDTO
required
The payout account details.

Output

PayoutAccountDTO
PayoutAccountDTO
The created payout account.

createPayoutOnboardingStep

Initializes an onboarding flow for a payout account with the payment provider (e.g., creates a Stripe Connect onboarding link). Source code

Input

input
CreateOnboardingDTO
required
The onboarding initialization details.

Output

OnboardingDTO
OnboardingDTO
The created onboarding with provider-specific data (e.g., onboarding URL).

createSellerOnboardingStep

Creates an onboarding record for a newly created seller to track their setup progress. Source code

Input

input
SellerDTO
required
The seller for which to create onboarding.

Output

SellerOnboardingDTO
SellerOnboardingDTO
The created onboarding record.

createSellerShippingProfileStep

Creates a default shipping profile for a seller and links it to the seller. This enables the seller to configure shipping options. Source code

Input

input
SellerDTO
required
The seller for which to create the shipping profile.

Output

This step does not return a value.

createSellerStep

Creates a seller record. It automatically generates a URL-friendly handle from the seller name. If an error occurs after creation, the step’s compensation function automatically deletes the created seller. Source code

Input

input
CreateSellerDTO
required
The seller details.

Output

SellerDTO
SellerDTO
The created seller with auto-generated handle.

deleteMemberInvitesStep

Deletes a member invitation. Source code

Input

id
string
required
The ID of the invitation to delete.

Output

This step does not return a value.

deleteMemberStep

Deletes a member from a seller’s team. Source code

Input

id
string
required
The ID of the member to delete.

Output

This step does not return a value.

deleteSellerStep

Deletes a seller from the marketplace. Source code

Input

id
string
required
The ID of the seller to delete.

Output

This step does not return a value.

getSellerProductsStep

Retrieves all products for a seller with comprehensive fields including variants, prices, options, tags, and images. Used for product export functionality. Source code

Input

seller_id
string
required
The ID of the seller whose products to retrieve.

Output

ProductDTO[]
ProductDTO[]
Array of products with full details including variants, prices, options, tags, and images.

recalculateOnboardingStep

Recalculates a seller’s onboarding status by checking multiple completion criteria:
  • Store information completeness (name, address, tax ID, etc.)
  • Products added
  • Shipping locations configured
  • Stripe connection established
Source code

Input

seller_id
string
required
The ID of the seller to recalculate onboarding for.

Output

SellerOnboardingDTO
SellerOnboardingDTO
The updated onboarding status with boolean flags for each completion criterion.

sendSellerInvitationEmailStep

Sends an invitation email to a potential seller with a registration link. Throws an error if the notification provider fails. Source code

Input

input
CreateSellerInvitationDTO
required
The invitation details.

Output

NotificationDTO
NotificationDTO
The sent notification details.

syncStripeAccountStep

Synchronizes a payout account’s status with the payment provider by fetching the latest account details from Stripe Connect. Source code

Input

account_id
string
required
The ID of the payout account to synchronize.

Output

PayoutAccountDTO
PayoutAccountDTO
The synchronized payout account.

updateMemberInviteStep

Updates a member invitation, typically to mark it as accepted. Source code

Input

input
object
required

Output

MemberInviteDTO
MemberInviteDTO
The updated member invitation.

updateMemberStep

Updates a member’s details. Source code

Input

input
UpdateMemberDTO
required
The member update details.

Output

MemberDTO
MemberDTO
The updated member.

updateSellerStep

Updates a seller’s details. Source code

Input

input
UpdateSellerDTO
required
The seller update details.

Output

SellerDTO
SellerDTO
The updated seller.

validateMemberInviteStep

Validates a member invitation token and retrieves the associated invite details. Source code

Input

input
AcceptMemberInviteDTO
required
The invite acceptance data including the token.

Output

MemberInviteDTO
MemberInviteDTO
The validated member invite with seller details.

validateNoExistingPayoutAccountForSellerStep

Validates that a seller does not already have a payout account. Throws an error if a payout account exists. Source code

Input

sellerId
string
required
The ID of the seller to check.

Output

void
void
Throws a DUPLICATE_ERROR if a payout account already exists.

validatePayoutAccountExistsForSellerStep

Validates that a seller has a payout account. Throws an error if no payout account exists and returns the payout account ID if found. Source code

Input

sellerId
string
required
The ID of the seller to check.

Output

object
object

validateProductsToImportStep

Validates products from a CSV import, parses them according to the product schema, and sets their status to “proposed” for admin approval. Source code

Input

products
unknown[]
required
Array of product objects parsed from CSV.

Output

CreateProductDTO[]
CreateProductDTO[]
Array of validated product creation DTOs with status set to “proposed”.

verifyVendorCampaignStep

Validates that a campaign belongs to the seller. If no campaign is specified, the validation is skipped. Source code

Input

input
object
required

Output

void
void
Throws an INVALID_DATA error if the campaign doesn’t belong to the seller.

verifyVendorPromotionStep

Validates that a vendor promotion uses the correct target type. Vendor promotions must target items only. Source code

Input

input
object
required

Output

void
void
Throws an INVALID_DATA error if target_type is not “items”.

verifyVendorTargetPromotionRulesStep

Validates that target promotion rules only use the allowed attribute (items.product.id) and that all targeted products belong to the seller. Source code

Input

input
object
required

Output

void
void
Throws an INVALID_DATA error if:
  • Rules use attributes other than “items.product.id”
  • Any targeted product doesn’t belong to the seller