SquareWooSync Pro – Loyalty Shortcodes Documentation #

Overview #

The Loyalty Shortcodes system provides 8 modular shortcodes to display Square loyalty program information anywhere on your WordPress site. All shortcodes are responsive, translation-ready, and easily customizable.

---

Available Shortcodes #

Shortcode	Description
[sws_loyalty_points]	Display current user’s points balance
[sws_loyalty_tier]	Show current tier/status
[sws_loyalty_progress]	Progress bar to next reward
[sws_loyalty_rewards]	List of available/upcoming rewards
[sws_loyalty_history]	Points transaction history (placeholder)
[sws_loyalty_earn_rate]	Display points earning rate
[sws_loyalty_widget]	Complete loyalty dashboard widget
[sws_loyalty_product_points]	Points earned for specific product

---

Basic Usage #

Quick Start #

Simply add any shortcode to your page, post, or widget area:

[sws_loyalty_points]

This will display: Points: 150 points

Adding to WordPress #

In Pages/Posts: #

1. Edit any page or post
2. Add a Shortcode block (Gutenberg) or paste directly (Classic Editor)
3. Enter the shortcode with desired attributes

In Widgets: #

1. Go to Appearance → Widgets
2. Add a Text or Shortcode widget
3. Paste the shortcode

In Theme Files: #

<?php echo do_shortcode(‘[sws_loyalty_points]’); ?>

---

Detailed Shortcode Reference #

1. Points Display – [sws_loyalty_points] #

Displays the current user’s loyalty points balance.

Attributes: – format – Display format (default: “simple”) – “simple” – Basic text display – “detailed” – Card-style with labels – “badge” – Compact badge style – class – Additional CSS classes – show_label – Show/hide “Points:” label (default: “true”)

Examples:

// Simple display
[sws_loyalty_points]
Output: Points: 150 points

// Badge style
[sws_loyalty_points format=”badge”]
Output: [150 points] (styled as badge)

// Detailed card
[sws_loyalty_points format=”detailed”]
Output: Card showing “Your Balance: 150 points”

// Without label
[sws_loyalty_points show_label=”false”]
Output: 150 points

// Custom CSS class
[sws_loyalty_points class=”my-custom-class”]

---

2. Tier Display – [sws_loyalty_tier] #

Shows the user’s current loyalty tier and progress to next tier.

Attributes: – show_next – Display next tier info (default: “true”) – class – Additional CSS classes

Examples:

// Show current and next tier
[sws_loyalty_tier]
Output: Current Tier: Silver
        50 points to Gold

// Current tier only
[sws_loyalty_tier show_next=”false”]
Output: Current Tier: Silver

---

3. Progress Bar – [sws_loyalty_progress] #

Visual progress bar showing advancement to next reward.

