Ree Plugin — Complete User Manual

Ree is an all-in-one billing and payments plugin for WordPress. It handles subscriptions, one-time purchases, digital downloads, license keys, usage-based billing, and product variants — all without WooCommerce. This manual covers every feature available today.

---

Table of Contents

1. Quick Setup
2. Plans & Subscriptions
3. Products & One-Time Purchases
4. Product Variants
5. Bundles & Add-ons
6. Digital Downloads
7. License Keys
8. Shopping Cart (Mixed Checkout)
9. Usage & Metered Billing
10. Customer Portal
11. Email Notifications
12. Payment Gateways
13. Webhooks
14. REST API
15. Shortcodes Reference
16. Admin Dashboard
17. Developer Hooks & Filters

---

1. Quick Setup

Requirements

• WordPress 6.0+
• PHP 8.0+
• A Stripe account (or another registered payment gateway driver)

Installation

1. Upload the ree folder to /wp-content/plugins/
2. Activate the plugin via Plugins → Installed Plugins
3. Go to Ree → Settings → Gateway
4. Select Stripe, enter your Secret Key, Publishable Key, and Webhook Secret
5. Click Test Stripe Connection to confirm credentials work
6. Copy the Webhook URL shown and paste it into Stripe → Developers → Webhooks
7. Enable these webhook events on Stripe: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed
8. Click Save Settings

The plugin auto-creates all required database tables on first activation.

---

2. Plans & Subscriptions

Plans are recurring billing products (monthly, annual, etc.) backed by Stripe Prices.

Creating a Plan

1. Go to Ree → Plans → click Add Plan
2. Fill in:
   • Plan Key — unique slug, e.g. pro_monthly
   • Plan Name — displayed to customers, e.g. “Pro Monthly”
   • Stripe Price ID — copy from your Stripe Dashboard (Stripe → Products → your product → price ID starting with price_)
   • Amount — in cents, e.g. 2900 = $29.00
   • Currency — lowercase ISO code, e.g. usd
   • Interval — month or year
   • Trial Days — optional free trial (0 = no trial)
   • Status — Active / Inactive
3. Click Save Plan

Checkout Flow

When a customer clicks a Subscribe button, Ree creates a Stripe Checkout Session in subscription mode and redirects them. After payment, Stripe sends a checkout.session.completed webhook and Ree records the subscription in the database, stores the Stripe customer ID on the user, and sends a welcome email.

Subscription Lifecycle

Stripe Event	Ree Action
invoice.paid	Sets status → active, updates period dates
invoice.payment_failed	Sets status → past_due, sends dunning email
customer.subscription.updated	Updates status, cancel_at_period_end, period_end
customer.subscription.deleted	Sets status → cancelled, sends cancellation email
customer.subscription.paused	Sets status → paused
customer.subscription.resumed	Sets status → active

Free Trial

Set Trial Days on a plan to give new subscribers a free trial period. Stripe will not charge until the trial ends. No credit card is required only if your Stripe settings allow it.

---

3. Products & One-Time Purchases

Products are for one-time sales — digital files, plugins, themes, courses, etc.

Creating a Product

1. Go to Ree → Products → click Add Product
2. Fill in:
   • Product Key — unique slug, e.g. my_plugin
   • Product Name — customer-facing name
   • Stripe Price ID — a one-time Stripe price (not a recurring price)
   • Amount — in cents
   • Currency — e.g. usd
   • Description — shown in cart
   • Download File URL — direct URL to the downloadable file (can be a private S3 URL, CDN URL, etc.)
   • Download Limit — max downloads per order (0 = unlimited)
   • Issue License Key — check to auto-generate a license key on purchase
   • Activation Limit — how many domain activations are allowed per license key
3. Click Save Product

Direct Buy Now Checkout

Use the shortcode to create a single-product checkout button that bypasses the cart entirely.

Order Record

After a successful one-time payment, Ree creates an order record with: email, amount, currency, Stripe payment intent ID, download token, and status paid. A purchase receipt email is automatically sent.

---

4. Product Variants

Variants let customers choose from multiple configurations of the same product — e.g. “Personal License / Team License / Agency License” or “Windows / Mac / Linux” — each with its own Stripe price.

Creating Variants

