> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartble.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating discount codes and automatic promotions

> Learn how to create manual coupon codes and automatic cart promotions in Cartble, set discount values, scope rules, prerequisites, and usage limits.

Cartble's discount system lets you create two kinds of savings rules: **manual coupon codes** that customers enter at checkout, and **automatic promotions** that apply to eligible carts without any customer action. Both are managed in **Admin → Discounts & Coupons**.

## Discount methods

<CardGroup cols={2}>
  <Card title="Manual coupon (code)" icon="tag">
    A specific code (e.g., `VIP20`, `SUMMER50`) that the customer types into the coupon field at checkout. The code is case-insensitive and trimmed automatically.
  </Card>

  <Card title="Automatic" icon="sparkles">
    Applied silently to the cart whenever the conditions are met. No code entry required — the discount appears automatically in the order total.
  </Card>
</CardGroup>

## Creating a discount rule

Navigate to **Admin → Discounts & Coupons** and click **New Discount**.

<Steps>
  <Step title="Choose the method">
    Select **Manual Coupon** or **Automatic**. For manual coupons, enter the code you want customers to use or click **Generate random code** to create an 8-character alphanumeric code.
  </Step>

  <Step title="Set the discount type and value">
    Choose one of three discount types:

    | Type            | Description                                                     |
    | --------------- | --------------------------------------------------------------- |
    | `percentage`    | Reduces the cart total by a percentage. Enter `20` for 20% off. |
    | `fixed_amount`  | Deducts a fixed monetary amount from the cart total.            |
    | `free_shipping` | Waives the shipping charge entirely. No value needed.           |
  </Step>

  <Step title="Define the scope">
    Control which products the discount applies to:

    | Scope                           | Description                                                        |
    | ------------------------------- | ------------------------------------------------------------------ |
    | **All products**                | Applies to every item in the store                                 |
    | **By product type (blueprint)** | Restricts to physical, subscription, digital, or service resources |
    | **Specific resources**          | Applies only to the products you hand-pick from the list           |
  </Step>

  <Step title="Add prerequisites (optional)">
    Set minimum requirements that must be met before the discount activates:

    * **Minimum cart subtotal** — the cart's item total must reach this amount
    * **Minimum item quantity** — the customer must have at least this many items in their cart
  </Step>

  <Step title="Set usage limits">
    Control how many times the discount can be used:

    | Limit                | Description                                                               |
    | -------------------- | ------------------------------------------------------------------------- |
    | **Global limit**     | Maximum total redemptions across all customers. Set to `0` for unlimited. |
    | **One per customer** | Restricts each customer (identified by email) to a single use.            |
  </Step>

  <Step title="Set the validity window">
    Enter a **start date** (required) and an optional **end date**. The discount is inactive outside this window. You can also use the active toggle to pause a discount manually at any time.
  </Step>
</Steps>

## Discount statuses

A discount rule on the list shows one of four states:

| Status        | Meaning                                 |
| ------------- | --------------------------------------- |
| **Active**    | Live and redeemable at checkout         |
| **Paused**    | Manually disabled via the active toggle |
| **Expired**   | The end date has passed                 |
| **Exhausted** | The global usage limit has been reached |

<Note>
  Deleting an active discount removes it immediately. Any customer who tries to apply a deleted code will see an error at checkout.
</Note>

## How discounts are recorded on orders

When a customer redeems a discount, Cartble stores an `appliedDiscount` object on the order record. This includes the discount's title, code (if applicable), type, method, and the exact amount deducted in cents — so your order history always reflects what was actually charged.

## Tips for common scenarios

<AccordionGroup>
  <Accordion title="One-time welcome discount for new customers">
    Create a manual coupon with type `percentage`, set **One per customer** to on, and leave the global limit at `0`. Share the code in your welcome email.
  </Accordion>

  <Accordion title="Automatic free shipping above a threshold">
    Create an automatic discount with type `free_shipping` and set a **minimum cart subtotal** equal to your free-shipping threshold. No code required — it activates as soon as the cart qualifies.
  </Accordion>

  <Accordion title="Flash sale on a specific product type">
    Create an automatic discount scoped to a specific blueprint (e.g., "Subscription"), set the type to `percentage`, and use the **start date** and **end date** fields to define the sale window.
  </Accordion>

  <Accordion title="Limited-run promotional code">
    Create a manual coupon and set a **global limit** (e.g., `100`). Once 100 customers redeem it, the code becomes exhausted automatically.
  </Accordion>
</AccordionGroup>