Packages

Packages define the specific entitlement a member receives when they make a purchase from a campaign. Each package specifies what the member pays, what they get in return (minutes, wallet credit, or both), which devices the entitlement applies to, and how long the entitlement remains valid.

Package Types

Every package has two type fields that determine the nature of the entitlement:

Package Type

The package type defines the primary entitlement:

• Minutes: The member receives a block of prepaid minutes. The base amount represents the number of minutes included. When purchased, the system creates a time credit with this many minutes.
• Money: The member receives wallet credit. The base amount represents the amount in minor currency units (e.g., cents). When purchased, the system creates a wallet credit with this balance.

Bonus Type

The bonus type defines an optional secondary entitlement granted on top of the base:

• Minutes: The member receives bonus minutes. The bonus amount specifies how many extra minutes are granted. A separate time credit is created with the "Bonus" credit type.
• Money: The member receives bonus wallet credit. The bonus amount specifies the bonus amount in minor units. A separate wallet credit is created with the "Bonus" credit type.
• None: No bonus is included with this package. The member receives only the base entitlement.

Example Combinations

Purchase Price vs. Entitlement

The purchase price is the amount the member pays at the register (in minor currency units). This is independent of the base amount. The two values do not need to match.

For example:

• A package might cost 2000 minor units (purchase price) but grant 3000 minor units of wallet credit (base amount). The member effectively gets a 50% bonus built into the base price.
• A minutes package might cost 1500 minor units and grant 120 minutes. The "per-minute cost" is implicit and does not need to match the standard hourly rate.

This separation allows cafe owners to create value-added packages where the entitlement exceeds the payment, making packages more attractive than pay-as-you-go pricing.

Device Restriction

The device restriction controls which device types the entitlement can be used on:

The device restriction is inherited by all wallet credits and time credits created from this package.

Validity Period

Valid Days

The valid_days field sets the number of days the entitlement remains usable after purchase. When a member buys the package, the system calculates the expiration date as purchase_date + valid_days. After expiration, any remaining balance (minutes or wallet credit) in the associated lots is no longer usable.

If valid_days is not set, the entitlement does not expire.

Valid Days of Week

The valid days setting is an optional day selection that restricts which days of the week the entitlement can be consumed. This allows packages like "weekday-only" or "weekend-only" bundles. When valid days are configured, the system only deducts from the package's credits on qualifying days.

Wallet Category and Cross-Category Spend

Packages can assign a wallet category to the wallet credits they create. This tags the funds with a category label (e.g., "gaming", "general", "food") that restricts where the balance can be spent.

The cross-category spending option on the package controls whether the created credits allow spending outside their category:

• 0 (default): Funds are restricted to their designated category.
• 1: Funds can also be spent in other categories.

Member Discount Stacking

The member discount stacking option controls whether a member's tier discount applies on top of this package's pricing when the package's minutes or wallet credit are consumed:

• 0 (default): The member's tier discount does not stack. The package is treated as a fixed-value deal.
• 1: The member's tier discount is applied in addition to the package terms. This gives higher-tier members additional savings even when using prepaid packages.

How Packages Are Purchased and Fulfilled

When a package is purchased:

1. Payment collection: The purchase price is charged to the member (cash, card, or wallet deduction).
2. Purchase record: A purchase entry is created, recording the member, package, payment amount, and timestamps.
3. Credit creation: Based on the package configuration:
   • If the package type is money: a wallet credit is created with the base amount and the "Paid" credit type.
   • If the package type is minutes: a time credit is created with the base amount as minutes and the "Paid" credit type.
   • If the bonus type is money: an additional wallet credit is created with the bonus amount and the "Bonus" credit type.
   • If the bonus type is minutes: an additional time credit is created with the bonus amount as minutes and the "Bonus" credit type.
4. Restriction and expiry: All created credits inherit the package's device restriction and wallet category. Expiration is calculated from the validity period if set.
5. Tracking: The purchase record maintains running totals of consumed vs. entitled amounts for both paid and bonus portions, enabling accurate refund calculations if needed.

Creating a Package

To add a package to an existing campaign:

1. Open the campaign from the campaign list.
2. Click Add Package.
3. Configure the package type (minutes or money) and set the base amount.
4. Optionally configure the bonus type and bonus amount.
5. Set the purchase price (the amount the member will pay).
6. Choose the device restriction.
7. Optionally set valid days and valid days of week for time-limited offers.
8. Configure wallet category and cross-category spend if you use category-based wallet separation.
9. Set the member discount stacking preference.
10. Save the package.