Jscriptz Checkout

1. Introduction

Jscriptz Checkout is a complete replacement for Magento's default checkout, designed specifically for Hyva Theme compatibility. It provides a modern, reactive checkout experience using Alpine.js instead of Knockout.js, with all cart operations handled via GraphQL.

System Requirements

2. Installation

Follow these steps to install and configure Jscriptz Checkout.

Prerequisites

• Magento 2.4.4 or higher
• PHP 8.1 or higher
• Composer 2.x
• Node.js 16+ (for Tailwind CSS build)
• 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 Checkout module
composer require jscriptz/module-checkout

Step 4: Run Magento Setup

# Enable the module
bin/magento module:enable Jscriptz_Checkout

# 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 → Jscriptz Checkout
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

Tailwind CSS Build (Optional)

The module includes its own Tailwind CSS build system for styling customization. If you want to customize styles:

# Navigate to the tailwind directory
cd app/code/Jscriptz/Checkout/view/frontend/tailwind

# Install dependencies
npm install

# Development build with watch mode
npm run dev

# Production build (minified)
npm run build

3. Global Configuration

Configure the global checkout behavior. These settings control the overall checkout experience across your store.

3.1 General Settings

3.2 Display Settings

Display Settings configuration showing checkout mode and layout options

3.3 Progress Bar

The progress bar provides visual feedback on checkout completion status.

Progress bar showing step numbers, labels, and completion status

3.4 Express Payments

Configure express payment options like Apple Pay and Google Pay.

Express payment method configuration options

3.5 Smart Shipping Display

Smart shipping features help customers choose the best shipping option with visual badges and countdown timers.

Shipping cutoff countdown showing time remaining for same-day shipping

3.6 Gift Options

Enable gift wrapping, gift messages, and gift receipts for your checkout.

3.7 Trust & Security Badges

Display trust badges to increase customer confidence during checkout.

4. Checkout Builder

The Checkout Builder is a powerful visual interface for designing your checkout layout. Drag and drop steps, resize columns, and customize every aspect of the checkout experience.

4.1 Overview & Layout

The builder interface consists of:

• Toolbar - Store selector, device type, templates, and save actions
• Sidebar - Fields and Design Components tabs for drag-and-drop
• Canvas - Visual representation of the checkout layout with rows and columns
• Modals - Step editing, template management, and component configuration

Checkout Builder main interface showing toolbar, sidebar, and layout canvas

4.2 Store & Device Selection

Configure different layouts for different stores and device types.

Device type switcher for Desktop, Tablet, and Mobile layouts

4.3 Layout Templates

Save and load checkout layouts as templates for quick configuration.

• System Templates - Pre-built layouts (2-Column, 3-Column, etc.)
• Custom Templates - Save your own layouts for reuse
• Load Template - Apply a template to the current store/device
• Delete Template - Remove saved custom templates

Template selection dropdown with system and custom templates

4.4 Row Management

The checkout layout uses a row/column grid system. Each row can contain 1-4 columns.

Column count selection dropdown for configuring row layouts

4.5 Column Resize

Resize columns by dragging the handle between them. Column widths are saved as percentages.

Column resize handle for adjusting column widths

Result after resizing columns to custom widths

4.6 Step Management

Manage checkout steps including adding, editing, reordering, and grouping.

Step Properties

Step edit modal showing all step properties

4.7 Design Components

Add visual elements to enhance your checkout layout.

Design Components tab showing available components for drag-and-drop

4.8 Fields Tab

The Fields tab shows all available fields that can be dragged to checkout steps.

• System Fields - Core checkout fields (email, address fields, etc.)
• Custom Fields - User-created fields from the Checkout Fields admin
• Search - Filter fields by name

Fields tab showing system and custom fields available for placement

5. Custom Checkout Fields

Create custom fields to collect additional information during checkout. Fields can be displayed in orders, invoices, shipments, and emails.

Checkout Fields listing showing all configured custom fields

5.1 Field Types

5.2 Creating Fields

To create a new field, click "Add New Field" and configure the following:

Field edit form showing general settings and field type selection

5.3 Field Properties

5.4 Display Settings

Control where custom field values are displayed after checkout.

Field display settings controlling where values appear

5.5 Visibility Conditions

Show or hide fields based on dynamic conditions. Supports 8 condition types:

All 8 visibility condition types for dynamic field display

5.6 Fee/Discount Fields

Create fields that add fees or discounts to the order total.

