---
title: Promotions
description: Create automatic discounts or promotion codes and control who can use them.
---

Use Promotions to define a discount, its customer experience, its eligibility rules, and whether it is active or still a draft.

## Why and when to use Promotions

Create a promotion for a planned campaign, customer incentive, free-shipping offer, or buy-and-get offer. Start in Draft while checking the details; use Active only when the discount should be eligible at checkout.

## Availability and prerequisites

- Open a Runner project with a ready store backend.
- Create the products referenced by a Buy X Get Y rule before building that promotion.
- Confirm the relevant market currency and shipping setup before offering amount-based or free-shipping discounts.
- Test checkout behavior with an appropriate test order before sharing a code publicly.

## Open Promotions

**Entry path:** **Workspace → choose a store → Store Operations → Promotions**

## Main controls

| Control | Why you use it | What happens when selected |
| --- | --- | --- |
| **Create** / **Add First Promotion** | Choose a new discount type | Opens a menu for Amount off order, Percentage off order, Buy X Get Y, or Free shipping. The empty list uses **Add First Promotion**. |
| **Amount off order** | Discount the order total by a fixed amount | Opens a form with amount, method, status, and eligibility settings. |
| **Percentage off order** | Discount the order total by a percentage | Opens a form with a percentage value and the shared settings. |
| **Buy X Get Y** | Give selected products after a qualifying purchase | Opens quantity and product selectors for what the customer buys and gets. |
| **Free shipping** | Remove eligible shipping fees | Opens a promotion whose discount applies to shipping. |
| **Automatic discount** | Apply the promotion without asking the customer for a code | Checkout evaluates the rules automatically, but the form still requires a code value to identify the promotion. |
| **Promotion code** | Require a customer-entered code | Customers must enter the required code at checkout. |
| **Active** / **Draft** | Control whether the promotion is usable | Saves the chosen operating state with the promotion. |
| **Add condition** | Limit who can use the promotion | Adds customer attribute, operator, and value fields. |
| **Save** | Apply a valid create or edit form | Creates or updates the promotion and returns to the promotion list after success. |
| Promotion row | Inspect one promotion | Opens type, method, status, code, usage, and available actions. |
| **Edit** | Change the selected promotion | Opens the edit form for that existing promotion type. |
| **Delete** | Permanently remove the promotion | From the desktop list, opens an irreversible confirmation naming the promotion code. The current mobile view does not show this action. |

## Create a promotion

1. Select **Create**, or **Add First Promotion** when the list is empty.
2. Choose the type that matches the offer.
3. Choose **Automatic discount** or **Promotion code**.
4. Enter the required code value. For **Promotion code**, enter the exact code customers should use; for **Automatic discount**, customers do not enter it.
5. Choose **Draft** while preparing or **Active** when it should be eligible.
6. Enter the Discount value, or select the Buy and Get products and quantities.
7. Leave eligibility as all customers or select **Add condition** and complete every condition field.
8. Review the summary, then select **Save**.
9. Return to the list and confirm the Type, Method, Status, Code, and Used values.

## Edit or remove a promotion

1. Select a promotion row.
2. Choose **Edit**, change the intended fields, and select **Save**.
3. Test the updated rule before sharing it with customers.
4. To remove it, return to the desktop list, select **Delete**, and read the code in the confirmation.
5. Continue only if permanent removal is intended.

## States and limits

- **Draft** is stored but not intended to be usable at checkout.
- **Active** is eligible to apply when its method and conditions match.
- **Inactive** can appear in the list when an existing promotion is not currently active.
- A percentage value must be between 1 and 100.
- The form requires a code value for both methods. Customers enter it only when **Promotion code** is selected.
- Buy X Get Y requires both the qualifying product and the free product.
- Every added condition needs an attribute, operator, and value.
- With an automatic discount, checkout decides whether its rules match; the customer does not enter the form's code value.

## Troubleshooting

- **Save is disabled or shows an error:** Complete the value, code, product, quantity, or condition fields named by the form.
- **A code does not work at checkout:** Confirm exact spelling, Active status, customer eligibility, product requirements, market, and the current checkout.
- **An automatic discount does not apply:** Check that the order meets every condition and that another promotion is not changing the expected result.
- **A free-shipping promotion has no visible effect:** Confirm the order has an eligible saved shipping option and that the promotion is Active.
- **Promotion list fails to load:** Refresh the page and confirm the correct project before trying to create a duplicate.

## Related guides

- [Products](./products)
- [Customers](./customers)
- [Shipping](./shipping)
- [Orders](./orders)