Attributes: – show_text – Show progress text (default: “true”) – height – Bar height in pixels (default: “25”) – class – Additional CSS classes – color – Progress bar color (default: “#2563eb”) – background – Background color (default: “#e5e7eb”)

Examples:

// Default progress bar
[sws_loyalty_progress]

// Custom colors and height
[sws_loyalty_progress color=”#10b981″ background=”#f3f4f6″ height=”30″]

// Without text label
[sws_loyalty_progress show_text=”false”]

// Custom styling
[sws_loyalty_progress class=”my-progress-bar” color=”#dc2626″]

---

4. Rewards List – [sws_loyalty_rewards] #

Displays available and upcoming rewards.

Attributes: – show_qualified – Show available rewards (default: “true”) – show_unqualified – Show locked rewards (default: “true”) – layout – Display layout (default: “list”) – “list” – Simple list view – “grid” – Grid layout – “cards” – Card-based layout – class – Additional CSS classes

Examples:

// Show all rewards as list
[sws_loyalty_rewards]

// Available rewards only in grid
[sws_loyalty_rewards show_unqualified=”false” layout=”grid”]

// Card layout for all rewards
[sws_loyalty_rewards layout=”cards”]

// Custom class
[sws_loyalty_rewards class=”rewards-section” layout=”list”]

---

5. Points History – [sws_loyalty_history] #

Placeholder for points transaction history (requires API extension).

Attributes: – limit – Number of transactions to show (default: “10”) – class – Additional CSS classes

Examples:

// Show last 10 transactions
[sws_loyalty_history]

// Show last 5 transactions
[sws_loyalty_history limit=”5″]

---

6. Earn Rate – [sws_loyalty_earn_rate] #

Displays how many points are earned per dollar spent.

Attributes: – format – Display format (default: “simple”) – “simple” – Inline text – “detailed” – Card with icon – class – Additional CSS classes

Examples:

// Simple inline display
[sws_loyalty_earn_rate]
Output: Earn 1 point per $1.00 spent

// Detailed card view
[sws_loyalty_earn_rate format=”detailed”]
Output: Card showing earn rate with icon

---

7. Complete Widget – [sws_loyalty_widget] #

Full loyalty dashboard combining multiple components.

Attributes: – title – Widget title (default: “Loyalty Program”) – show_points – Show points section (default: “true”) – show_progress – Show progress bar (default: “true”) – show_rewards – Show rewards list (default: “true”) – show_earn_rate – Show earn rate (default: “true”) – class – Additional CSS classes

Examples:

// Full widget with all sections
[sws_loyalty_widget]

// Custom title, hide earn rate
[sws_loyalty_widget title=”My Rewards” show_earn_rate=”false”]

// Points and progress only
[sws_loyalty_widget show_rewards=”false” show_earn_rate=”false”]

// No title
[sws_loyalty_widget title=””]

---

8. Product Points – [sws_loyalty_product_points] #

Shows points earned for a specific product.

Attributes: – product_id – WooCommerce product ID (optional, uses current product if empty) – format – Display format (default: “simple”) – “simple” – Basic text – “badge” – Badge style – “message” – Full message with login prompt – class – Additional CSS classes

Examples:

// Current product (on product page)
[sws_loyalty_product_points]
Output: Earn 25 points

// Specific product
[sws_loyalty_product_points product_id=”123″]

// Badge style
[sws_loyalty_product_points format=”badge”]
Output: [+25 points] (as badge)

// Message format
[sws_loyalty_product_points format=”message”]
Output: Earn 25 points with this purchase (or login prompt)

---

Styling & Customization #

CSS Structure #

The stylesheet (assets/styles/loyalty-shortcodes.css) uses simple, semantic class names:

/* Main color – change this to match your brand */
.sws-loyalty-points { color: #2563eb; }

/* Backgrounds */
.sws-loyalty-widget { background: white; }

/* Borders */
.sws-loyalty-widget { border: 1px solid #e5e7eb; }

Customization Guide #

1. Change Primary Color #

Find and replace all instances of #2563eb with your brand color:

/* Example: Change to green */
.sws-loyalty-points { color: #10b981; }
.sws-loyalty-badge { background: #10b981; }
.sws-progress-fill { background: #10b981; }

2. Adjust Spacing #

Modify padding and margins:

.sws-loyalty-widget { padding: 24px; } /* Increase padding */
.sws-widget-section { padding: 16px 0; } /* More space between sections */

3. Typography #

Change font sizes and weights:

.sws-loyalty-points-value {
    font-size: 48px; /* Larger points display */
    font-weight: 900; /* Bolder text */
}

4. Custom Theme Integration #

Add to your theme’s CSS:

/* Match your theme’s styling */
.sws-loyalty-widget {
    font-family: ‘Your Theme Font’, sans-serif;
    background: var(–theme-background);
    border-radius: var(–theme-border-radius);
}

Advanced Customization #

Override Specific Elements #

/* Custom progress bar */
.my-custom-progress .sws-progress-bar {
    height: 40px;
    border-radius: 20px;
}

.my-custom-progress .sws-progress-fill {
    background: linear-gradient(90deg, #3b82f6, #8b5cf6);
}

Responsive Adjustments #

/* Mobile-specific styling */
@media (max-width: 768px) {
    .sws-loyalty-widget {
        padding: 12px;
        font-size: 14px;
    }
   
    .sws-loyalty-points-value {
        font-size: 24px;
    }
}

---

Common Use Cases #

1. Account Page Dashboard #

Add to WooCommerce My Account page:

[sws_loyalty_widget title=”Your Rewards Dashboard”]

2. Product Page Integration #

Add below add-to-cart button:

[sws_loyalty_product_points format=”message”]

3. Header Points Display #

Add to header widget area:

[sws_loyalty_points format=”badge”]

4. Checkout Page Reminder #

Show points to be earned:

<div class=”checkout-loyalty”>
    <h3>Loyalty Rewards</h3>
    [sws_loyalty_earn_rate format=”detailed”]
    [sws_loyalty_progress show_text=”true”]
</div>

5. Sidebar Widget #

Create a compact loyalty widget:

<div class=”sidebar-loyalty”>
    [sws_loyalty_points format=”simple”]
    [sws_loyalty_tier show_next=”true”]
    [sws_loyalty_rewards show_unqualified=”false” layout=”list”]
</div>

6. Email Signature #

For email templates (if supported):

[sws_loyalty_points show_label=”true”]

---

Troubleshooting #

Shortcode Not Displaying #

Issue: Shortcode shows as plain text Solution: – Ensure Square loyalty program is enabled in settings – Check that user is logged in (for user-specific data) – Verify shortcode syntax is correct

No Data Showing #

Issue: Shortcode renders but shows no data Solution: – Verify Square API connection is active – Check user has Square customer ID linked – Ensure loyalty program has active rewards configured

Styling Issues #

Issue: Shortcodes don’t match theme Solution: 1. Check if loyalty-shortcodes.css is loading 2. Add custom CSS to override defaults 3. Use class attribute for specific targeting

Performance #

Issue: Slow loading Solution: – Data is cached per page load – Consider using widget instead of multiple shortcodes – Reduce number of shortcodes per page

Guest Users #

Issue: Non-logged-in users see login prompts Solution: This is expected behavior. Options: 1. Hide shortcodes for guests using conditional logic 2. Use is_user_logged_in() check in templates 3. Display earn rate info only (doesn’t require login)

---

Developer Notes #

Filters Available #

// Modify points display
add_filter(‘sws_loyalty_points_output’, function($output, $points) {
    return “You have {$points} awesome points!”;
}, 10, 2);

// Customize login prompt
add_filter(‘sws_loyalty_login_prompt’, function($html) {
    return ‘<div class=”custom-login”>Please login</div>’;
});

Conditional Display #

// Only show for logged-in users
<?php if (is_user_logged_in()): ?>
    <?php echo do_shortcode(‘[sws_loyalty_widget]’); ?>
<?php endif; ?>

// Show different content based on points
<?php
$user_id = get_current_user_id();
$square_id = get_user_meta($user_id, ‘square_customer_id’, true);
if ($square_id) {
    echo do_shortcode(‘[sws_loyalty_rewards]’);
} else {
    echo ‘Join our loyalty program!’;
}
?>

AJAX Integration #

The shortcodes use cached data. For real-time updates:

// Refresh loyalty data via AJAX
jQuery.ajax({
    url: ajax_object.ajax_url,
    data: {
        action: ‘fetch_loyalty_data’,
        nonce: loyalty_data.nonce
    },
    success: function(response) {
        // Update DOM with new data
    }
});

---

Support & Updates #

For issues or feature requests related to loyalty shortcodes: 1. Check the main SquareWooSync Pro documentation 2. Ensure you’re running the latest version 3. Contact support with specific shortcode and attribute details

Version: 1.0.0
Last Updated: 2024