6. Checkout Steps

The checkout process consists of several steps that can be customized via the Checkout Builder.

6.1 Contact Information

The first step collects the customer's email address and handles authentication.

• Email Input - Required email address field
• Email Existence Check - Real-time check if email exists in system
• Login Option - Password field for existing customers
• Create Account - Option to create account with purchase

Email existence check detecting an existing customer account

6.2 Shipping Address

Collect shipping address with support for saved addresses and autocomplete.

• Saved Addresses - Logged-in customers can select saved addresses
• Address Autocomplete - Google Places API integration (optional)
• Field Validation - Required field validation

6.3 Billing Address

• Same as Shipping - Toggle to use shipping address
• Separate Billing - Enter different billing address
• VAT ID Field - Optional VAT ID for B2B customers

6.4 Shipping Method

Display available shipping methods with smart badges and pricing.

Shipping method selection with smart badges

6.5 Payment Method

Supported payment method integrations:

6.6 Order Summary

Displays cart contents, totals, and allows coupon/gift card entry.

• Cart Items - Expandable list with quantity adjustment
• Subtotal - Cart subtotal before shipping/tax
• Shipping - Selected shipping cost
• Tax - Calculated taxes
• Grand Total - Final order total
• Coupon Code - Apply discount codes
• Gift Card - Apply gift card balances

Enhanced order summary with expandable items and totals

6.7 Gift Options

Optional gift options for the order.

Gift options section with wrapping, message, and receipt options

7. Customer Experience

7.1 Email Existence Check

When a customer enters their email, the system checks if an account exists. If found, a login option is displayed.

7.2 Login for Existing Customers

Existing customers can log in during checkout to access:

• Saved addresses
• Saved payment methods
• Order history
• Reward points/store credit

Sign in button enabled after password entry

7.3 Guest Checkout

Customers can complete checkout without creating an account.

7.4 Account Creation

Options for account creation:

• Before Order - Create account during checkout
• After Order - Option shown on success page
• Password Field - Set password when creating account

7.5 Multi-Step Wizard Mode

Alternative to one-page checkout, displaying one step at a time with Previous/Next navigation.

Multi-step checkout showing step-by-step navigation

8. Social Login New

Allow customers to sign in or create accounts using their existing social media accounts. This simplifies the checkout process and increases conversion by reducing friction.

8.1 Overview

Social Login enables customers to authenticate using their existing social accounts during checkout. Benefits include:

8.2 Supported Providers

8.3 Google Setup

To enable Google Sign-In, you need to create OAuth 2.0 credentials in the Google Cloud Console.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" at the top, then "New Project"
3. Enter a project name (e.g., "My Store Social Login")
4. Click "Create"

Step 2: Configure OAuth Consent Screen

1. In the Google Cloud Console, go to APIs & Services → OAuth consent screen
2. Select External user type (or Internal if using Google Workspace)
3. Fill in the required fields:
   • App name: Your store name
   • User support email: Your email address
   • Developer contact: Your email address
4. Add scopes: email, profile, openid
5. Save and continue through the remaining steps

Step 3: Create OAuth Client ID

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Web application as the application type
4. Enter a name (e.g., "Magento Social Login")
5. Add Authorized JavaScript origins:

   https://your-store.com

6. Add Authorized redirect URIs:

   https://your-store.com/jscriptz_checkout/sociallogin/callback/provider/google

7. Click Create

Step 4: Publish the App (Production)

For production use, you need to publish your OAuth consent screen:

1. Go to OAuth consent screen
2. Click Publish App
3. If your app requests sensitive scopes, you may need to submit for Google verification

8.4 LinkedIn Setup

To enable LinkedIn Sign-In, you need to create an application in the LinkedIn Developer Portal.

Step 1: Create a LinkedIn App

1. Go to LinkedIn Developer Portal
2. Click Create app
3. Fill in the required fields:
   • App name: Your store name
   • LinkedIn Page: Select your company page (or create one)
   • Privacy policy URL: Your store's privacy policy URL
   • App logo: Upload your store logo (100x100px minimum)
4. Accept the terms and click Create app

LinkedIn Developer Portal - Create App form with required fields

Step 2: Request Sign In with LinkedIn using OpenID Connect

1. In your app's settings, go to the Products tab
2. Find Sign In with LinkedIn using OpenID Connect
3. Click Request access
4. Accept the terms to enable the product

