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

# Surprises: gifts and cycle-based discounts to retain subscribers

> Create rules that reward specific cycles of a subscription with gift products or a one-time discount, to reduce churn and reward loyalty.

**Surprises** rewards your subscribers on specific cycles: a gift product that rides along free in that cycle's order, a one-time discount on that charge, or both. The rules are managed in **Apps → Reval → Surprises**.

## Creating a rule

<Steps>
  <Step title="Name">
    An internal name that tells you what it does, e.g. "Gift on the 2nd order".
  </Step>

  <Step title="Trigger">
    When the rule fires:

    * **Specific order number** — cycle N of the subscription (e.g. the 3rd charge). With **Apply per customer** enabled, the count adds up the orders from *all* of the customer's subscriptions and the reward is granted **only once per customer**; disabled, it counts per subscription and is granted once per subscription.
    * **Order streak** — N cycles in a row with no interruption. The streak breaks if more than 1.5× the plan's frequency passes without an order: a long pause or a charge that was never recovered resets it; a short pause resumed in time keeps it.
  </Step>

  <Step title="Reward">
    At least one of the two (they can be combined):

    * **Discount** — a percentage or fixed amount off **the products in that single charge** (shipping isn't discounted; tax is recalculated). It applies from **order 2** onward: to discount the first order there's the plan's first-purchase discount.
    * **Gifts** — one or more products/variants from the catalog, added **at \$0 cost** to that cycle's order.
  </Step>

  <Step title="Condition (optional)">
    Subscription statuses that must hold at the moment of applying: **Active**, or **Failed charge** (the cycle came off a decline and was recovered). It's satisfied by any of the ticked ones; with none ticked, it always applies.

    Conditions are evaluated at the moment of the charge, so there's no "Paused" option: a paused subscription has its debit paused in Mercado Pago and doesn't generate charges.
  </Step>
</Steps>

<Note>
  If a customer meets the criteria of **several rules in the same cycle**, **all** the rewards are applied on that order.
</Note>

## How they're applied

* **Gifts**: they're added as \$0 lines to the Shopify order of the cycle that triggered the rule. The gift's stock follows the same inventory logic configured for that product — with one deliberate exception: a gift that's out of stock **never holds back** the paid order; it's skipped (recorded in the logs) and the order goes out anyway. If the gift was skipped, the reward is **not** counted as applied and the customer isn't notified, and the rule can still reward them on a later cycle.
* **Discounts**: because Mercado Pago charges the recurring amount up front, the discount is **prepared one cycle ahead** (the debit amount is lowered for that charge and automatically restored afterwards). That cycle's Shopify order is issued with the discounted prices, so the order and the charge match. If the discounted amount would fall below Mercado Pago's minimum, the rule is skipped and that's logged.
* Every reward delivered is counted on the rule ("Applied N times") and emits the **"Surprise applied"** event to Klaviyo / Shopify Flow — you can build a notification email, or communicate nothing at all and make it a genuine surprise. The gift's notice goes out once the order carrying it has been created, not before.

<Warning>
  Editing or deleting a rule doesn't affect rewards already applied, nor the gifts on an order that's still waiting on stock. Pausing a rule (the "Pause" button) deactivates it without losing its history.
</Warning>

<Note>
  If you change a subscription's price (product change, quantity or bulk price update) while it had a discount prepared, the discount is cancelled: your new price wins. The rule can prepare it again on a later cycle.
</Note>