User Guide

1. Introduction

Jscriptz Subscriptions adds Subscribe & Save functionality to your Magento 2 store, enabling customers to purchase products on a recurring basis. The module integrates seamlessly with Stripe for payment processing and provides a complete customer self-service portal.

Key Features

Requirements

• Magento 2.4.x (Open Source or Commerce)
• PHP 8.1 or higher
• Stripe_Payments module (for payment processing)
• Jscriptz_Checkout module (optional, for enhanced checkout integration)
• Stripe account with Subscriptions enabled

2. Installation

Prerequisites

• Magento 2.4.4 or higher
• PHP 8.1 or higher
• Composer 2.x
• Stripe account (for payment processing)
• Valid Jscriptz license (purchased from mage.jscriptz.com)

Step 1: Get Your Composer Access Token

After purchasing the extension, log in to your Jscriptz account to get your Composer authentication token:

1. Go to mage.jscriptz.com/customer/account
2. Click on GitHub Access in the left sidebar
3. Click Generate New Token if you don't have one
4. Copy your access token (valid for 50 minutes)

Step 2: Configure Composer Authentication

Create or update your auth.json file in your Magento root directory:

{
    "http-basic": {
        "packages.jscriptz.com": {
            "username": "YOUR_LICENSE_KEY",
            "password": "YOUR_ACCESS_TOKEN"
        }
    }
}

Replace YOUR_LICENSE_KEY with your license key from the My Licenses page, and YOUR_ACCESS_TOKEN with the token from Step 1.

Step 3: Install via Composer

# Add the Jscriptz repository (first time only)
composer config repositories.jscriptz composer https://packages.jscriptz.com

# Install the Subscriptions module
composer require jscriptz/module-subscriptions

Step 4: Run Magento Setup

# Enable the module
bin/magento module:enable Jscriptz_Subscriptions

# Run setup upgrade
bin/magento setup:upgrade

# Compile DI (production mode)
bin/magento setup:di:compile

# Deploy static content (production mode)
bin/magento setup:static-content:deploy -f

# Clear cache
bin/magento cache:flush

Step 5: Activate Your License

After installation, activate your license in the Magento admin:

1. Go to Stores → Configuration → Jscriptz → Subscriptions
2. Expand the License section
3. Enter your License Key from your Jscriptz License Account
4. Click Save Config
5. Click Verify License to confirm activation

3. Admin Configuration

3.1 General Settings

3.2 Display Settings

3.3 Customer Options

3.4 Stripe Integration

4. Subscription Plans

Subscription plans define the billing frequency, discounts, and trial periods available to customers.

4.1 Creating Plans

1. Navigate to Marketing > Subscriptions > Subscription Plans
2. Click Add New Plan
3. Fill in the plan details (see configuration below)
4. Save the plan

4.2 Plan Configuration

4.3 Frequency Options

4.4 Trials & Discounts

5. Product Configuration

Enable subscriptions on a per-product basis and assign available plans.

Enabling Subscriptions for a Product

1. Edit the product in Catalog > Products
2. Navigate to the Subscriptions tab
3. Set Enable Subscription to Yes
4. Select the available Subscription Plans for this product
5. Optionally configure product-specific discount overrides
6. Save the product

Product Subscription Fields

6. Visual Themes

The Subscribe & Save widget supports 6 pre-built visual themes, each with full customization options.

6.1 Available Themes

6.2 Theme Customization

Each theme can be customized using the visual editor in admin configuration:

Background Options

• Type: Gradient, Solid, or Transparent
• Solid Color: Hex color value
• Gradient Type: Linear or Radial
• Gradient Angle: Direction in degrees
• Gradient Stops: Color positions

Border Options

• Style: None, Solid, Dashed, Dotted, Gradient, Glow
• Width: Border thickness in pixels
• Color: Border color
• Radius: Corner roundness

Typography Options

• Font Color: Main text color
• Accent Color: Highlight color for "Save" text and prices
• Font Size: Base font size

Animation Options

• Icon Animation: Bounce, Pulse, Wiggle, or None
• Hover Animation: Scale, Glow, Lift, or None

Layout Options

• Scale: Widget size (50%-150%)
• Show Icon: Display theme icon
• Show Discount Badge: Display discount percentage badge
• Show Original Price: Show crossed-out original price
• Show Frequency Dropdown: Display frequency selector

Toggle Options

• Type: Switch, Checkbox, or Radio
• Background Color: Active state color
• Border Radius: Toggle corner roundness

7. Customer Experience

7.1 Product Page Widget

When a product has subscriptions enabled, customers see the Subscribe & Save widget on the product page (and optionally in the cart).

Widget Elements

• One-Time Purchase: Radio button for single purchase
• Subscribe & Save: Radio button to enable subscription
• Frequency Selector: Dropdown to choose delivery frequency
• Discount Display: Shows savings amount (e.g., "Save 10%")
• Price Comparison: Original price vs. subscription price

7.2 My Subscriptions Dashboard