LinkedIn Products tab showing Sign In with LinkedIn using OpenID Connect

Step 3: Configure OAuth 2.0 Settings

1. Go to the Auth tab in your app
2. Add the following Authorized redirect URL:

   https://your-store.com/jscriptz_checkout/sociallogin/callback/provider/linkedin

3. Copy your Client ID and Client Secret from this page

LinkedIn Auth tab showing Client ID, Client Secret, and redirect URLs

8.5 Facebook Setup

To enable Facebook Login, you need to create an application in the Facebook Developer Portal.

Step 1: Create a Facebook App

1. Go to Facebook Developers
2. Click My Apps in the top right corner
3. Click Create App
4. Select Consumer as the app type
5. Enter your app name (e.g., "Your Store Checkout") and contact email
6. Click Create App

Step 2: Add Facebook Login Product

1. In your app dashboard, click Add Product in the left sidebar
2. Find Facebook Login and click Set Up
3. Skip the quickstart wizard - we'll configure manually

Step 3: Configure Facebook Login Settings

1. In the left sidebar, go to Facebook Login → Settings
2. Configure the OAuth settings:
   • Client OAuth Login: Yes
   • Web OAuth Login: Yes
   • Enforce HTTPS: Yes
3. Add the following Valid OAuth Redirect URI:

   https://your-store.com/jscriptz_checkout/sociallogin/popupcallback/provider/facebook/

4. Click Save Changes

https://your-store.com/subcats/jscriptz_checkout/sociallogin/popupcallback/provider/facebook/

Step 4: Get App Credentials

1. In the left sidebar, go to Settings → Basic
2. Copy your App ID (visible at top)
3. Click Show next to App Secret and copy it

Step 5: App Review (Production)

For production use with real customers:

1. Go to App Review in the left sidebar
2. Click Permissions and Features
3. Request email permission (usually auto-approved)
4. Submit for review

8.6 Apple Setup

To enable Sign in with Apple, you need an Apple Developer Program membership ($99/year) and must configure several identifiers and keys.

Step 1: Enroll in Apple Developer Program

1. Go to Apple Developer Program
2. Click Enroll
3. Sign in with your Apple ID (or create one)
4. Complete the enrollment process ($99/year)
5. Wait for enrollment approval (can take up to 48 hours)

Step 2: Create an App ID

1. Go to Certificates, Identifiers & Profiles
2. Click Identifiers in the sidebar
3. Click the + button to create a new identifier
4. Select App IDs and click Continue
5. Select App type and click Continue
6. Fill in the details:
   • Description: Your store name (e.g., "My Store")
   • Bundle ID: Explicit, use reverse domain (e.g., "com.yourstore.checkout")
7. Scroll down and check Sign In with Apple
8. Click Continue, then Register

Step 3: Create a Services ID

1. In Identifiers, click the + button again
2. Select Services IDs and click Continue
3. Fill in the details:
   • Description: Your store name
   • Identifier: A unique ID (e.g., "com.yourstore.signin")
4. Click Continue, then Register
5. Click on the newly created Services ID
6. Check Sign In with Apple and click Configure
7. Configure the web authentication:
   • Primary App ID: Select the App ID you created
   • Domains: your-store.com
   • Return URLs:

     https://your-store.com/jscriptz_checkout/sociallogin/popupcallback/provider/apple/

8. Click Save, then Continue, then Save

Step 4: Create a Sign In Key

1. Go to Keys in the sidebar
2. Click the + button to create a new key
3. Enter a Key Name (e.g., "Sign In with Apple Key")
4. Check Sign In with Apple
5. Click Configure next to Sign In with Apple
6. Select your Primary App ID and click Save
7. Click Continue, then Register
8. Important: Download the key file (.p8) immediately - you can only download it once!
9. Note the Key ID shown on the page

Step 5: Get Your Team ID

1. Go to Apple Developer Account
2. Your Team ID is shown in the top right corner of the Membership page, or in the URL when viewing identifiers

Step 6: Configure Magento Admin

In Magento admin, go to Stores → Configuration → JSCRIPTZ → Jscriptz Checkout → Social Login and expand the Apple section:

Apple-Specific Behaviors

• Name only on first login: Apple only provides the user's name on the very first authorization. Subsequent logins won't include name data.
• Private relay email: Users can choose to hide their email. In this case, Apple provides a private relay address (e.g., xyz123@privaterelay.appleid.com) that forwards to the user's real email.
• Two-factor authentication: Apple requires 2FA on all Apple IDs used for Sign in with Apple.

