Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

IPromotionModuleService

The main service interface for the Promotion Module.

Methods​

registerUsage​

This method adjusts the budget for each campaign associated with the promotions' specified computed actions. It adjusts the used property of a CampaignBudget to account for the adjustment amounts in the specified associated computed actions.

Example​

await promotionModuleService.registerUsage([
  {
    action: "addItemAdjustment",
    item_id: "cali_123",
    amount: 50,
    code: "50OFF",
  },
  {
    action: "addShippingMethodAdjustment",
    shipping_method_id: "casm_123",
    amount: 5000,
    code: "FREESHIPPING",
  },
])

Parameters​

computedActionsComputeActions[]Required
The computed actions to adjust their promotion's campaign budget.

Returns​

PromisePromise<void>Required
Resolves when the campaign budgets have been adjusted successfully.

computeActions​

This method provides the actions to perform on a cart based on the specified promotions and context.

Example​

const actions = await promotionModuleService.computeActions(
  ["50OFF"],
  {
    items: [
      {
        id: "cali_123",
        quantity: 2,
        subtotal: 1000,
      },
    ],
    shipping_methods: [
      {
        id: "casm_123",
        subtotal: 0,
        adjustments: [
          {
            id: "adj_123",
            code: "FREESHIPPING",
          },
        ],
      },
    ],
  }
)

Parameters​

promotionCodesToApplystring[]Required
The promotion codes to be applied on the cart.
applicationContextComputeActionContextRequired
The items and shipping methods of the cart.
optionsRecord<string, any>
Any relevant options that may change how the actions are computed.

Returns​

PromisePromise<ComputeActions[]>Required
The list of computed actions to be applied on the cart.

create​

**create**(data, sharedContext?): Promise&#60;[PromotionDTO](types.PromotionTypes.PromotionDTO.mdx)[]&#62;

This method creates promotions.

Example​

const promotions = await promotionModuleService.create([
  {
    code: "50OFF",
    type: "standard",
    application_method: {
      type: "percentage",
      target_type: "items",
      value: 50,
    },
  },
  {
    code: "FREESHIPPING",
    type: "standard",
    application_method: {
      type: "percentage",
      target_type: "shipping_methods",
      value: 100,
    },
  },
  {
    code: "BUY2GET1",
    type: "buyget",
    application_method: {
      type: "fixed",
      target_type: "items",
      buy_rules_min_quantity: 2,
      apply_to_quantity: 1,
      buy_rules: [
        {
          attribute: "SKU",
          operator: "eq",
          values: ["SHIRT"],
        },
      ],
    },
  },
])

Parameters​

dataCreatePromotionDTO[]Required
The promotions to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO[]>Required
The created promotions.

**create**(data, sharedContext?): Promise&#60;[PromotionDTO](types.PromotionTypes.PromotionDTO.mdx)&#62;

This method creates a promotion.

Example​

const promotionA = await promotionModuleService.create({
  code: "50OFF",
  type: "standard",
  application_method: {
    type: "percentage",
    target_type: "items",
    value: 50,
  },
})

const promotionB = await promotionModuleService.create({
  code: "FREESHIPPING",
  type: "standard",
  application_method: {
    type: "percentage",
    target_type: "shipping_methods",
    value: 100,
  },
})

const promotionC = await promotionModuleService.create({
  code: "BUY2GET1",
  type: "buyget",
  application_method: {
    type: "fixed",
    target_type: "items",
    buy_rules_min_quantity: 2,
    apply_to_quantity: 1,
    buy_rules: [
      {
        attribute: "SKU",
        operator: "eq",
        values: ["SHIRT"],
      },
    ],
  },
})

Parameters​

dataCreatePromotionDTORequired
The promotion to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO>Required
The created promotion.

update​

**update**(data, sharedContext?): Promise&#60;[PromotionDTO](types.PromotionTypes.PromotionDTO.mdx)[]&#62;

This method updates existing promotions.

Example​

const promotions = await promotionModuleService.update([
  {
    id: "promo_123",
    is_automatic: true,
  },
])

Parameters​

dataUpdatePromotionDTO[]Required
The attributes to update in the promotions.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO[]>Required
The updated promotions.

**update**(data, sharedContext?): Promise&#60;[PromotionDTO](types.PromotionTypes.PromotionDTO.mdx)&#62;

This method updates an existing promotion.

Example​

const promotion = await promotionModuleService.update({
  id: "promo_123",
  is_automatic: true,
})

Parameters​

dataUpdatePromotionDTORequired
The attributes to update in the promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO>Required
The updated promotion.

list​

This method retrieves a paginated list of promotions based on optional filters and configuration.

Example​

To retrieve a list of promotions using their IDs:

const promotions = await promotionModuleService.list({
  id: ["promo_123", "promo_321"],
})

To specify relations that should be retrieved within the promotions:

const promotions = await promotionModuleService.list(
  {
    id: ["promo_123", "promo_321"],
  },
  {
    relations: ["application_method"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const promotions = await promotionModuleService.list(
  {
    id: ["promo_123", "promo_321"],
  },
  {
    relations: ["application_method"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterablePromotionProps
The filters to apply on the retrieved promotions.
configFindConfig<PromotionDTO>
The configurations determining how the promotion is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO[]>Required
The list of promotions.

listAndCount​

This method retrieves a paginated list of promotions along with the total count of available promotions satisfying the provided filters.

Example​

To retrieve a list of promotions using their IDs:

const [promotions, count] =
  await promotionModuleService.listAndCount({
    id: ["promo_123", "promo_321"],
  })

To specify relations that should be retrieved within the promotions:

const [promotions, count] =
  await promotionModuleService.listAndCount(
    {
      id: ["promo_123", "promo_321"],
    },
    {
      relations: ["application_method"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const [promotions, count] =
  await promotionModuleService.listAndCount(
    {
      id: ["promo_123", "promo_321"],
    },
    {
      relations: ["application_method"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePromotionProps
The filters to apply on the retrieved promotions.
configFindConfig<PromotionDTO>
The configurations determining how the promotion is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[PromotionDTO[], number]>Required
The list of promotions along with their total count.

retrieve​

This method retrieves a promotion by its ID.

Example​

A simple example that retrieves a promotion by its ID:

const promotion =
  await promotionModuleService.retrieve("promo_123")

To specify relations that should be retrieved:

const promotion = await promotionModuleService.retrieve(
  "promo_123",
  {
    relations: ["application_method"],
  }
)

Parameters​

idstringRequired
The ID of the promotion.
configFindConfig<PromotionDTO>
The configurations determining how the promotion is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionDTO>Required
The retrieved promotion.

delete​

**delete**(ids, sharedContext?): Promise&#60;void&#62;

This method deletes promotions by their IDs.

Example​

await promotionModuleService.delete([
  "promo_123",
  "promo_321",
])

Parameters​

idsstring[]Required
The IDs of the promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the promotions are deleted.

**delete**(ids, sharedContext?): Promise&#60;void&#62;

This method deletes a promotion by its ID.

Example​

await promotionModuleService.delete("promo_123")

Parameters​

idsstringRequired
The IDs of the promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the promotion is deleted.

softDelete​

This method soft deletes a promotion by its IDs.

Example​

await promotionModuleService.softDelete("promo_123")

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

promotionIdsstring | string[]Required
The list of promotions to soft delete.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated application method. The object's keys are the ID attribute names of the promotion entity's relations, such as application_method_id, and its value is an array of strings, each being the ID of a record associated with the promotion through this relation, such as the IDs of associated application method. If there are no related records, the promise resolves to void.

restore​

This method restores soft deleted promotions by their IDs.

Example​

await promotionModuleService.restore("promo_123")

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

promotionIdsstring | string[]Required
The promotions' IDs.
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the promotion. You can pass to its returnLinkableKeys property any of the promotion's relation attribute names, such as application_method_id.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored, such as the ID of associated application method. The object's keys are the ID attribute names of the promotion entity's relations, such as application_method_id, and its value is an array of strings, each being the ID of the record associated with the promotion through this relation, such as the IDs of associated application method. If there are no related records restored, the promise resolves to void.

addPromotionRules​

This method adds promotion rules to a promotion.

Example​

const promotionRules =
  await promotionModuleService.addPromotionRules(
    "promo_123",
    [
      {
        attribute: "customer_group_id",
        operator: "in",
        values: ["VIP", "VVIP"],
      },
    ]
  )

Parameters​

promotionIdstringRequired
The promotion's ID.
rulesDataCreatePromotionRuleDTO[]Required
The promotion rules to be created and added to the promotion.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionRuleDTO[]>Required
The promotion rules created.

addPromotionTargetRules​

This method adds target promotion rules to a promotion's application method.

Example​

const targetPromotionRules =
  await promotionModuleService.addPromotionTargetRules(
    "promo_123",
    [
      {
        attribute: "SKU",
        operator: "eq",
        values: "SHIRT",
      },
    ]
  )

Parameters​

promotionIdstringRequired
The promotion's ID.
rulesDataCreatePromotionRuleDTO[]Required
The promotion rules to be created and added as target rules to the promotion's application method.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionRuleDTO[]>Required
The created promotion rules.

addPromotionBuyRules​

This method adds buy promotion rules to a promotion's application method.

Example​

const buyPromotionRules =
  await promotionModuleService.addPromotionBuyRules(
    "promo_123",
    [
      {
        attribute: "SKU",
        operator: "eq",
        values: "SHIRT",
      },
    ]
  )

Parameters​

promotionIdstringRequired
The promotion's ID.
rulesDataCreatePromotionRuleDTO[]Required
The promotion rules to be created and added as buy rules to the promotion's applicatio method.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionRuleDTO[]>Required
The created promotion rules.

removePromotionRules​

This method removes promotion rules from a promotion.

Example​

await promotionModuleService.removePromotionRules(
  "promo_123",
  ["prorul_123", "prorul_321"]
)

Parameters​

promotionIdstringRequired
The promotion's ID.
ruleIdsstring[]Required
The promotion rules' IDs.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the promotion rules are deleted successfully.

removePromotionTargetRules​

This method removes target promotion rules from a promotion's application method.

Example​

await promotionModuleService.removePromotionTargetRules(
  "promo_123",
  ["prorul_123", "prorul_321"]
)

Parameters​

promotionIdstringRequired
The promotion's ID.
ruleIdsstring[]Required
The target promotion rules' IDs.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the target promotion rules are deleted.

removePromotionBuyRules​

This method removes buy promotion rules from a promotion's application method.

Example​

await promotionModuleService.removePromotionBuyRules(
  "promo_123",
  ["prorul_123", "prorul_321"]
)

Parameters​

promotionIdstringRequired
The promotion's ID.
ruleIdsstring[]Required
The buy promotion rules' IDs.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the buy promotion rules are deleted.

createCampaigns​

**createCampaigns**(data, sharedContext?): Promise&#60;[CampaignDTO](types.PromotionTypes.CampaignDTO.mdx)&#62;

This method creates a campaign.

Example​

const campaign = await promotionModuleService.createCampaigns(
  {
    name: "Summer discounts",
    campaign_identifier: "G-123456",
    starts_at: new Date("2025-06-01"),
    ends_at: new Date("2025-09-01"),
    budget: {
      type: "usage",
      limit: 10,
    },
  }
)

Parameters​

dataCreateCampaignDTORequired
The campaign to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO>Required
The created campaign.

**createCampaigns**(data, sharedContext?): Promise&#60;[CampaignDTO](types.PromotionTypes.CampaignDTO.mdx)[]&#62;

This method creates campaigns.

Example​

const campaigns =
  await promotionModuleService.createCampaigns([
    {
      name: "Summer discounts",
      campaign_identifier: "G-123456",
      starts_at: new Date("2025-06-01"),
      ends_at: new Date("2025-09-01"),
      budget: {
        type: "usage",
        limit: 10,
      },
    },
  ])

Parameters​

dataCreateCampaignDTO[]Required
The campaigns to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO[]>Required
The created campaigns.

updateCampaigns​

**updateCampaigns**(data, sharedContext?): Promise&#60;[CampaignDTO](types.PromotionTypes.CampaignDTO.mdx)[]&#62;

This method updates existing campaigns.

Example​

const campaigns =
  await promotionModuleService.updateCampaigns([
    {
      id: "procamp_123",
      name: "Summer Sales",
    },
  ])

Parameters​

dataUpdateCampaignDTO[]Required
The attributes to update in the campaigns.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO[]>Required
The updated campaigns.

**updateCampaigns**(data, sharedContext?): Promise&#60;[CampaignDTO](types.PromotionTypes.CampaignDTO.mdx)&#62;

This method updates an existing campaign.

Example​

const campaigns =
  await promotionModuleService.updateCampaigns({
    id: "procamp_123",
    name: "Summer Sales",
  })

Parameters​

dataUpdateCampaignDTORequired
The attributes to update in the campaign.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO>Required
The updated campaign.

listPromotionRules​

This method retrieves a paginated list of promotion rules based on optional filters and configuration.

Example​

To retrieve a list of promotion rules using their IDs:

const promotionRules =
  await promotionModuleService.listPromotionRules({
    id: ["prorul_123", "prorul_321"],
  })

To specify relations that should be retrieved within the promotion rules:

const promotionRules =
  await promotionModuleService.listPromotionRules(
    {
      id: ["prorul_123", "prorul_321"],
    },
    {
      relations: ["promotions"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const promotionRules =
  await promotionModuleService.listPromotionRules(
    {
      id: ["prorul_123", "prorul_321"],
    },
    {
      relations: ["promotions"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterablePromotionRuleProps
The filters to apply on the retrieved promotion rules.
configFindConfig<PromotionRuleDTO>
The configurations determining how the promotion rule is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a promotion rule.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionRuleDTO[]>Required
The list of promotion rules.

updatePromotionRules​

This method updates existing promotion rules.

Example​

const promotionRules =
  await promotionModuleService.updatePromotionRules([
    {
      id: "prorul_123",
      description: "Only allow VIP customers",
    },
  ])

Parameters​

dataUpdatePromotionRuleDTO[]Required
The attributes to update in the promotion rules.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<PromotionRuleDTO[]>Required
The updated promotion rules.

listCampaigns​

This method retrieves a paginated list of campaigns based on optional filters and configuration.

Example​

To retrieve a list of campaigns using their IDs:

const campaigns = await promotionModuleService.listCampaigns({
  id: ["procamp_123"],
})

To specify relations that should be retrieved within the campaigns:

const campaigns = await promotionModuleService.listCampaigns(
  {
    id: ["procamp_123"],
  },
  {
    relations: ["promotions"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const campaigns = await promotionModuleService.listCampaigns(
  {
    id: ["procamp_123"],
  },
  {
    relations: ["promotions"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableCampaignProps
The filters to apply on the retrieved campaigns.
configFindConfig<CampaignDTO>
The configurations determining how the campaign is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a campaign.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO[]>Required
The list of campaigns.

listAndCountCampaigns​

This method retrieves a paginated list of campaigns along with the total count of available campaigns satisfying the provided filters.

Example​

To retrieve a list of campaigns using their IDs:

const [campaigns, count] =
  await promotionModuleService.listAndCountCampaigns({
    id: ["procamp_123"],
  })

To specify relations that should be retrieved within the campaigns:

const [campaigns, count] =
  await promotionModuleService.listAndCountCampaigns(
    {
      id: ["procamp_123"],
    },
    {
      relations: ["promotions"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const [campaigns, count] =
  await promotionModuleService.listAndCountCampaigns(
    {
      id: ["procamp_123"],
    },
    {
      relations: ["promotions"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterableCampaignProps
The filters to apply on the retrieved campaigns.
configFindConfig<CampaignDTO>
The configurations determining how the campaign is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a campaign.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[CampaignDTO[], number]>Required
The list of campaigns along with their total count.

retrieveCampaign​

This method retrieves a campaigns by its ID.

Example​

A simple example that retrieves a promotion by its ID:

const campaign =
  await promotionModuleService.retrieveCampaign("procamp_123")

To specify relations that should be retrieved:

const campaign =
  await promotionModuleService.retrieveCampaign(
    "procamp_123",
    {
      relations: ["promotions"],
    }
  )

Parameters​

idstringRequired
The ID of the campaigns.
configFindConfig<CampaignDTO>
The configurations determining how the campaign is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a campaign.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<CampaignDTO>Required
The retrieved campaigns.

deleteCampaigns​

**deleteCampaigns**(ids, sharedContext?): Promise&#60;void&#62;

This method deletes campaigns by their IDs.

Example​

await promotionModuleService.deleteCampaigns(["procamp_123"])

Parameters​

idsstring[]Required
The IDs of the campaigns.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the campaigns are deleted successfully.

**deleteCampaigns**(ids, sharedContext?): Promise&#60;void&#62;

This method deletes a campaign by its ID.

Example​

await promotionModuleService.deleteCampaigns("procamp_123")

Parameters​

idsstringRequired
The IDs of the campaign.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the campaign is deleted successfully.

softDeleteCampaigns​

This method soft deletes campaigns by their IDs.

Example​

await promotionModuleService.softDeleteCampaigns(
  "procamp_123",
  {
    returnLinkableKeys: ["budget_id"],
  }
)

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

campaignIdsstring | string[]Required
The IDs of the campaigns.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated campaign budget. The object's keys are the ID attribute names of the campaign entity's relations, such as budget_id, and its value is an array of strings, each being the ID of a record associated with the campaign through this relation, such as the IDs of associated campaign budget. If there are no related records, the promise resolves to void.

restoreCampaigns​

This method restores soft deleted campaigns by their IDs.

Example​

await promotionModuleService.restoreCampaigns("procamp_123", {
  returnLinkableKeys: ["budget_id"],
})

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

campaignIdsstring | string[]Required
The IDs of the campaigns
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the campaigns. You can pass to its returnLinkableKeys property any of the campaign's relation attribute names, such as budget_id.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored, such as the ID of associated campaign budget. The object's keys are the ID attribute names of the campaign entity's relations, such as budget_id, and its value is an array of strings, each being the ID of the record associated with the campaign through this relation, such as the IDs of associated campaign budget. If there are no related records restored, the promise resolves to void.
Was this section helpful?
© 2025 Medusa, Inc. All rights reserved.