www/apps/resources/references/promotion/IPromotionModuleService/methods/promotion.IPromotionModuleService.retrievePromotion/page.mdx
import { TypeList } from "docs-ui"
This documentation provides a reference to the retrievePromotion method. This belongs to the Promotion Module.
You should only use this methods when implementing complex customizations. For common cases, check out available workflows instead.
</Note>This method retrieves a promotion by its ID.
A simple example that retrieves a promotion by its ID:
const promotion =
await promotionModuleService.retrievePromotion("promo_123")
To specify relations that should be retrieved:
:::note
You can only retrieve data models defined in the same module. To retrieve linked data models from other modules, use Query instead.
:::
const promotion = await promotionModuleService.retrievePromotion(
"promo_123",
{
relations: ["application_method"],
}
)
<TypeList types={[{"name":"id","type":"string","description":"The ID of the promotion.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"config","type":"FindConfig<PromotionDTO>","description":"The configurations determining how the promotion is retrieved. Its properties, such as select or relations, accept the\nattributes or relations associated with a promotion.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"select","type":"(keyof Entity \| string & object)[]","description":"An array of strings, each being attribute names of the entity to retrieve in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"skip","type":"null \| number","description":"A number indicating the number of records to skip before retrieving the results.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"take","type":"null \| number","description":"A number indicating the number of records to return in the result.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"relations","type":"string[]","description":"An array of strings, each being relation names of the entity to retrieve in the result.\n\nYou can only retrieve data models defined in the same module. To retrieve linked data models\nfrom other modules, use Query instead.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"order","type":"FindConfigOrder","description":"An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be ASC\nto sort retrieved records in an ascending order, or DESC to sort retrieved records in a descending order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"withDeleted","type":"boolean","description":"A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the\nSoftDeletableEntity class.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"filters","type":"Record<string, any>","description":"Enable ORM specific defined filters","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"Record<string, any>","description":"Enable ORM specific defined options","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"sharedContext","type":"Context","description":"A context used to share resources, such as transaction manager, between the application and the module.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"transactionManager","type":"TManager","description":"An instance of a transaction manager of type TManager, which is a typed parameter passed to the context to specify the type of the transactionManager.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"manager","type":"TManager","description":"An instance of a manager, typically an entity manager, of type TManager, which is a typed parameter passed to the context to specify the type of the manager.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isolationLevel","type":"string","description":"A string indicating the isolation level of the context. Possible values are READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, or SERIALIZABLE.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"enableNestedTransactions","type":"boolean","description":"A boolean value indicating whether nested transactions are enabled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"eventGroupId","type":"string","description":"A string indicating the ID of the group to aggregate the events to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"transactionId","type":"string","description":"A string indicating the ID of the current transaction.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"runId","type":"string","description":"A string indicating the ID of the current run.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"messageAggregator","type":"IMessageAggregator","description":"An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"requestId","type":"string","description":"A string indicating the ID of the current request.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"idempotencyKey","type":"string","description":"A string indicating the idempotencyKey of the current workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"parentStepIdempotencyKey","type":"string","description":"A string indicating the idempotencyKey of the parent workflow execution.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"preventReleaseEvents","type":"boolean","description":"preventReleaseEvents","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"isCancelling","type":"boolean","description":"A boolean value indicating whether the current workflow execution is being cancelled.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"cancelingFromParentStep","type":"boolean","description":"Weither or not a sub workflow cancellation is being triggered from a parent step.\nIf true, the parent step will not be triggered by the sub workflow.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePromotion"/>
<TypeList types={[{"name":"Promise","type":"Promise<PromotionDTO>","optional":false,"defaultValue":"","description":"The retrieved promotion.","expandable":false,"children":[{"name":"id","type":"string","description":"The ID of the promotion.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"string","description":"The code of the promotion.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"PromotionTypeValues","description":"The type of the promotion:\n\n- standard indicates that a promotion is a standard one applied with conditions.\n- buyget indicates that a promotion is a "Buy X get Y" promotion.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"status","type":"PromotionStatusValues","description":"The status of the promotion:\n\n- active promotion is available for user to consume\n- inactive promotion is no longer available to the user\n- draft promotion is currently being prepared","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"is_automatic","type":"boolean","description":"Whether the promotion is applied automatically.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"is_tax_inclusive","type":"boolean","description":"Whether the promotion is tax inclusive.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"limit","type":"null \| number","description":"The maximum number of times this promotion can be used across all orders.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"used","type":"number","description":"The number of times this promotion has been used in completed orders.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"application_method","type":"ApplicationMethodDTO","description":"The associated application method.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"string","description":"The ID of the application method.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"type","type":"ApplicationMethodTypeValues","description":"The type of the application method indicating how\nthe associated promotion is applied.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"target_type","type":"ApplicationMethodTargetTypeValues","description":"The target type of the application method indicating\nwhether the associated promotion is applied to the cart's items,\nshipping methods, or the whole order.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"allocation","type":"ApplicationMethodAllocationValues","description":"The allocation value that indicates whether the associated promotion\nis applied on each item in a cart or split between the items in the cart.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"value","type":"number","description":"The discounted amount applied by the associated promotion based on the type.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"string","description":"The currency code of the application method","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"max_quantity","type":"null \| number","description":"The max quantity allowed in the cart for the associated promotion to be applied.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"buy_rules_min_quantity","type":"null \| number","description":"The minimum quantity required for a buyget promotion to be applied.\nFor example, if the promotion is a "Buy 2 shirts get 1 free", the\nvalue of this attribute is 2.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"apply_to_quantity","type":"null \| number","description":"The quantity that results from matching the buyget promotion's condition.\nFor example, if the promotion is a "Buy 2 shirts get 1 free", the value\nof this attribute is 1.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"promotion","type":"string \| PromotionDTO","description":"The promotion of the application method.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"target_rules","type":"PromotionRuleDTO[]","description":"The target rules of the application method.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"buy_rules","type":"PromotionRuleDTO[]","description":"The buy rules of the application method.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"rules","type":"PromotionRuleDTO[]","description":"The rules of the promotion.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"string","description":"The ID of the promotion rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"values","type":"PromotionRuleValueDTO[]","description":"The values of the promotion rule.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"description","type":"null \| string","description":"The description of the promotion rule.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"attribute","type":"string","description":"The attribute of the promotion rule.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"operator","type":"PromotionRuleOperatorValues","description":"The operator of the promotion rule.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"campaign_id","type":"null \| string","description":"The associated campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"campaign","type":"CampaignDTO","description":"The associated campaign.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"id","type":"string","description":"The ID of the campaign.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"name","type":"string","description":"The name of the campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"description","type":"string","description":"The description of the campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"campaign_identifier","type":"string","description":"The campaign identifier of the campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"starts_at","type":"Date","description":"The start date of the campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"ends_at","type":"Date","description":"The end date of the campaign.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"budget","type":"CampaignBudgetDTO","description":"The associated campaign budget.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"promotions","type":"PromotionDTO[]","description":"The associated promotions.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="retrievePromotion"/>