8.7 Magento Configuration

After setting up your OAuth provider(s), configure them in Magento admin.

General Settings

Provider Configuration

For each provider (Google, LinkedIn, etc.), configure:

https://your-store.com/jscriptz_checkout/sociallogin/callback/provider/[provider_code]

Login Page Integration

Social Login can also be displayed on the customer login page (/customer/account/login):

9. Order Processing

9.1 Order Success Page

After successful order placement, customers see a confirmation page with:

• Order number and confirmation
• Order summary details
• Option to create account (for guests)
• Continue shopping links

Order success page with confirmation details

9.2 Admin Order View

Custom field values are displayed in the admin order view when "Show in Order View" is enabled.

Custom fields displayed in admin order view

9.3 Invoice & Shipment Views

Custom fields appear on invoices and shipments when configured.

Custom fields displayed on invoice view

9.4 Order Emails

Custom fields are automatically included in order confirmation emails.

10. Mobile Experience

The checkout is fully responsive with mobile-specific features.

Mobile Features

• Responsive Layout - Tailwind breakpoints (sm/md/lg) for adaptive design
• Mobile Sticky Order Summary - Fixed bottom bar with expandable drawer
• Touch-Optimized Controls - Larger tap targets for mobile input
• Device-Specific Layouts - Configure unique layouts for mobile in Builder

Mobile checkout view with sticky order summary bar

11. Order Bumps (Upsells)

Add upsell products to the checkout to increase average order value.

Order Bump Features

12. Analytics Dashboard

Track checkout performance with built-in analytics.

Analytics dashboard showing conversion metrics and funnel

12.1 Conversion Funnel

Visualize checkout progression and identify drop-off points.

• Sessions per Step - How many sessions reached each step
• Drop-off Rates - Percentage abandoning at each step
• Completion Rate - Overall checkout completion percentage

12.2 Error Tracking

Monitor validation errors and payment failures.

• Top Errors - Most common error messages
• Error Count - Total occurrences per error
• Error Percentage - Relative frequency of each error

13. A/B Testing

Run split tests to optimize checkout conversion.

13.1 Creating Tests

A/B tests listing showing test status and results

13.2 Test Results

View test performance metrics including:

• Conversion rate per variant
• Revenue per variant
• Statistical significance
• Recommended winner

14. Abandoned Cart Recovery

Automatically recover abandoned carts with email campaigns.

Recovery Process

1. Detection - Hourly cron identifies abandoned sessions
2. Email 1 - Sent immediately after abandonment
3. Email 2 - Sent 6 hours later (configurable)
4. Email 3 - Sent 24 hours later (configurable)
5. Recovery - Token-based link restores cart for completion

Webhook Integration

Send abandoned cart data to third-party services (Klaviyo, Mailchimp, etc.) via webhooks.

15. VAT/Tax Integration

EU VAT ID validation and B2B tax exemption.

Features

16. Developer Reference

Adding Custom Fields via DI

Add custom fields programmatically in your module's etc/di.xml:

<type name="Jscriptz\Checkout\ViewModel\CustomFields">
    <arguments>
        <argument name="billingAddressFields" xsi:type="array">
            <item name="my_field" xsi:type="array">
                <item name="type" xsi:type="string">text</item>
                <item name="label" xsi:type="string">My Field</item>
                <item name="sortOrder" xsi:type="number">100</item>
            </item>
        </argument>
    </arguments>
</type>

GraphQL Mutations

Save Custom Fields

mutation {
  setJscriptzCheckoutFields(input: {
    cart_id: "masked_cart_id"
    fields: [
      { field_code: "my_field", value: "my_value" }
    ]
  }) {
    success
    message
  }
}

Track Analytics

mutation {
  trackCheckoutAnalytics(input: {
    session_token: "unique_token"
    event_type: "step_viewed"
    step_code: "shipping_address"
  }) {
    success
    session_token
  }
}

Email Template Variable

For custom email templates, add this variable to display custom fields:

{{var custom_checkout_fields_html|raw}}

CLI Commands

# Clear checkout-related caches
bin/magento cache:clean layout block_html full_page config

# Run setup after schema changes
bin/magento setup:upgrade

# Deploy static content
bin/magento setup:static-content:deploy -f

17. Troubleshooting

Common Issues

18. Quick Reference

Admin Menu Locations

Field Types Reference

Database Tables