Logged-in customers can view and manage all their subscriptions from their account dashboard.

Dashboard Features

• List of all active, paused, and cancelled subscriptions
• Subscription details (products, frequency, next billing date)
• Subscription increment ID (e.g., SUB-000001)
• Status indicators (Active, Paused, Cancelled, etc.)
• Action buttons for each subscription

7.3 Customer Actions

Subscription Statuses

8. GraphQL API

The module provides a complete GraphQL API for headless implementations and custom frontends.

8.1 Queries

subscriptionThemeConfig

Get the subscription theme configuration including customizations.

{
  subscriptionThemeConfig {
    enabled
    theme
    display_position
    show_savings
    price_location
    custom_css
    customization {
      background { type solid_color gradient_type }
      border { style width color radius }
      typography { font_color accent_color font_size }
      animations { icon_enabled icon_type hover_enabled hover_type }
      layout { scale show_icon show_discount_badge }
      toggle { type bg_color border_radius }
    }
  }
}

customer.subscriptions

Get the logged-in customer's subscriptions.

{
  customer {
    subscriptions(status: "active") {
      subscription_id
      increment_id
      status
      status_label
      plan { name billing_frequency discount_value }
      items { name sku qty subscription_price { value currency } }
      next_billing_date
      recurring_amount { value currency }
      can_pause
      can_skip
      can_cancel
    }
  }
}

8.2 Mutations

Example: Set Cart Item Subscription

mutation {
  setCartItemSubscription(
    cart_id: "abc123"
    cart_item_id: 5
    enabled: true
    plan_id: 1
  ) {
    success
    message
    cart {
      items {
        id
        subscription {
          enabled
          plan { name discount_value }
          subscription_price { value currency }
        }
      }
    }
  }
}

Example: Cancel Subscription

mutation {
  cancelSubscription(
    subscription_id: 123
    reason: "No longer needed"
    at_period_end: true
  ) {
    success
    message
    subscription {
      status
      end_date
    }
  }
}

8.3 Types

CartItemInterface Extensions

Cart items include subscription data:

• subscription_options - Available subscription plans for the product
• subscription - Current subscription configuration for the item

Key Types

9. Email Templates

The module includes 7 email templates for subscription lifecycle events. All templates can be customized in Marketing > Email Templates.

Customizing Email Templates

1. Go to Marketing > Email Templates
2. Click Add New Template
3. Load the default template from the dropdown
4. Customize the content
5. Save and assign in Stores > Configuration > Jscriptz > Subscriptions

Available Template Variables

• {{var subscription.increment_id}} - Subscription ID
• {{var subscription.status}} - Current status
• {{var subscription.next_billing_date}} - Next billing date
• {{var subscription.recurring_amount}} - Recurring amount
• {{var customer.name}} - Customer name
• {{var plan.name}} - Plan name
• {{var items}} - Subscription items collection

10. Stripe Integration

Subscriptions are powered by Stripe Subscriptions for secure, reliable recurring billing.

Setup Requirements

1. Install and configure the Stripe_Payments module
2. Enable Stripe in Magento payment configuration
3. Create a webhook endpoint in Stripe Dashboard
4. Configure the webhook signing secret in module settings

Webhook Configuration

Required Webhook Events

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• invoice.upcoming

Stripe Data Sync

The module syncs the following data with Stripe:

11. Cron Jobs

The module includes 3 scheduled cron jobs for automated subscription management.

Manual Execution

Cron jobs can be run manually using:

bin/magento cron:run --group=default

Or run a specific job:

bin/magento indexer:reindex jscriptz_subscriptions_sync_status

12. Database Schema

The module creates 6 custom tables and extends 2 core Magento tables.

Custom Tables

Extended Core Tables

13. Troubleshooting

Common Issues

Subscription widget not appearing

• Verify subscriptions are enabled in configuration
• Check that the product has subscriptions enabled
• Confirm at least one plan is assigned to the product
• Clear cache: bin/magento cache:clean

Webhooks not processing

• Verify the webhook URL is correct in Stripe Dashboard
• Check that the webhook signing secret is configured
• Review var/log/system.log for webhook errors
• Test webhook delivery from Stripe Dashboard

Subscription status not syncing

• Verify cron is running: bin/magento cron:run
• Check Stripe API credentials are correct
• Review var/log/exception.log for errors
• Manually run sync: bin/magento cron:run --group=default

Payment method update failing

• Ensure Stripe.js is loading on the frontend
• Check browser console for JavaScript errors
• Verify the SetupIntent is being created successfully

Debug Logging

Enable debug logging for detailed troubleshooting:

# View subscription-related logs
tail -f var/log/system.log | grep -i subscription

# View all errors
tail -f var/log/exception.log

Cache Management

After configuration changes, clear relevant caches:

# Clear all caches
bin/magento cache:clean

# Clear specific caches
bin/magento cache:clean config full_page

Support

For additional support:

• Check the module's GitHub repository for known issues
• Review Stripe documentation for API-related issues
• Contact Jscriptz support with detailed error logs