> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a plan

A pricing plan draws on two catalogs that belong to your app: **app features** and **[usage events](/introduction-6)**. You define each one once, then include it in as many plans as you need. Events are app-level: you can define and track them without ever pricing them.

The plans list is searchable by **name** or **handle**. [Global search](/global-search) jumps to a plan from anywhere in the organization.

Usage pricing comes in two shapes, and a plan carries one of them: **per unit** on an event key ("\$0.01 per 1,000 emails"), or **percentage of value** on a [view](/usage-views) ("2% of GMV"). Both are set the same way, in the same section of the plan form.

<Steps>
  <Step title="Define your app features">
    Go to **Plan builder → Features** and select **Create feature**. Name it, keep or edit the **key** your app will gate on, and pick a type: **Boolean (Enabled/Disabled)** unlocks a capability, **Number (with limit)** sets a limit the plan fills in.
  </Step>

  <Step title="Define your events">
    Go to **Usage → Events** and select **Create event**. Name it, keep or edit the **key**, and set the **unit** you meter: email, character, run. There is no pricing here: an event's quota and rate are per-plan, set in the next step.
  </Step>

  <Step title="Build the plan">
    Open **Plan builder** and select **Create plan**.

    | Section | What you set |
    | - | - |
    | **Basics** | The plan name and description merchants see |
    | **Pricing and billing** | Monthly price in USD, optional annual price, trial period |
    | **Features included** | The app features this plan unlocks, and a **Limit** for the number ones |
    | **Usage pricing** | The subject this plan meters (an event, or a [view](/usage-views) over one) with the included quota, the overage rate and the units it covers, and a monthly cap |

    Both sections can create catalog entries on the spot: **Create feature** and **Add event** add to the catalog and select the new entry for you.

    Clearing **Monthly price** leaves the field empty. Saving requires you to enter a price, including `0` for a free plan. Clearing an annual price removes that optional price when you save.
  </Step>

  <Step title="Publish it">
    A new plan is saved as a draft and stays hidden from merchants. Select **Activate plan** to publish it to the Shopify Billing API. **Switch to draft** hides it again from new subscribers, and existing subscribers keep access.
  </Step>
</Steps>

## What the plan shape allows

Shopify sets the boundaries for how recurring and metered charges combine.

| Rule | Why |
| - | - |
| An annual price needs a monthly price | The annual price is a variant of the monthly one |
| A plan with an annual price can't meter usage | Shopify bills usage monthly |
| One subject per plan can charge overage, an event **or** a view, not both | A subscription carries a single usage line item |
| Only a **billing-period** view can be priced | Shopify bills usage per 30-day cycle, so a rolling window has no overage to charge |
| A view has to have finished computing before it can be priced | Until then it has read only part of your history, and the first charge would be a figure nobody could explain |

A monthly price of 0 makes the plan free, and merchants subscribe without a Shopify charge, unless the plan meters usage, which is still something to charge for. "\$0/month plus 2% of GMV" is a real plan and goes through Shopify like any other.

## Percentage of value, end to end

The shape everyone asks for: charge a share of what the app is worth to the merchant rather than a fixed rate per action.

<Steps>
  <Step title="Track the value in the properties">
    ```ts theme={null}
    await track({
      eventKey: "order_created",
      quantity: 1,
      properties: { orderId: order.id, total_price: 129.5 },
    })
    ```
  </Step>

  <Step title="Define the view">
    On the `order_created` event, add a view that **totals `total_price`** over the **billing period**. Call it `gmv`. The create-time preview shows what the definition would give on your last 90 days before you commit to it.
  </Step>

  <Step title="Price it">
    In the plan's usage section, switch on the `gmv` view and set an **overage rate of 0.02 per 1 unit**: 2% of every unit of GMV. Add an included quantity if the first \$1,000 is free, and a monthly cap.
  </Step>
</Steps>

Because the view is computed over your whole history, it reports correct numbers for orders tracked long before you defined it, but a plan only charges for usage from the moment the view existed. Nothing is billed retroactively.

### What the merchant approves

The approval screen states the pricing model in words, and Meridian states it as the **exact** rate it will charge, converted to the merchant's currency, never rounded to the cent. A sub-cent rate is stated per a whole number of units instead: `0.005` per unit is approved as **"0.05 USD per 10"**, not as `0.01` per unit (which would promise double) and not as `0.00` (which reads as free). The two statements price identically, and the second one is money a merchant can read.

Rates below one cent are worth setting when your metric is fine-grained: they accumulate exactly and are charged together rather than being rounded away one at a time.

<Note>
  A view a plan prices is **locked**: its aggregation, property, window and key can no longer be changed, it cannot be recomputed, and it cannot be deleted. A metric merchants are billed on cannot be redefined underneath them. Renaming it is still fine, and removing it from every plan unlocks it again. To meter something different, create a second view. The old one keeps its charge history.
</Note>

<Note>
  Feature and event keys can't be changed after creation, because your app gates on them at runtime. Deleting a feature or an event removes it from every plan that includes it.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.