get: operationId: GetPromotions summary: List Promotions description: >- Retrieve a list of promotions. The promotions can be filtered by fields such as `id`. The promotions can also be sorted or paginated. x-authenticated: true parameters: - name: fields in: query description: >- Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. required: false schema: type: string title: fields description: >- Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. externalDocs: url: '#select-fields-and-relations' - name: offset in: query description: The number of items to skip when retrieving a list. required: false schema: type: number title: offset description: The number of items to skip when retrieving a list. externalDocs: url: '#pagination' - name: limit in: query description: Limit the number of items returned in the list. required: false schema: type: number title: limit description: Limit the number of items returned in the list. externalDocs: url: '#pagination' - name: order in: query description: >- The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. required: false schema: type: string title: order description: >- The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. - name: q in: query description: Search term to filter the promotion's searchable attributes. required: false schema: type: string title: q description: Search term to filter the promotion's searchable attributes. - name: code in: query required: false schema: oneOf: - type: string title: code description: Filter by a promotion code. - type: array description: Filter by promotion codes. items: type: string title: code description: A promotion code. - name: campaign_id in: query required: false schema: oneOf: - type: string title: campaign_id description: Filter by a campaign's ID to retrieve its associated promotions. - type: array description: Filter by campaign IDs to retrieve their associated promotions. items: type: string title: campaign_id description: A campaign's ID. - name: application_method in: query description: >- Apply filters on the application methods to retrieve the promotions of the matching application methods. required: false schema: type: object description: >- Apply filters on the application methods to retrieve the promotions of the matching application methods. properties: currency_code: oneOf: - type: string title: currency_code description: Filter by a currency code. - type: array description: Filter by currency codes. items: type: string title: currency_code description: A currency code. - name: created_at in: query description: Filter by a promotion's creation date. required: false schema: type: object description: Filter by a promotion's creation date. properties: $and: type: array description: >- Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters. items: type: object title: $and $or: type: array description: >- Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters. items: type: object title: $or $eq: oneOf: - type: string title: $eq description: Filter by an exact match. - type: array description: Filter by an exact match. items: type: string title: $eq description: Filter by an exact match. $ne: type: string title: $ne description: Filter by values not equal to this parameter. $in: type: array description: Filter by values in this array. items: type: string title: $in description: Filter by values in this array. $nin: type: array description: Filter by values not in this array. items: type: string title: $nin description: Filter by values not in this array. $not: oneOf: - type: string title: $not description: >- Filter by values not matching the conditions in this parameter. - type: object description: >- Filter by values not matching the conditions in this parameter. - type: array description: >- Filter by values not matching the conditions in this parameter. items: type: string title: $not description: >- Filter by values not matching the conditions in this parameter. $gt: type: string title: $gt description: >- Filter by values greater than this parameter. Useful for numbers and dates only. $gte: type: string title: $gte description: >- Filter by values greater than or equal to this parameter. Useful for numbers and dates only. $lt: type: string title: $lt description: >- Filter by values less than this parameter. Useful for numbers and dates only. $lte: type: string title: $lte description: >- Filter by values less than or equal to this parameter. Useful for numbers and dates only. $like: type: string title: $like description: Apply a `like` filter. Useful for strings only. $re: type: string title: $re description: Apply a regex filter. Useful for strings only. $ilike: type: string title: $ilike description: Apply a case-insensitive `like` filter. Useful for strings only. $fulltext: type: string title: $fulltext description: Filter to apply on full-text properties. $overlap: type: array description: Filter arrays that have overlapping values with this parameter. items: type: string title: $overlap description: Filter arrays that have overlapping values with this parameter. $contains: type: array description: Filter arrays that contain some of the values of this parameter. items: type: string title: $contains description: Filter arrays that contain some of the values of this parameter. $contained: type: array description: Filter arrays that contain all values of this parameter. items: type: string title: $contained description: Filter arrays that contain all values of this parameter. $exists: type: boolean title: $exists description: Filter by whether a value for this parameter exists (not `null`). - name: updated_at in: query description: Filter by a promotion's update date. required: false schema: type: object description: Filter by a promotion's update date. properties: $and: type: array description: >- Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters. items: type: object title: $and $or: type: array description: >- Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters. items: type: object title: $or $eq: oneOf: - type: string title: $eq description: Filter by an exact match. - type: array description: Filter by an exact match. items: type: string title: $eq description: Filter by an exact match. $ne: type: string title: $ne description: Filter by values not equal to this parameter. $in: type: array description: Filter by values in this array. items: type: string title: $in description: Filter by values in this array. $nin: type: array description: Filter by values not in this array. items: type: string title: $nin description: Filter by values not in this array. $not: oneOf: - type: string title: $not description: >- Filter by values not matching the conditions in this parameter. - type: object description: >- Filter by values not matching the conditions in this parameter. - type: array description: >- Filter by values not matching the conditions in this parameter. items: type: string title: $not description: >- Filter by values not matching the conditions in this parameter. $gt: type: string title: $gt description: >- Filter by values greater than this parameter. Useful for numbers and dates only. $gte: type: string title: $gte description: >- Filter by values greater than or equal to this parameter. Useful for numbers and dates only. $lt: type: string title: $lt description: >- Filter by values less than this parameter. Useful for numbers and dates only. $lte: type: string title: $lte description: >- Filter by values less than or equal to this parameter. Useful for numbers and dates only. $like: type: string title: $like description: Apply a `like` filter. Useful for strings only. $re: type: string title: $re description: Apply a regex filter. Useful for strings only. $ilike: type: string title: $ilike description: Apply a case-insensitive `like` filter. Useful for strings only. $fulltext: type: string title: $fulltext description: Filter to apply on full-text properties. $overlap: type: array description: Filter arrays that have overlapping values with this parameter. items: type: string title: $overlap description: Filter arrays that have overlapping values with this parameter. $contains: type: array description: Filter arrays that contain some of the values of this parameter. items: type: string title: $contains description: Filter arrays that contain some of the values of this parameter. $contained: type: array description: Filter arrays that contain all values of this parameter. items: type: string title: $contained description: Filter arrays that contain all values of this parameter. $exists: type: boolean title: $exists description: Filter by whether a value for this parameter exists (not `null`). - name: deleted_at in: query description: Filter by a promotion's deletion date. required: false schema: type: object description: Filter by a promotion's deletion date. properties: $and: type: array description: >- Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters. items: type: object title: $and $or: type: array description: >- Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters. items: type: object title: $or $eq: oneOf: - type: string title: $eq description: Filter by an exact match. - type: array description: Filter by an exact match. items: type: string title: $eq description: Filter by an exact match. $ne: type: string title: $ne description: Filter by values not equal to this parameter. $in: type: array description: Filter by values in this array. items: type: string title: $in description: Filter by values in this array. $nin: type: array description: Filter by values not in this array. items: type: string title: $nin description: Filter by values not in this array. $not: oneOf: - type: string title: $not description: >- Filter by values not matching the conditions in this parameter. - type: object description: >- Filter by values not matching the conditions in this parameter. - type: array description: >- Filter by values not matching the conditions in this parameter. items: type: string title: $not description: >- Filter by values not matching the conditions in this parameter. $gt: type: string title: $gt description: >- Filter by values greater than this parameter. Useful for numbers and dates only. $gte: type: string title: $gte description: >- Filter by values greater than or equal to this parameter. Useful for numbers and dates only. $lt: type: string title: $lt description: >- Filter by values less than this parameter. Useful for numbers and dates only. $lte: type: string title: $lte description: >- Filter by values less than or equal to this parameter. Useful for numbers and dates only. $like: type: string title: $like description: Apply a `like` filter. Useful for strings only. $re: type: string title: $re description: Apply a regex filter. Useful for strings only. $ilike: type: string title: $ilike description: Apply a case-insensitive `like` filter. Useful for strings only. $fulltext: type: string title: $fulltext description: Filter to apply on full-text properties. $overlap: type: array description: Filter arrays that have overlapping values with this parameter. items: type: string title: $overlap description: Filter arrays that have overlapping values with this parameter. $contains: type: array description: Filter arrays that contain some of the values of this parameter. items: type: string title: $contains description: Filter arrays that contain some of the values of this parameter. $contained: type: array description: Filter arrays that contain all values of this parameter. items: type: string title: $contained description: Filter arrays that contain all values of this parameter. $exists: type: boolean title: $exists description: Filter by whether a value for this parameter exists (not `null`). - name: $and in: query required: false schema: type: array description: >- Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters. items: type: object title: $and - name: $or in: query required: false schema: type: array description: >- Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters. items: type: object title: $or - name: currency_code in: query required: false schema: oneOf: - type: string title: currency_code description: >- Filter by a currency code. The promotions are filtered based on their application method's currency code. - type: array description: >- Filter by currency codes. The promotions are filtered based on their application method's currency code. items: type: string title: currency_code description: A currency code. - name: application_method_type in: query required: false schema: oneOf: - type: string title: application_method_type description: >- Filter by an application method type. The promotions are filtered based on their application method's type. - type: array description: >- Filter by application method types. The promotions are filtered based on their application method's type. items: type: string title: application_method_type description: An application method type. - name: with_deleted in: query description: Whether to include deleted records in the result. required: false schema: type: boolean title: with_deleted description: Whether to include deleted records in the result. security: - api_token: [] - cookie_auth: [] - jwt_token: [] x-codeSamples: - lang: JavaScript label: JS SDK source: $ref: ../code_samples/JavaScript/admin_promotions/get.js - lang: Shell label: cURL source: $ref: ../code_samples/Shell/admin_promotions/get.sh tags: - Promotions responses: '200': description: OK content: application/json: schema: allOf: - type: object description: The paginated list of promotions. required: - limit - offset - count properties: limit: type: number title: limit description: The maximum number of items returned. offset: type: number title: offset description: >- The number of items skipped before retrieving the returned items. count: type: number title: count description: The total number of items. - type: object description: The paginated list of promotions. required: - promotions properties: promotions: type: array description: The list of promotions. items: $ref: ../components/schemas/AdminPromotion.yaml '400': $ref: ../components/responses/400_error.yaml '401': $ref: ../components/responses/unauthorized.yaml '404': $ref: ../components/responses/not_found_error.yaml '409': $ref: ../components/responses/invalid_state_error.yaml '422': $ref: ../components/responses/invalid_request_error.yaml '500': $ref: ../components/responses/500_error.yaml post: operationId: PostPromotions summary: Create Promotion description: Create a promotion. x-authenticated: true parameters: - name: fields in: query description: >- Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. required: false schema: type: string title: fields description: >- Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. externalDocs: url: '#select-fields-and-relations' security: - api_token: [] - cookie_auth: [] - jwt_token: [] requestBody: content: application/json: schema: allOf: - type: object description: The promotion's details. required: - code - type - campaign_id - application_method properties: code: type: string title: code description: The promotion's code. is_automatic: type: boolean title: is_automatic description: Whether the promotion is applied automatically. type: type: string description: The promotion's type. externalDocs: url: >- https://docs.medusajs.com/v2/resources/commerce-modules/promotion/concepts#what-is-a-promotion enum: - standard - buyget campaign_id: type: string title: campaign_id description: The ID of the campaign that the promotion belongs to. campaign: type: object description: >- The details of a campaign to create and add the promotion to it. required: - name - campaign_identifier - description - budget - starts_at - ends_at properties: name: type: string title: name description: The campaign's name. campaign_identifier: type: string title: campaign_identifier description: The campaign's identifier. description: type: string title: description description: The campaign's description. budget: type: object description: >- The campaign's budget which, when crossed, ends the campaign. required: - type - limit - currency_code properties: type: type: string description: > The budget's type. This can't be edited later. Use `spend` to set a limit on the total amount discounted by the campaign's promotions. Use `usage` to set a limit on the total number of times the campaign's promotions can be used. enum: - spend - usage limit: type: number title: limit description: The budget's limit. currency_code: type: string title: currency_code description: >- The campaign budget's currency code. This can't be edited later. starts_at: type: string title: starts_at description: The campaign's start date. format: date-time ends_at: type: string title: ends_at description: The campaign's end date. format: date-time application_method: type: object description: The promotion's application method. required: - description - value - currency_code - max_quantity - type - target_type - apply_to_quantity - buy_rules_min_quantity properties: description: type: string title: description description: The application method's description. value: type: number title: value description: >- The discounted amount applied by the associated promotion based on the `type`. currency_code: type: string title: currency_code description: The application method's currency code. max_quantity: type: number title: max_quantity description: >- The max quantity allowed in the cart for the associated promotion to be applied. type: type: string description: >- The type of the application method indicating how the associated promotion is applied. enum: - fixed - percentage target_type: type: string description: >- The target type of the application method indicating whether the associated promotion is applied to the cart's items, shipping methods, or the whole order. enum: - order - shipping_methods - items allocation: type: string description: >- The allocation value that indicates whether the associated promotion is applied on each item in a cart or split between the items in the cart. enum: - each - across target_rules: type: array description: The application method's target rules. items: type: object description: A target rule's details. required: - operator - description - attribute - values properties: operator: type: string description: >- The operator used to check whether the target rule applies on a cart. For example, `eq` means that the cart's value for the specified attribute must match the specified value. enum: - gte - lte - gt - lt - eq - ne - in description: type: string title: description description: The target rule's description. attribute: type: string title: attribute description: >- The attribute to compare against when checking whether a promotion can be applied on a cart. example: items.product.id values: oneOf: - type: string title: values description: The attribute's value. example: prod_123 - type: array description: The allowed attribute values. items: type: string title: values description: An attribute value. example: prod_123 buy_rules: type: array description: The application method's buy rules. items: type: object description: A buy rule's details. required: - operator - description - attribute - values properties: operator: type: string description: >- The operator used to check whether the buy rule applies on a cart. For example, `eq` means that the cart's value for the specified attribute must match the specified value. enum: - gte - lte - gt - lt - eq - ne - in description: type: string title: description description: The buy rule's description. attribute: type: string title: attribute description: >- The attribute to compare against when checking whether a promotion can be applied on a cart. example: items.product.id values: oneOf: - type: string title: values description: The attribute's value. example: prod_123 - type: array description: The allowed attribute values. items: type: string title: values description: An attribute value. example: prod_123 apply_to_quantity: type: number title: apply_to_quantity description: >- The quantity that results from matching the `buyget` promotion's condition. For example, if the promotion is a "Buy 2 shirts get 1 free", the value f this attribute is `1`. buy_rules_min_quantity: type: number title: buy_rules_min_quantity description: >- The minimum quantity required for a `buyget` promotion to be applied. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is `2`. rules: type: array description: The promotion's rules. items: type: object description: A rule's details. required: - operator - description - attribute - values properties: operator: type: string description: >- The operator used to check whether the buy rule applies on a cart. For example, `eq` means that the cart's value for the specified attribute must match the specified value. enum: - gte - lte - gt - lt - eq - ne - in description: type: string title: description description: The rule's description. attribute: type: string title: attribute description: >- The attribute to compare against when checking whether a promotion can be applied on a cart. example: items.product.id values: oneOf: - type: string title: values description: The attribute's value. example: prod_123 - type: array description: The allowed attribute values. items: type: string title: values description: An attribute value. example: prod_123 - type: object description: The promotion's details. properties: additional_data: type: object description: >- Pass additional custom data to the API route. This data is passed to the underlying workflow under the `additional_data` parameter. description: The promotion's details. x-codeSamples: - lang: JavaScript label: JS SDK source: $ref: ../code_samples/JavaScript/admin_promotions/post.js - lang: Shell label: cURL source: $ref: ../code_samples/Shell/admin_promotions/post.sh tags: - Promotions responses: '200': description: OK content: application/json: schema: $ref: ../components/schemas/AdminPromotionResponse.yaml '400': $ref: ../components/responses/400_error.yaml '401': $ref: ../components/responses/unauthorized.yaml '404': $ref: ../components/responses/not_found_error.yaml '409': $ref: ../components/responses/invalid_state_error.yaml '422': $ref: ../components/responses/invalid_request_error.yaml '500': $ref: ../components/responses/500_error.yaml x-workflow: createPromotionsWorkflow x-events: []