> ## 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.

# How Reval works: from the chosen plan to the Shopify order

> A complete walkthrough of a subscription's lifecycle in Reval: signup, automatic charges, customer portal and payment retries.

Reval coordinates three systems —the buyer's browser, Mercado Pago and Shopify— so that every subscription works end to end without manual intervention. This page explains how information flows at each stage, both from your store's perspective and from the subscriber's.

<Note>
  **Shopify is the single source of truth.** Every approved charge generates a real Shopify order with its product lines, shipping cost and taxes calculated live. There is no parallel database and no "phantom" orders: what you see in your Shopify admin is what was actually charged and will ship.
</Note>

## Full subscription flow

```text theme={null} theme={null}
Buyer picks a plan
        │
        ▼
  Reval custom checkout
  (tokenization in the browser)
        │
        ▼
  Open-amount mandate created in MP
        │
        ▼
  Automatic charge on every cycle
        │
        ▼
  MP webhook → Reval validates idempotency
        │
        ▼
  Real order created in Shopify
  (lines + shipping + live taxes)
        │
        ▼
  Fulfillment through your usual flow
```

***

<Tabs>
  <Tab title="Merchant view">
    ### What happens in your store

    As a merchant, your main interaction with Reval happens at two moments: the initial setup (plans, discounts, frequencies) and reviewing reports. The day-to-day runs automatically.

    #### Subscription signup

    <Steps>
      <Step title="The buyer picks a plan in the buy box">
        A plan selector appears on the product page with the frequency (weekly, monthly, bimonthly, etc.) and the discount attached to each one. The buyer selects the plan and clicks "Subscribe".
      </Step>

      <Step title="Reval custom checkout">
        The buyer enters their card details directly in Reval's checkout. **Tokenization happens in the browser**, with no redirect to Mercado Pago. Reval's server never sees the full card number.
      </Step>

      <Step title="Creating the open-amount recurring charge mandate">
        Reval creates a recurring charge mandate (preapproval) in Mercado Pago using the **open-amount** modality — that is, without tying it to a fixed Mercado Pago plan. This is essential because a mandate tied to an MP plan can only charge a fixed amount, with no ability to add shipping, taxes or per-customer discounts. With an open amount, each cycle charges the exact amount (product + shipping + taxes) queried live against your store's real Shopify rates.
      </Step>

      <Step title="First charge and Shopify order">
        The first charge runs immediately. When Mercado Pago confirms the payment via webhook, Reval creates the first Shopify order with all the lines, shipping and taxes. That order enters your normal fulfillment flow.
      </Step>
    </Steps>

    #### Recurring cycle

    <Steps>
      <Step title="Automatic charge through the mandate">
        On the cycle date, Mercado Pago executes the charge using the active mandate. The amount is the one set on the mandate —product, shipping and tax calculated at signup time— and it only changes if someone explicitly updates it from the admin or the portal.
      </Step>

      <Step title="MP webhook reaches Reval">
        Mercado Pago notifies the result of the charge (approved or declined) via a webhook. Reval verifies idempotency: if the event was already processed, it discards it without creating a duplicate order.
      </Step>

      <Step title="Order created in Shopify (approved charge)">
        If the charge was approved, Reval immediately creates a Shopify order with the subscription's current lines, the shipping cost and taxes. The order is available for fulfillment right away.
      </Step>

      <Step title="Declined charge">
        Reval logs the failure with its reason and shows it in the admin and in the portal. **Mercado Pago retries the charge on its own**; if the retries run out, it cancels the mandate and Reval marks the subscription as cancelled. No order is created until there is an approved charge.
      </Step>
    </Steps>

    <Tip>
      You can see each subscription's status, its charge attempts and its order history directly in the Reval panel inside your Shopify admin.
    </Tip>
  </Tab>

  <Tab title="Subscriber view">
    ### What the buyer experiences

    The subscriber doesn't need to create a separate account or install anything. Everything happens inside your Shopify store.

    #### Subscription signup

    <Steps>
      <Step title="Picks the plan on the product">
        On the product page, the buyer sees Reval's buy box with the available subscription options: frequencies and discounts. They choose whichever suits them best.
      </Step>

      <Step title="Enters their card details">
        Reval's custom checkout appears inside your store's theme. The buyer enters card number, expiry and CVV. The data is tokenized directly in their browser.
      </Step>

      <Step title="Confirms the subscription">
        On confirmation, the first charge is processed immediately. The buyer receives a confirmation and becomes active in the self-service portal.
      </Step>
    </Steps>

    #### Self-service portal

    The subscriber portal lives inside your store's theme (it isn't an external page). From there, each customer can:

    <CardGroup cols={2}>
      <Card title="See the next charge" icon="calendar">
        Next cycle date, estimated amount and products included in that shipment.
      </Card>

      <Card title="Change products or quantities" icon="pen-to-square">
        Swap a variant (another flavor, another size) or adjust the quantity of each item.
      </Card>

      <Card title="Add an add-on" icon="circle-plus">
        Add a one-off product to the next cycle. It's charged immediately and ships together with the recurring order.
      </Card>

      <Card title="Pause or cancel" icon="circle-pause">
        Pause the charges and resume them manually whenever they want, or cancel while stating a reason.
      </Card>

      <Card title="Edit the shipping address" icon="location-dot">
        Update the delivery details, which apply from the next shipment onward.
      </Card>

      <Card title="See history" icon="clock-rotate-left">
        Review the orders generated by the subscription and how much they've saved compared to the price without a plan.
      </Card>
    </CardGroup>

    <Info>
      The portal uses **cryptographically signed links**, which means the buyer gets in from the confirmation email without having to create a password. The links have a configurable expiry.
    </Info>
  </Tab>
</Tabs>

***

## Security and reliability

Reval is designed so that every operation is safe and doesn't leave inconsistent states behind:

<CardGroup cols={2}>
  <Card title="Tokenization in the browser" icon="shield-halved">
    Card details never pass through Reval's servers. The Mercado Pago SDK tokenizes directly in the buyer's browser.
  </Card>

  <Card title="Idempotent webhooks" icon="check-double">
    Every Mercado Pago event is processed exactly once. If the webhook arrives duplicated, Reval detects it and doesn't create an extra order.
  </Card>

  <Card title="Signed links" icon="key">
    The portal and the checkout use cryptographically signed links. Without the right signature, there's no access.
  </Card>

  <Card title="Orders that don't get lost" icon="rotate">
    If a charge is approved but the order can't be created —because a product went out of stock, for example— it's queued and a daily process retries it until it succeeds. The customer already paid: their order doesn't fall through the cracks.
  </Card>
</CardGroup>