1. Go to Ree → Products, find your product, click Variants
2. Click Add Variant
3. Fill in:
   • Variant Key — unique slug, e.g. my_plugin_team
   • Variant Name — shown in the dropdown, e.g. “Team License — $79”
   • Stripe Price ID
   • Amount — in cents
   • Sort Order — controls dropdown order
   • Status — Active / Inactive

Storefront Behavior

When a product has active variants, the shortcode renders a dropdown instead of a simple button. The customer selects a variant, then adds it to the cart. The selected variant’s price is used for checkout.

---

5. Bundles & Add-ons

Bundles

A bundle groups multiple products together and sells them as a single item at a combined price. Manage bundles under Ree → Bundles.

Add-ons

Add-ons are optional extras customers can include with their cart at checkout (e.g. priority support, extended license, installation service). Manage add-ons under Ree → Add-ons.

---

6. Digital Downloads

Ree delivers digital files through a secure, token-based download system — never exposing real file URLs to customers.

How It Works

1. On successful payment, Ree generates a unique 32-character download token and stores it with the order
2. The token expires 7 days after purchase (configurable)
3. The purchase receipt email includes a Download Now button pointing to /ree-download?token=xxx
4. When a customer clicks the link, Ree:
   • Validates the token exists and matches a paid order
   • Checks the token hasn’t expired
   • Checks the download count against the per-product limit
   • Increments the download counter
   • Redirects to the actual file URL

Security

• Real file URLs are never exposed to the browser — customers only see the /ree-download?token=xxx URL
• Expired tokens return HTTP 410 Gone
• Orders with non-paid status are blocked (HTTP 403)
• Download limit enforcement prevents abuse

Download Limit

Set Download Limit on the product to 0 for unlimited, or any positive integer. When the limit is reached, the customer sees a friendly message directing them to support.

---

7. License Keys

When a product has Issue License Key enabled, Ree automatically generates a license key on every purchase and delivers it via email.

License Key Format

Keys use the format XXXXX-XXXXX-XXXXX-XXXXX with an unambiguous character set (no 0, O, 1, I, L) to avoid confusion.

Activation Limits

Each license key has a configurable activation limit (e.g. 1 site, 5 sites, unlimited). Activations are tracked per domain.

License REST API

Ree exposes three public endpoints your plugin/software can call to validate and manage licenses:

Endpoint	Method	Description
/ree/v1/license/check	POST	Check if a license key is valid and active
/ree/v1/license/activate	POST	Activate a license key on a domain
/ree/v1/license/deactivate	POST	Deactivate a license key from a domain

All endpoints accept a JSON body with license_key and (for activate/deactivate) domain.

Example: Check License

POST https://yoursite.com/wp-json/ree/v1/license/check
Content-Type: application/json

{
  "license_key": "ABCDE-FGHJK-MNPQR-STUVW"
}

// Response (valid):
{ "valid": true, "status": "active", "activations_remaining": 4 }

// Response (invalid):
{ "valid": false, "error": "License not found" }

Example: Activate License

POST https://yoursite.com/wp-json/ree/v1/license/activate
Content-Type: application/json

{
  "license_key": "ABCDE-FGHJK-MNPQR-STUVW",
  "domain": "myclient.com"
}

Admin License Management

Go to Ree → Licenses to see all issued licenses. You can:

• Search by email, license key, or product key
• Revoke a license (immediately blocks all activations)
• Resend the purchase receipt email (re-delivers the download link and license key)

---

8. Shopping Cart (Mixed Checkout)

The Ree cart lets customers add multiple products (and/or add-ons) before checking out in a single Stripe session.

Cart Shortcodes

• Add to Cart — Add to Cart button. If the product has variants, renders a dropdown selector.

• Your cart is empty.

  Browse Plans
  — Renders the cart widget showing line items, totals, and checkout button.
• — Skip the cart; go straight to Stripe Checkout for a single product.

Mixed Cart (Products + Subscriptions)

If a customer adds both one-time products and a subscription plan, Ree handles both in one checkout using Stripe’s invoice item + subscription flow.

Cart Flow

1. Customer adds products via shortcode buttons
2. Cart state is stored in a browser cookie / local storage
3. Customer clicks Checkout in the

   Your cart is empty.

   Browse Plans
   widget
4. Ree creates a Stripe Checkout Session with all items
5. Customer pays on Stripe’s hosted page
6. On success, Ree receives the webhook, creates order records, generates download tokens and license keys, and emails the receipt

---

9. Usage & Metered Billing

