Entitlements System

The entitlements system manages the gifts for premium subscribers. It tracks and handles allocation, selection and redemption of the gifts.

Overview

When a premium subscription is purchased or renewed, an entitlement is assigned to the subscription. Additionally, a portion of the money paid is allocated as a deferred amount for the entitlement. When the entitlement is redeemed, the money is earned, and recorded as earned income on the entitlement.

Entitlements are designed to run on an annual cycle, with a new gift being introduced each year.

Core Concepts

Entitlements

An entitlement represents a redeemable benefit associated with a premium subscription. Each entitlement has:

  • Entitlement Number: A unique identifier indicating which annual cycle the entitlement applies to
  • Deferred Amount: The monetary value held in reserve
  • Earned Income: The realized value after redemption
  • Status: Can be either redeemed or unredeemed
  • Associated Order: Links to the original order created to redeem the entitlement
  • Redemption Details: Tracks when and how the entitlement was used

Premium Gifts

  • Each entitlement is typically associated with a premium gift
  • Gifts can be predefined products or custom variations
  • Gifts are managed through a journal_premium_gift data store

Key Features

Entitlement Management

  1. Creation
    • Entitlements are created when premium subscriptions are purchased or renewed
    • Each entitlement is assigned a unique ID and entitlement number
    • Deferred amounts are recorded at creation
  2. Tracking
    • System maintains complete history of entitlements
    • Tracks both unredeemed and redeemed benefits
    • Records all associated order information
  3. Admin Redemption Options
    • Standard redemption for predefined gifts
    • Custom redemption with manual order ID and notes
    • Ability to modify entitlement numbers
    • Option to delete entitlements if needed

Financial Tracking

  • Deferred Amount: Value reserved for future redemption
  • Earned Income: Value realized after redemption
  • Order Tracking: Full integration with the order system

Circulation Management User Interface

The system provides a comprehensive interface for managing entitlements:

  1. List View
    • Displays all entitlements for a subscription
    • Shows status (redeemed/unredeemed)
    • Provides financial information
  2. Management Actions
    • Process redemptions
    • Change entitlement numbers
    • Handle custom redemptions
    • Delete entitlements if necessary

Technical Implementation

Data Structure

Each entitlement record includes:

  • ID
  • Entitlement number
  • Order information
  • Financial data
  • Redemption status and details
  • Associated gift information

Integration Points

  • WordPress core functionality
  • WooCommerce order system
  • Custom premium gift management
  • Subscription management system

Security

The system implements several security measures:

  • Nonce verification for all actions
  • Order validation
  • Access control based on user permissions
  • Secure handling of financial data