From 2940b0fee2754c86f3ecbd8f79d6035de82e1038 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 19 Feb 2025 12:12:03 +0200 Subject: [PATCH] docs: update promotions user guide (#11524) * update promotion pages * finish update * fix build error --- www/apps/user-guide/app/customers/page.mdx | 2 +- .../user-guide/app/discounts/create/page.mdx | 44 --- .../user-guide/app/discounts/manage/page.mdx | 101 ------ www/apps/user-guide/app/discounts/page.mdx | 36 --- .../app/promotions/campaigns/page.mdx | 174 ++++++++++ .../user-guide/app/promotions/create/page.mdx | 303 ++++++++++++++++++ .../user-guide/app/promotions/manage/page.mdx | 230 +++++++++++++ www/apps/user-guide/app/promotions/page.mdx | 33 ++ www/apps/user-guide/generated/edit-dates.mjs | 6 +- www/apps/user-guide/generated/sidebar.mjs | 30 +- www/apps/user-guide/sidebar.mjs | 26 +- 11 files changed, 790 insertions(+), 195 deletions(-) delete mode 100644 www/apps/user-guide/app/discounts/create/page.mdx delete mode 100644 www/apps/user-guide/app/discounts/manage/page.mdx delete mode 100644 www/apps/user-guide/app/discounts/page.mdx create mode 100644 www/apps/user-guide/app/promotions/campaigns/page.mdx create mode 100644 www/apps/user-guide/app/promotions/create/page.mdx create mode 100644 www/apps/user-guide/app/promotions/manage/page.mdx create mode 100644 www/apps/user-guide/app/promotions/page.mdx diff --git a/www/apps/user-guide/app/customers/page.mdx b/www/apps/user-guide/app/customers/page.mdx index 9f590af5dc..3a733495cf 100644 --- a/www/apps/user-guide/app/customers/page.mdx +++ b/www/apps/user-guide/app/customers/page.mdx @@ -10,7 +10,7 @@ export const metadata = { The Customers domain allows you to manage customers and customer groups in your commerce store. -You can manage both customers that have registered in your store and guest customers that have placed an order. You can also segment these customers into groups to offer them specific [promotions](../discounts/page.mdx) and [pricing](../pricing/page.mdx). +You can manage both customers that have registered in your store and guest customers that have placed an order. You can also segment these customers into groups to offer them specific [promotions](../promotions/page.mdx) and [pricing](../pricing/page.mdx). You can view the list of customers in your commerce store by clicking on Customers from the sidebar menu. diff --git a/www/apps/user-guide/app/discounts/create/page.mdx b/www/apps/user-guide/app/discounts/create/page.mdx deleted file mode 100644 index 8640f1174d..0000000000 --- a/www/apps/user-guide/app/discounts/create/page.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -sidebar_position: 1 ---- - -export const metadata = { - title: `Create a Discount`, -} - -# {metadata.title} - -In this document, you’ll learn how to create a discount. - -## How to Create a Discount - -{/* TODO check info for correctness */} - -To create a discount: - -1. Go to Discounts. -2. Click the Create button. -3. In the form that opens: - 1. Choose the one of the following discount types: - - **Percentage:** discount a specific percentage. - - **Fixed amount:** discount a specific amount. - - **Free shipping:** Remove any shipping amount available during checkout. - 2. In the "Choose valid regions" field, choose the region(s) that the discount can be used in. If you chose the "Fixed amount" type, you can only choose one region. - 3. Enter the discount code in the Code field. - 4. If you chose the Percentage type, enter the percentage amount to discount in the Percentage field. - 5. If you chose the "Fixed amount" type, enter the amount to discount in the Amount field. - 6. You can optionally enter a description for the discount. - 7. To use this discount as a parent discount to other discounts, check the "Is this a template discount?" checkbox. This is useful when you want to re-use rules and conditions across multiple discounts. - 8. To add a start date for the discount, toggle the "Discount has a start date" field and enter the start date in the field shown. If you keep this field disabled, the discount starts immediately after creating the discount. - 9. To add an expiry date for the discount, toggle the "Discount has an expiry date" field and enter the end date in the field shown. If you keep this field disabled, the discount doesn't have an expiry date. - 10. To limit the number of times a discount can be used by all customers, toggle the "Limit the number of redemptions?" field and enter the limit in the field shown. If you keep this field disabled, the discount can be used unlimited times. - 11. To set the duration that the discount runs for, toggle the "Availability duration" field and enter the duration in years, months, days, hours, and minutes. - 12. Under the Conditions section, you can add discount's conditions that limits which products, customer groups, or shipping methods that the discount can be used with. - - To add a condition, click the "Add condition" button. - - A condition is segmented to editable fields: - - The first field specifies the criteria of the conditon. For example, "products" to apply the condition on the products. - - The second field specifies the limit of the condition. For example, "all" to apply the condition on all products. - - The third field can be used to specify additions or exceptions to the condition. For example, "except" to add a condition that applies the discount to all products except. - - The fourth field specifies the value of the third field's condition. For example, "Shirt" to add a condition that applies the discount to all products except the product "Shirt". - 13. Under the Metadata section, optionally add additional information as key-value pairs. -4. Once you're done, click the Save button. diff --git a/www/apps/user-guide/app/discounts/manage/page.mdx b/www/apps/user-guide/app/discounts/manage/page.mdx deleted file mode 100644 index 2086999c69..0000000000 --- a/www/apps/user-guide/app/discounts/manage/page.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -sidebar_position: 2 ---- - -import { EllipsisHorizontal } from "@medusajs/icons" - -export const metadata = { - title: `Manage Discounts`, -} - -# {metadata.title} - -In this document, you’ll learn how to manage discounts including editing and deleting a discount. - -## View Discount Details - -To view a discount’s details: - -1. Go to Discounts. -2. Click on the discount you want to view its details - -This opens the discount’s details page. - ---- - -## Edit a Discount - -### Change Discount Status - -{/* TODO check for correctness */} - - - -Changing a discount’s status to published makes it available for customers to use. Changing a discount’s status to draft makes it unavailable for customers to use. - - - -To change a discount’s status: - -1. Go to the discount details page. -2. At the top right of the first section, you’ll see the status of the discount (for example, Active). Click on it. -3. Choose from the dropdown the opposite status (for example, Inactive) - -### Edit General Information - -To edit a discount’s general information: - -1. Go to the discount details page. -2. Click on the icon at the top right of the first section. -3. Choose Edit from the dropdown. -4. In the drawer that opens, edit any of the discount information. -5. Once done, click the Save button. - ---- - -## Edit Discount Configurations - -To edit a discount’s configuration: - -1. Go to the discount details page. -2. Under the Configurations section, click on the icon at the top right. -3. Choose Edit from the dropdown. -4. In the drawer that opens, edit any of the configurations. -5. Once done, click the Save button. - ---- - -## Manage Discount Conditions - -{/* TODO check for correctness */} - -To manage a discount's conditions: - -1. Go to the discount details page. -2. Under the Conditions section, click on the icon at the top right. -3. Choose Edit from the dropdown. -4. In the drawer that opens, you can remove or edit an existing discount, or add a new one. Similar to when you created the discount: - - To add a condition, click the "Add condition" button. - - A condition is segmented to editable fields: - - The first field specifies the criteria of the conditon. For example, "products" to apply the condition on the products. - - The second field specifies the limit of the condition. For example, "all" to apply the condition on all products. - - The third field can be used to specify additions or exceptions to the condition. For example, "except" to add a condition that applies the discount to all products except. - - The fourth field specifies the value of the third field's condition. For example, "Shirt" to add a condition that applies the discount to all products except the product "Shirt". -5. Once you're done, click the Save button. - ---- - -## Delete a Discount - - - -Deleting a discount is irreversible. - - - -To delete a discount: - -1. Go to the discount details page. -2. Click on the icon at the top right of the first section. -3. Choose Delete from the dropdown. -4. Confirm deleting the discount by entering its code and clicking the Delete button in the pop-up. diff --git a/www/apps/user-guide/app/discounts/page.mdx b/www/apps/user-guide/app/discounts/page.mdx deleted file mode 100644 index 54b9c5ddfd..0000000000 --- a/www/apps/user-guide/app/discounts/page.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_autogenerate_exclude: true ---- - -export const metadata = { - title: `Discounts`, -} - -# {metadata.title} - -In this document, you’ll get an overview of types of discounts and the Discounts page. - -## Overview - -You can create discounts of different types in Medusa that customers use on checkout: - -- **Percentage Discounts** to deduct a percentage of the total amount of an order. -- **Fixed Discounts** to deduct a fixed amount from the total amount of an order. -- **Free Shipping** to override the delivery amount of an order and make it free. - -Discounts are in the form of a code that your customers use. Discounts have conditions and options, such as start and end dates, or what products is the discount applied to. - ---- - -## View List of Discounts - -You can view the list of available discounts in your ecommerce store by clicking on Discounts from the sidebar menu. - -The list shows discount details such as the code, description, value, and status. - ---- - -## Learn More About Discounts - -- [Create a Discount](./create/page.mdx) -- [Manage Discounts](./manage/page.mdx) diff --git a/www/apps/user-guide/app/promotions/campaigns/page.mdx b/www/apps/user-guide/app/promotions/campaigns/page.mdx new file mode 100644 index 0000000000..81f4165a5f --- /dev/null +++ b/www/apps/user-guide/app/promotions/campaigns/page.mdx @@ -0,0 +1,174 @@ +import { EllipsisHorizontal } from "@medusajs/icons" +import { Table } from "docs-ui" + +export const metadata = { + title: `Manage Campaigns`, +} + +# {metadata.title} + +In this guide, you'll learn how to view and manage campaigns. + +## What is a Campaign? + +A campaign is a collection of promotions related to specific marketing or sales goals. A campaign also gives you granular control over promotion usages, allowing you to set up start and end dates, and budget usages that once exceeded, the promotions of the campaign can't be used anymore. + +--- + +## View Campaigns + +To view the campaigns in your store, go to Promotions -> Campaigns from the sidebar. + +In the list, you can see campaign details such as the name, description, and identifier. You can also search, filter, and sort the campaigns to find the specific item you are looking for. + + + +Find tips to use lists effectively in [this guide](../../tips/lists/page.mdx). + + + +![Campaigns list](https://res.cloudinary.com/dza7lstvk/image/upload/v1739953082/User%20Guide/Screenshot_2025-02-19_at_10.17.49_AM_wsuorp.png) + +--- + +## Create Campaign + +To create a campaign: + +1. Go to Promotions -> Campaigns from the sidebar. +2. Click on the Create button at the top right. +3. In the form that opens: + - Enter the campaign's name and identifier in their respective fields. + - Optionally add a description in the Description field. + - Optionally set a start date in the "Start date" field. Promotions in this campaign can only be used after this date. + - Optionally set an end date in the "End date" field. Promotions in this campaign are expired after this date. + - You can set a campaign budget of the following types: + - **Usage**: How many times the promotions in the campaign can be used. Once the number of times exceed the limit, the campaign and its promotions expire. + - **Spend**: The total amount that can be discounted by the promotions in the campaign. Once the total amount discounted exceeds the limit, the campaign and its promotions expire. This is not applicable to "Buy X Get Y" promotions. + - If you chose the **Spend** type, select the currency of the limit in the "Currency" field. + - When adding promotions to the campaign later, promotions that discount a fixed amount can only be added if the currency matches the campaign budget's currency. + - In the Limit field, you can set a campaign budget limit based on the type you chose. + - If you chose **Usage**, enter the number of times the promotions in the campaign can be used. + - If you chose **Spend**, enter the total amount that can be discounted by the promotions in the campaign. +4. Once you're done, click the Create button. + +![Create Campaign Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739953632/User%20Guide/Screenshot_2025-02-19_at_10.27.00_AM_u4w38d.png) + +--- + +## View Campaign Details + +To view the details of a campaign: + +1. Go to Promotions -> Campaigns from the sidebar. +2. Click on the campaign you want to view. + +This opens the campaign's details page. + +![Campaign Details](https://res.cloudinary.com/dza7lstvk/image/upload/v1739953751/User%20Guide/Screenshot_2025-02-19_at_10.28.59_AM_lvi2vl.png) + +### Campaign Statuses + +At the top right of the first section, you can see the campaign's status. The status can be one of the following: + + + + + Status + Description + + + + + Scheduled + The campaign has a start date in the future. Once the start date is reached, the campaign becomes active. + + + Active + The campaign is active and its promotions can be used. + + + Expired + The campaign has an end date that has passed. The campaign and its promotions are expired and can't be used anymore. + + +
+ +--- + +## Edit Campaign Details + +To edit the details of a campaign: + +1. Go to the campaign's details page. +2. Click the icon at the top right of the first section. +3. Choose Edit from the dropdown. +4. In the side window that opens, you can edit the campaign's name, description, identifier, and start and end dates. +5. Once you're done, click the Save button. + +![Edit Campaign Details](https://res.cloudinary.com/dza7lstvk/image/upload/v1739954855/User%20Guide/Screenshot_2025-02-19_at_10.47.24_AM_c81zgf.png) + +--- + +## Edit Campaign Budget Limit + +To edit a campaign's budget usage or spending limit: + +1. Go to the campaign's details page. +2. Click the icon at the top right of the "Budget Limit" section. +3. Choose Edit from the dropdown. +4. In the side window that opens, you can edit the budget limit. +5. Once you're done, click the Save button. + +![Edit Campaign Budget Limit](https://res.cloudinary.com/dza7lstvk/image/upload/v1739955041/User%20Guide/Screenshot_2025-02-19_at_10.50.32_AM_wsvwko.png) + +--- + +## Manage Promotions of Campaign + +From the campaign's details page, you can manage which promotions belong to the campaign. + +### Add Promotions to Campaign + +To add promotions to a campaign: + + + +You can only add promotions that don't belong to another campaign. + + + +1. Go to the campaign's details page. +2. Click on the Add button at the top right of the "Promotions" section. +3. In the list that opens, check the promotions you want to add to the campaign. +4. Once you're done, click the Save button. + +![Add Promotions to Campaign](https://res.cloudinary.com/dza7lstvk/image/upload/v1739954374/User%20Guide/Screenshot_2025-02-19_at_10.39.17_AM_gvzsjj.png) + +### Remove Promotions from Campaign + +To remove promotions from a campaign: + +1. Go to the campaign's details page. +2. In the "Promotions" section, check the promotions you want to remove from the campaign. +3. Once you're done, either press R or click the Remove button at the bottom center of the page. +4. Confirm removing the promotion from the campaign by clicking the "Continue" button in the pop-up. + +![Remove Promotions from Campaign](https://res.cloudinary.com/dza7lstvk/image/upload/v1739954706/User%20Guide/Screenshot_2025-02-19_at_10.42.49_AM_zk8mcr.png) + +--- + +## Delete Campaign + + + +Deleting a campaign is irreversible. Deleting a campaign doesn't delete its promotions. + + + +To delete a campaign: + +1. Go to the campaign's details page. +2. Click the icon at the top right of the first section. +3. Choose Delete from the dropdown. +4. Confirm deleting the campaign by clicking the "Delete" button in the pop-up. diff --git a/www/apps/user-guide/app/promotions/create/page.mdx b/www/apps/user-guide/app/promotions/create/page.mdx new file mode 100644 index 0000000000..2aa6642226 --- /dev/null +++ b/www/apps/user-guide/app/promotions/create/page.mdx @@ -0,0 +1,303 @@ +--- +sidebar_position: 1 +--- + +export const metadata = { + title: `Create a Promotion`, +} + +# {metadata.title} + +In this guide, you’ll learn how to create a promotion of different types and configurations. + +To create a promotion: + +1. Go to Promotions. +2. Click on the Create button. + +This will open the form to create a promotion, which is made up of three steps: Type, Details, and Campaign. + +## Step 1: Type + +In the first step of creating a promotion, you need to specify the type of the promotion, which can be one of the following: + +1. **Amount off products**: Discount a fixed amount of products matching custom and dynamic conditions. +2. **Amount off order**: Discount a fixed amount from the total order amount. +3. **Percentage off product**: Discount a percentage off the amount of products matching custom and dynamic conditions. +4. **Percentage off order**: Discount a percentage off an order's total. +5. **Buy X Get Y**: When the customer buys X quantity of a product, they get Y quantity for free. For example, buy 3 shirts get 1 for free. + +Once you've selected the type, click on the Continue button. + +![Create Promotion Form First Step](https://res.cloudinary.com/dza7lstvk/image/upload/v1739894084/User%20Guide/Screenshot_2025-02-18_at_5.54.25_PM_irp2ax.png) + +--- + +## Step 2: Details + +The fields in the details section will slightly differ based on the type you chose. So, the next sections cover the instructions for each type. Follow the section of the type you chose. + +### a. Amount off Products + +If you chose the "Amount off Products" promotion type in the first section, fill out the following in the Details step: + +1. For the Method, choose how you want the promotion to be applied: + - **Promotion code**: The customer must enter the promotion's code during checkout for the promotion to apply. + - **Automatic**: The promotion is applied automatically if the customer's cart matches the promotion's conditions. +2. For the Status, choose **Draft** if you don't want to allow customers to use the promotion yet, or **Active** otherwise. +3. In the Code field, enter the promotion's code. It must be a code that doesn't have spaces. For example, `50OFF`. +4. In the "Who can use this code?" section, you'll specify the conditions that must be met for the promotion to be applicable for a customer's cart. + - You must set the currency code that this promotion applies to, which is shown as a required field. + - To add a custom condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must be / must not be placing the order from the specified sales channels. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the VIP group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the VIP customer group. + +![Who can use this section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898104/User%20Guide/Screenshot_2025-02-18_at_7.01.14_PM_wvskll.png) + +5. In the Promotion Value field, set the amount to be discounted from applicable products when the promotion is applied. The amount is in the currency you chose in the previous section. +6. In the Maximum Quantity field, set the maximum quantity of the applicable that the promotion is applied to in the cart. For example, if set to `1` and the customer has two applicable items in the cart, the promotion is only applied to one of them. +7. In the "What items will the promotion be applied to?" section, you'll specify the items in the cart that the promotion can be applied to. To add a condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product**: The promotion applies / doesn't apply to the specified product(s). + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to apply the promotion on products in the "Shirts" category: + - Set the Attribute to Product Category. + - Set the Operator to In or Equals. + - Set the Value to the Shirts product category. +8. Once you're done, click Next and move on to the [next step](#step-3-campaign). + +![What items will the promotion be applied to section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898160/User%20Guide/Screenshot_2025-02-18_at_7.02.26_PM_izi1sv.png) + +### b. Amount off Order + +If you chose the "Amount off Order" promotion type in the first section, fill out the following in the Details step: + +1. For the Method, choose how you want the promotion to be applied: + - **Promotion code**: The customer must enter the promotion's code during checkout for the promotion to apply. + - **Automatic**: The promotion is applied automatically if the customer's cart matches the promotion's conditions. +2. For the Status, choose Draft if you don't want to allow customers to use the promotion yet, or Active otherwise. +3. In the Code field, enter the promotion's code. It must be a code that doesn't have spaces. For example, `50OFF`. +4. In the "Who can use this code?" section, you'll specify the conditions that must be met for the promotion to be applicable for a customer's cart. + - You must set the currency code that this promotion applies to, which is shown as a required field. + - To add a custom condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must be / must not be placing the order from the specified sales channels. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the VIP group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the VIP customer group. + +![Who can use this code form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898239/User%20Guide/Screenshot_2025-02-18_at_7.03.46_PM_iawubi.png) + +5. In the Promotion Value field, set the amount to be discounted from the order when the promotion is applied. The amount is in the currency you chose in the previous section. +6. Once you're done, click Next and move on to the [next step](#step-3-campaign). + +### c. Percentage off Product + +If you chose the "Percentage off Product" promotion type in the first section, fill out the following in the Details step: + +1. For the Method, choose how you want the promotion to be applied: + - **Promotion code**: The customer must enter the promotion's code during checkout for the promotion to apply. + - **Automatic**: The promotion is applied automatically if the customer's cart matches the promotion's conditions. +2. For the Status, choose Draft if you don't want to allow customers to use the promotion yet, or Active otherwise. +3. In the Code field, enter the promotion's code. It must be a code that doesn't have spaces. For example, `50OFF`. +4. In the "Who can use this code?" section, you'll specify the conditions that must be met for the promotion to be applicable for a customer's cart. To add a condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must / must not be placing the order from the specified sales channels. + - **Currency Code**: The currency code that the customer must / must not be placing the order in. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the VIP group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the VIP customer group. + +![Who can use this code section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898340/User%20Guide/Screenshot_2025-02-18_at_7.05.27_PM_yircnf.png) + +5. In the Promotion Value field, set the amount to be discounted from applicable products when the promotion is applied. The amount is in the currency you chose in the previous section. +6. In the Maximum Quantity field, set the maximum quantity of the applicable that the promotion is applied to in the cart. For example, if set to `1` and the customer has two applicable items in the cart, the promotion is only applied to one of them. +7. In the "What items will the promotion be applied to?" section, you'll specify the items in the cart that the promotion can be applied to. To add a condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product**: The promotion applies / doesn't apply to the specified product(s). + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to apply the promotion on products in the "Shirts" category: + - Set the Attribute to Product Category. + - Set the Operator to In or Equals. + - Set the Value to the Shirts product category. +8. Once you're done, click Next and move on to the [next step](#step-3-campaign). + +![What items will the promotion be applied to section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898386/User%20Guide/Screenshot_2025-02-18_at_7.06.14_PM_bdi5jv.png) + +### d. Percentage off Order + +If you chose the "Percentage off Order" promotion type in the first section, fill out the following in the Details step: + +1. For the Method, choose how you want the promotion to be applied: + - **Promotion code**: The customer must enter the promotion's code during checkout for the promotion to apply. + - **Automatic**: The promotion is applied automatically if the customer's cart matches the promotion's conditions. +2. For the Status, choose Draft if you don't want to allow customers to use the promotion yet, or Active otherwise. +3. In the Code field, enter the promotion's code. It must be a code that doesn't have spaces. For example, `50OFF`. +4. In the "Who can use this code?" section, you'll specify the conditions that must be met for the promotion to be applicable for a customer's cart. To add a condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must / must not be placing the order from the specified sales channels. + - **Currency Code**: The currency code that the customer must / must not be placing the order in. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the VIP group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the VIP customer group. + +![Who can use this code section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898478/User%20Guide/Screenshot_2025-02-18_at_7.07.46_PM_eriyxm.png) + +5. In the Promotion Value field, set the amount to be discounted from applicable products when the promotion is applied. The amount is in the currency you chose in the previous section. +6. Once you're done, click Next and move on to the [next step](#step-3-campaign). + +### e. Buy X Get Y + +If you chose the "Buy X Get Y" promotion type in the first section, fill out the following in the Details step: + +1. For the Method, choose how you want the promotion to be applied: + - **Promotion code**: The customer must enter the promotion's code during checkout for the promotion to apply. + - **Automatic**: The promotion is applied automatically if the customer's cart matches the promotion's conditions. +2. For the Status, choose Draft if you don't want to allow customers to use the promotion yet, or Active otherwise. +3. In the Code field, enter the promotion's code. It must be a code that doesn't have spaces. For example, `50OFF`. +4. In the "Who can use this code?" section, you'll specify the conditions that must be met for the promotion to be applicable for a customer's cart. To add a condition, click on the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must / must not be placing the order from the specified sales channels. + - **Currency Code**: The currency code that the customer must / must not be placing the order in. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the VIP group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the VIP customer group. + +![Who can use this code section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898542/User%20Guide/Screenshot_2025-02-18_at_7.08.45_PM_nh5iw4.png) + +5. In the "What needs to be in the cart to unlock the promotion?" section, you'll specify the "Buy X" part (for example, "Buy 3 shirts"): + - You must set the minimum required quantity of the items in the cart. For example, for the "Buy 3 shirts get 1 for free", you set the minimum quantity to three. + - You must set the product(s) that this promotion applies / doesn't apply to. + - To add a custom condition, click on the "Add condition" button. For each custom condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you don't want the promotion to apply to products in the "Shirt" category: + - Set the Attribute to Product Category. + - Set the Operator to "Not In". + - Set the Value to the "Shirt" category. + +![What needs to be in cart to unlock promotion section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898589/User%20Guide/Screenshot_2025-02-18_at_7.09.31_PM_xzj8ro.png) + +6. In the "What items will the promotion be applied to?" section, you'll specify the Buy Y part (for example, "get 1 free shirt"): + - You must set the quantity of items that the customer gets out of the promotion. For example, for the "Buy 3 shirts get 1 for free", you set the quantity to one. + - You must set the products tht the customer gets out of the promotion for free. + - To add a custom condition, click on the "Add condition" button. For each custom condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you don't want the promotion to offer products in the "Shirt" category: + - Set the Attribute to Product Category. + - Set the Operator to "Not In". + - Set the Value to the "Shirt" category. +7. Once you're done, click Next and move on to the [next step](#step-3-campaign). + +![What items will the promotion be applied to section](https://res.cloudinary.com/dza7lstvk/image/upload/v1739898642/User%20Guide/Screenshot_2025-02-18_at_7.10.28_PM_rl3dkp.png) + +--- + +## Step 3: Campaign + +The promotion can be associated with a campaign, giving you granular control over its budget, and when it starts and ends. + +In the campaigns section, you can select whether to: + +- Continue **Without Campaign**. If selected, you can proceed and create the promotion. +- Continue with an **Existing Campaign**. If selected, you'll need to select the campaign that the promotion will belong to. +- Continue with a **New Campaign**. If selected, you'll see fields to create a new campaign. + +### Create Campaign + +If you selected a new campaign, you need to fill out the following to create a campaign and add the promotion to it: + +1. In the Name field, enter the campaign's name. +2. In the Identifier field, enter a custom identifier for the campaign. This is useful if you're associating the campaign with a campaign in an external system, for example. +3. Optionally enter a description, and start and end dates. + - If a start date is specified, all promotions in the campaign can be used after the specified date. + - If an end date is specified, all promotions in the campaign can't be used after the specified date. +4. Under the campaign budget, you can add limits that automatically expires the campaign, which means promotions in that campaign can't be used anymore. + - For Type, you can choose to set the budget either based on: + - **Usage**: How many times the promotions in the campaign can be used. Once the number of times exceed the limit, the campaign and its promotions expire. + - **Spend**: The total amount that can be discounted by the promotions in the campaign. Once the total amount discounted exceeds the limit, the campaign and its promotions expire. This is disabled if you select the "Buy X Get Y" promotion type. + - In the Limit field, enter the budget limit based on the chosen type. +5. Once you're done, click on the Save button. + +![Create campaign form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739897668/User%20Guide/Screenshot_2025-02-18_at_6.53.46_PM_gfhp9l.png) diff --git a/www/apps/user-guide/app/promotions/manage/page.mdx b/www/apps/user-guide/app/promotions/manage/page.mdx new file mode 100644 index 0000000000..1f313b061d --- /dev/null +++ b/www/apps/user-guide/app/promotions/manage/page.mdx @@ -0,0 +1,230 @@ +--- +sidebar_position: 2 +--- + +import { EllipsisHorizontal } from "@medusajs/icons" +import { Table } from "docs-ui" + +export const metadata = { + title: `Manage Promotions`, +} + +# {metadata.title} + +In this guide, you’ll learn how to manage promotions. + +## View Promotion's Details + +To view a promotion's details: + +1. Go to Promotions from the sidebar. +2. Choose the promotion from the list. + +This opens the promotion's details page. The sections in the details page may differ based on the promotion's type. + +![Promotion Details](https://res.cloudinary.com/dza7lstvk/image/upload/v1739951000/User%20Guide/Screenshot_2025-02-19_at_9.42.23_AM_fjpgv7.png) + +### Promotion Statuses + +A promotion's status is shown in the Promotions listing page, and in the promotion's details page at the top right of the first section. The status can be one of the following: + + + + + Status + Description + + + + + Draft + The promotion is not active and can't be used. + + + Active + The promotion is active and can be used. + + + Inactive + The promotion was active but has been deactivated manually. It can't be used. + + + Scheduled + The promotion's campaign has a start date in the future. Once the start date is reached, the promotion becomes active. + + + Expired + The promotion's campaign has an end date that has passed. The promotion can't be used. + + +
+ +--- + +## Edit Promotion's Details + +To edit a promotion's general details: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the first section. +3. Choose Edit from the dropdown. +4. In the side window that opens: + - You can change the promotion's status to either **Draft**, **Active**, or **Inactive**. Inactive is useful if the promotion was originally active but you want to expire it. + - You can edit the promotion's method (whether it's applied manually or automatically) and code. + - You can change how the amount is discounted, either by a fixed amount or a percentage. You can also change the discounted amount. + - You can change how the promotion is applied, either on every applicable item or across all items in the cart. + - For example, if your promotion discounts an amount from applicable products in a cart, choosing **Each** applies the discount on each applicable product, whereas **Across** applies the discount across all applicable products. +5. Once you're done, click the Save button. + +![Edit Promotion Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739951499/User%20Guide/Screenshot_2025-02-19_at_9.51.26_AM_zylmig.png) + +--- + +## Edit Who Can Use the Promotion + +To edit who can use the promotion: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the "Who can use this code?" section. +3. Choose Edit from the dropdown. +4. In the side window that opens, you can edit existing conditions or add new ones by clicking the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Customer Group**: The customer must belong / not belong to the specified customer group(s). + - **Region**: The customer's region must belong / not belong to the specified region(s). + - **Country**: The customer's country, which is determined through their shipping address, must belong / not belong to the specified countries. + - **Sales Channel**: The customer must be / must not be placing the order from the specified sales channels. + - **Currency Code**: The currency code that the customer must / must not be placing the order in. + - Select the operator of the condition: + - **In**: The customer's value for the chosen attribute must belong to the specified values. + - **Equals**: The customer's value for the chosen attribute must be the same as the specified value. + - **Not In**: The customer's value for the chosen attribute must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to allow only customers belonging to the B2B group to use this promotion: + - Set the Attribute to Customer Group. + - Set the Operator to In or Equals. + - Set the Value to the B2B customer group. +5. Once you're done, click the Save button. + +![Edit who can use the promotion form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739951824/User%20Guide/Screenshot_2025-02-19_at_9.56.55_AM_miqo10.png) + +--- + +## Edit the Items the Promotion Applies To + + + +For "Buy X Get Y" or "buyget" promotion types, this section allows you to edit which items the customer gets for free when they buy the specified items. To edit the items that the customer must buy to get the free items, refer to the [Edit Buy X Promotion Condition](#edit-buy-x-promotion-condition) section. + + + +To edit the items the promotion applies to: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the "What items will the promotion be applied to?" section. +3. Choose Edit from the dropdown. +4. In the side window that opens, you can edit existing conditions or add new ones by clicking the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product**: The promotion applies / doesn't apply to the specified product(s). + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to apply the promotion on products in the "Business desktop PC" category: + - Set the Attribute to Product Category. + - Set the Operator to In or Equals. + - Set the Value to the "Business desktop PC" product category. +5. Once you're done, click the Save button. + +![Edit the items the promotion applies to form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739951994/User%20Guide/Screenshot_2025-02-19_at_9.59.46_AM_n5jbpg.png) + +--- + +## Edit Buy X Promotion Condition + +For "Buy X Get Y" or "buyget" promotion types, you can edit the "Buy X" part of the promotion. For example, change "Buy 3 shirts to get 1 for free" to "Buy 2 shirts to get 1 for free". + + + +To edit the items that the customer gets for free when they buy the specified items, refer to the [Edit the Items the Promotion Applies To](#edit-the-items-the-promotion-applies-to) section. + + + +To edit the "Buy X" part of the promotion: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the "What needs to be in the cart to unlock the promotion?" section. +3. Choose Edit from the dropdown. +4. In the side window, you can edit the minimum required quantity of the product in the "Buy X" condition, and any other existing conditions. You can also add new conditions by clicking the "Add condition" button. For each condition: + - Select the attribute in the first field. This is the attribute that the condition applies to. It can be: + - **Product**: The promotion applies / doesn't apply to the specified product(s). + - **Product Category**: The promotion applies / doesn't apply to the products belonging to the specified categories. + - **Product Collection**: The promotion applies / doesn't apply to the products belonging to the specified collection(s). + - **Product Type**: The promotion applies / doesn't apply to the products belonging to the specified type(s). + - **Product Tag**: The promotion applies / doesn't apply to the products belonging to the specified tag(s). + - Select the operator of the condition: + - **In**: The value of the item in the cart must belong to the specified values. + - **Equals**: The value of the item in the cart must equal the specified values. + - **Not In**: The value of the item in the cart must not belong to the specified values. + - Select the value of the attribute. + - For example, if you want to apply the promotion on products in the "Shirts" category: + - Set the Attribute to Product Category. + - Set the Operator to In or Equals. + - Set the Value to the "Shirts" product category. +5. Once you're done, click the Save button. + +![Edit Buy X Promotion Condition form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739952429/User%20Guide/Screenshot_2025-02-19_at_10.06.59_AM_raqa9m.png) + +--- + +## Add Promotion to Campaign + +If you created a promotion without a campaign, you can add it to an existing campaign from its details page. + +To add a promotion to a campaign: + +1. Go to the promotion's details page. +2. Click on "Add to Campaign" at the top right of the "Campaign" section. +3. In the side window that opens: + - Select "Existing Campaign". + - Choose the campaign from the "Existing Campaign" dropdown. For promotions that are applied as a fixed amount, only campaigns whose budget uses the same currency as the promotion are shown. +4. Once you're done, click the Save button. + +![Add Promotion to Campaign form](https://res.cloudinary.com/dza7lstvk/image/upload/v1739952681/User%20Guide/Screenshot_2025-02-19_at_10.11.12_AM_enjz4o.png) + +--- + +## Change Promotion's Campaign + +You can change the campaign that a promotion belongs to, or remove it from a campaign. + +To change a promotion's campaign: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the "Campaign" section. +3. Choose Edit from the dropdown. +4. In the side window that opens: + - To remove the promotion from its current campaign, select "Without Campaign". + - To change the promotion's campaign, select "Existing Campaign" and choose the campaign from the "Existing Campaign" dropdown. +5. Once you're done, click the Save button. + +--- + +## Delete Promotion + + + +Deleting a promotion is irreversible. + + + +To delete a promotion: + +1. Go to the promotion's details page. +2. Click the icon at the top right of the first section. +3. Choose Delete from the dropdown. +4. Confirm deleting the promotion in the pop-up by entering its code and clicking the "Delete" button. diff --git a/www/apps/user-guide/app/promotions/page.mdx b/www/apps/user-guide/app/promotions/page.mdx new file mode 100644 index 0000000000..eb6ba9e9b4 --- /dev/null +++ b/www/apps/user-guide/app/promotions/page.mdx @@ -0,0 +1,33 @@ +--- +sidebar_autogenerate_exclude: true +--- + +export const metadata = { + title: `Promotions`, +} + +# {metadata.title} + +The Promotions domain allows you to create and manage discounts and campaigns in your store. You can create different types of promotions, such as discounted amount or percentage, or buy X get Y for free. + +Promotions belong to campaigns, and you can manage campaign budgets, start and end dates, and more, giving you granular control over your promotions. + +You can view the list of promotions in your commerce store by clicking on Promotions from the sidebar menu. + +In the list, you can see promotion details such as the code and status. You can also search, filter, and sort the promotions to find the specific item you are looking for. + + + +Find tips to use lists effectively in [this guide](../tips/lists/page.mdx). + + + +![Promotions list](https://res.cloudinary.com/dza7lstvk/image/upload/v1739893625/User%20Guide/Screenshot_2025-02-18_at_5.46.51_PM_khqnjq.png) + +--- + +## Manage Promotions + +- [Create a Promotion](./create/page.mdx) +- [Manage Promotions](./manage/page.mdx) +- [Manage Campaigns](./campaigns/page.mdx) \ No newline at end of file diff --git a/www/apps/user-guide/generated/edit-dates.mjs b/www/apps/user-guide/generated/edit-dates.mjs index 6cd011b25a..9dc1262d71 100644 --- a/www/apps/user-guide/generated/edit-dates.mjs +++ b/www/apps/user-guide/generated/edit-dates.mjs @@ -55,5 +55,9 @@ export const generatedEditDates = { "app/products/edit/page.mdx": "2025-02-17T17:13:29.141Z", "app/products/variants/page.mdx": "2025-02-18T12:10:36.029Z", "app/products/create/bundle/page.mdx": "2025-02-18T12:17:32.166Z", - "app/products/create/multi-part/page.mdx": "2025-02-18T12:17:29.629Z" + "app/products/create/multi-part/page.mdx": "2025-02-18T12:17:29.629Z", + "app/promotions/campaigns/page.mdx": "2025-02-19T09:02:49.193Z", + "app/promotions/create/page.mdx": "2025-02-19T09:00:51.979Z", + "app/promotions/manage/page.mdx": "2025-02-19T09:01:11.841Z", + "app/promotions/page.mdx": "2025-02-19T09:00:12.501Z" } \ No newline at end of file diff --git a/www/apps/user-guide/generated/sidebar.mjs b/www/apps/user-guide/generated/sidebar.mjs index 795bc86eb9..7ef6605ceb 100644 --- a/www/apps/user-guide/generated/sidebar.mjs +++ b/www/apps/user-guide/generated/sidebar.mjs @@ -275,26 +275,38 @@ export const generatedSidebar = [ "loaded": true, "isPathHref": true, "type": "category", - "path": "/discounts", - "title": "Discounts", - "autogenerate_path": "/discounts", + "title": "Promotions", "children": [ { "loaded": true, "isPathHref": true, "type": "link", - "path": "/discounts/create", - "title": "Create a Discount", - "description": "", + "title": "Overview", + "path": "/promotions", "children": [] }, { "loaded": true, "isPathHref": true, "type": "link", - "path": "/discounts/manage", - "title": "Manage Discounts", - "description": "", + "title": "Create Promotion", + "path": "/promotions/create", + "children": [] + }, + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Manage Promotion", + "path": "/promotions/manage", + "children": [] + }, + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Manage Campaigns", + "path": "/promotions/campaigns", "children": [] } ] diff --git a/www/apps/user-guide/sidebar.mjs b/www/apps/user-guide/sidebar.mjs index a9f650d5cb..80211898aa 100644 --- a/www/apps/user-guide/sidebar.mjs +++ b/www/apps/user-guide/sidebar.mjs @@ -165,9 +165,29 @@ export const sidebar = sidebarAttachHrefCommonOptions([ }, { type: "category", - path: "/discounts", - title: "Discounts", - autogenerate_path: "/discounts", + title: "Promotions", + children: [ + { + type: "link", + title: "Overview", + path: "/promotions", + }, + { + type: "link", + title: "Create Promotion", + path: "/promotions/create", + }, + { + type: "link", + title: "Manage Promotion", + path: "/promotions/manage", + }, + { + type: "link", + title: "Manage Campaigns", + path: "/promotions/campaigns", + }, + ], }, { type: "category",