Ree tracks per-user credits and usage for usage-based billing models (AI tokens, API calls, SMS messages, data transfer, etc.).

Meters

A meter is a named counter, e.g. ai_credits. Each meter has a unit label and can be linked to a Stripe Billing Meter for automatic usage-based invoicing.

Usage Reporting API

Your application reports usage via:

POST https://yoursite.com/wp-json/ree/v1/usage/report
X-Ree-Api-Key: your_api_key
Content-Type: application/json

{
  "user_id": 42,
  "meter": "ai_credits",
  "quantity": 150,
  "description": "GPT-4o API call",
  "idempotency_key": "unique-key-123"
}

API Key

Generate a REST API key under Ree → Settings → REST API Key. Rotate it at any time — the old key is immediately invalidated.

Customer-Facing Widgets

• — shows the logged-in user’s current balance for a meter
• — shows the logged-in user’s usage history (date, description, quantity used)

Admin Usage View

Go to Ree → Usage to see usage events across all users, filterable by meter and user.

---

10. Customer Portal

Logged-in customers can manage their own subscriptions via the Stripe Customer Portal.

Setup

1. In your Stripe Dashboard, go to Settings → Billing → Customer portal and configure what customers can do (cancel, update card, download invoices, etc.)
2. Add Manage Subscription shortcode or link to /ree-account anywhere on your site

How It Works

• Unauthenticated users are redirected to the WordPress login page, then back to the portal
• Authenticated users with a Stripe customer ID are redirected to a one-time portal session URL
• Users with no subscription see a friendly “no subscription” page

Portal URL

The portal is accessible at /ree-account on your WordPress site. No page needs to be created — Ree handles the route natively.

---

11. Email Notifications

Ree sends five transactional emails automatically. All are sent from the name and address configured in Ree → Settings → Emails.

Email	Trigger	Content
Welcome	New subscription created	Welcome message + plan name
Purchase Receipt	One-time payment completed	Order summary + Download Now button + license key(s)
Payment Failed	Invoice payment fails (3 escalating)	Update card CTA, attempt number
Cancellation	Subscription cancelled	Confirmation + plan name
Renewal Reminder	Manual trigger via do_action	Upcoming renewal notice

Configuring From Name / Email

1. Go to Ree → Settings → Emails
2. Set From Name (defaults to site name)
3. Set From Email (defaults to WordPress admin email)
4. Click Save Settings

---

12. Payment Gateways

Ree uses a driver-based payment gateway architecture. Stripe is built in; additional gateways can be registered by any plugin or theme.

Selecting the Active Gateway

1. Go to Ree → Settings → Gateway
2. Click the radio button for the gateway you want to use
3. Fill in the credentials for that gateway
4. Click Test [Gateway] Connection to verify
5. Click Save Settings

Stripe Setup

Field	Where to find it
Secret Key	Stripe Dashboard → Developers → API Keys → Secret key
Publishable Key	Stripe Dashboard → Developers → API Keys → Publishable key
Webhook Secret	Stripe Dashboard → Webhooks → your endpoint → Signing secret

Adding a Custom Gateway

Register a custom gateway driver via the ree_payment_gateways filter:

add_filter( 'ree_payment_gateways', function( $gateways ) {
    $gateways[] = new My_Gateway_Paypal();
    return $gateways;
} );

Your driver must extend Ree_Gateway and implement: id(), name(), settings_fields(), test_connection(), create_customer(), create_checkout_session(), and verify_webhook(). Once registered, the gateway appears in Settings automatically.

Feature Flags

Gateways declare what they support via supported_features(). Call Ree_Gateways::active()->supports('portal') before using optional features like the billing portal or metered billing.

---

13. Webhooks

Ree’s webhook endpoint is at:

https://yoursite.com/wp-json/ree/v1/webhook

All incoming webhooks are:

1. Signature-verified using your Webhook Secret
2. Logged to the database (viewable at Ree → Webhooks)
3. Processed to update subscription/order status, trigger emails, etc.

Webhook Log

Go to Ree → Webhooks to see the last 200 incoming events with: event type, Stripe event ID, subscription ID, status, and timestamp. Useful for debugging failed payments or missing order records.

---

14. REST API

Ree exposes a REST API for external integrations.

Authentication

Generate an API key under Ree → Settings → REST API Key. Send it as a header:

X-Ree-Api-Key: reekey_your_key_here

