Skip to main content

​
Workflows

​
batchVendorPromotionRulesWorkflow

This documentation provides a reference to the batchVendorPromotionRulesWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow performs batch operations on promotion rules, including creating and deleting rules. When creating target rules, it validates that the seller owns all products being targeted by the rules. Source code

​
Examples

packages/modules/b2c-core/src/api/vendor/promotions/[id]/target-rules/batch/route.ts
import {
  AuthenticatedMedusaRequest,
  MedusaResponse
} from '@medusajs/framework/http'
import { ContainerRegistrationKeys, RuleType } from '@medusajs/framework/utils'
import { fetchSellerByAuthActorId } from '../../../../../../shared/infra/http/utils'
import { batchVendorPromotionRulesWorkflow } from '../../../../../../workflows/promotions/workflows'
import { VendorBatchPromotionRulesType } from '../../../validators'

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

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

  await batchVendorPromotionRulesWorkflow(req.scope).run({
    input: {
      data: {
        id,
        rule_type: RuleType.TARGET_RULES,
        create: req.validatedBody.create,
        delete: req.validatedBody.delete
      },
      seller_id: seller.id
    }
  })

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

  res.json({ promotion })
}

​
Steps

  • verifyVendorTargetPromotionRulesStep: Validates seller ownership of products in target rules (only for target_rules type).
  • batchPromotionRulesWorkflow: Creates and deletes promotion rules using Medusa’s core workflow.

​
Input

​
input
object
required
The batch promotion rules operation details.

​
Output

This workflow does not return a value.

​
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 and links it to the seller. It validates that the seller owns the campaign (if specified), that the promotion uses the correct target type, 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

  • verifyVendorCampaignStep: Validates that the campaign (if specified) belongs to the seller.
  • verifyVendorPromotionStep: Validates that the promotion uses the correct target type (items only).
  • verifyVendorTargetPromotionRulesStep: Validates that all targeted products belong to the seller.
  • createPromotionsWorkflow: Creates the promotion using Medusa’s core workflow.
  • createRemoteLinkStep: Links the promotion (and optionally the campaign) to the seller.

​
Input

​
input
object
required
The promotion creation details.

​
Output

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

​
updateVendorPromotionWorkflow

This documentation provides a reference to the updateVendorPromotionWorkflow. It belongs to the @mercurjs/b2c-core package. This workflow updates an existing promotion. It validates that any new campaign association belongs to the seller. Source code

​
Examples

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

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

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

  await updateVendorPromotionWorkflow.run({
    container: req.scope,
    input: {
      promotion: {
        id: req.params.id,
        ...req.validatedBody
      },
      seller_id: seller.id
    }
  })

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

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

​
Steps

  • verifyVendorCampaignStep: Validates that the campaign (if being updated) belongs to the seller.
  • updatePromotionsWorkflow: Updates the promotion using Medusa’s core workflow.

​
Input

​
input
object
required
The promotion update details.

​
Output

​
PromotionDTO[]
PromotionDTO[]
Array containing the updated promotion.

​
Steps

​
registerUsageStep

Registers promotion usage when a promotion is applied to a cart. This step tracks how many times a promotion code has been used and includes a compensation function to revert the usage if the order is not completed. Source code

​
Examples

packages/modules/b2c-core/src/workflows/cart/workflows/split-and-complete-cart.ts
import { registerUsageStep } from "../../promotions/steps";

// ... inside splitAndCompleteCartWorkflow

const promotionUsage = transform(
  { lineItemAdjustments, shippingAdjustments },
  ({ lineItemAdjustments, shippingAdjustments }) => {
    const promotionUsage = [];

    for (const adjustment of lineItemAdjustments) {
      promotionUsage.push({
        amount: adjustment.amount,
        code: adjustment.code!,
      });
    }

    for (const adjustment of shippingAdjustments) {
      promotionUsage.push({
        amount: adjustment.amount,
        code: adjustment.code!,
      });
    }

    return promotionUsage;
  }
);

registerUsageStep(promotionUsage);

​
Input

​
data
UsageComputedActions[]
required
Array of promotion usage records to register.

​
Output

This step does not return a value.

​
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, not shipping or order totals. Source code

​
Input

​
input
object
required

​
Output

​
void
void
Throws an INVALID_DATA error if the 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. This ensures vendors can only create promotions for their own products. 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