Endpoints

Endpoint	Auth	Description
POST /ree/v1/usage/report	API Key	Record usage event for a user/meter
POST /ree/v1/test-connection	WP Nonce	Test active gateway credentials
POST /ree/v1/license/check	Public	Validate a license key
POST /ree/v1/license/activate	Public	Activate license on a domain
POST /ree/v1/license/deactivate	Public	Deactivate license from a domain
POST /ree/v1/webhook	Signature	Incoming payment gateway webhooks

---

15. Shortcodes Reference

Shortcode	Attributes	Output
	plan (required), label, class	Subscribe button → Stripe Checkout
Manage Subscription	label, class	Link to /ree-account (billing portal)
No plans configured yet.	none	Pricing grid of all active plans
⬇ Download Ree — Free Enter your name and email to get the download link instantly. No spam, ever — just the occasional Ree update. Your name Email address ⬇ Send me the download link By downloading you agree to the MIT license. We'll send occasional Ree updates — unsubscribe anytime.	none	Free plugin/file download form (email-gated)
	product (required), label, class	Add to Cart button (or variant selector + button)
Your cart is empty. Browse Plans	none	Cart widget with line items + checkout button
	product (required), label, class	Direct checkout button (bypasses cart)
	meter (required)	Current usage balance for logged-in user
	meter (required)	Usage history table for logged-in user

Examples

Start Free Trial

Manage Billing


		
			Buy Now — $49
		

---

16. Admin Dashboard

Access the full Ree admin at WordPress Admin → Ree.

Page	What You See
Dashboard	MRR, active subscriptions, one-time revenue, total orders — with 6-month charts
Subscriptions	All subscriptions: email, plan, amount, status, period end, Stripe link
Orders	One-time purchases: email, products, amount, status, Stripe PI link
Licenses	All license keys: revoke / resend per key, search by email/key/product
Products	CRUD for one-time products including download + license settings
Variants	Per-product variant management
Bundles	Bundle definitions (multiple products as one)
Add-ons	Optional add-on definitions for cart checkout
Plans	Subscription plan CRUD
Usage	Usage events by meter and user
Webhooks	Incoming webhook event log
Settings	Gateway credentials, email from name/email, debug log toggle, REST API key

---

17. Developer Hooks & Filters

Action Hooks

Hook	Arguments	Fires when
ree_subscription_created	$sub_id, $user_id, $email	New subscription confirmed
ree_subscription_updated	$sub_id	Subscription updated
ree_subscription_cancelled	$sub_id, $record	Subscription cancelled
ree_subscription_paused	$sub_id	Subscription paused
ree_subscription_resumed	$sub_id	Subscription resumed
ree_invoice_paid	$sub_id, $sub_record	Invoice paid successfully
ree_payment_failed	$sub_id, $email, $attempt	Payment attempt failed
ree_order_created	$payment_intent_id, $user_id, $email	One-time order confirmed

Filter Hooks

Filter	Usage
ree_payment_gateways	Add custom gateway drivers ($gateways[] = new My_Driver(); return $gateways;)

Example: Grant Access on Subscription Created

add_action( 'ree_subscription_created', function( $sub_id, $user_id, $email ) {
    if ( $user_id ) {
        // Add a WordPress user role or meta when subscription starts
        $user = new WP_User( $user_id );
        $user->add_role( 'subscriber_pro' );
    }
}, 10, 3 );

add_action( 'ree_subscription_cancelled', function( $sub_id, $record ) {
    if ( $record && $record->user_id ) {
        $user = new WP_User( $record->user_id );
        $user->remove_role( 'subscriber_pro' );
    }
}, 10, 2 );

---

What’s Coming Next

Ree is being extended into a universal billing platform supporting utility services (Electric, Water, Gas), pest control, insurance, gyms, HOA, lawn care, ISPs, solar, and security monitoring. Upcoming features being released daily include:

• Service Type Config — configure Ree as a utility, SaaS, pest control, or insurance platform and get type-specific UI
• Invoice Line Item Engine — fully configurable billing line items with tax and late fee support
• Meter Read Entry + Import — for electric, water, gas billing
• Tiered Rate Engine — inclining/declining block rates, seasonal switching
• PDF Invoice Generation
• Customer Billing History Portal
• CSV Export

Follow the release log at ideauseful.com or check the changelog in the plugin settings.