WooCommerce Integration

The useLoyalty WooCommerce plugin connects your WordPress store to automatically award points for purchases and display loyalty features to customers.

Features

Points for Orders: Automatic points based on order value
My Account Tab: Points balance in WooCommerce account
Coupon Rewards: Generate WooCommerce coupons as rewards
Refund Handling: Automatic point deduction on refunds
Webhook Sync: Real-time order and customer sync
Product Multipliers: Bonus points for specific products

Requirements

WordPress 5.8+
WooCommerce 5.0+
PHP 7.4+
SSL certificate (HTTPS required)

Installation

1. Download Plugin

Download the useLoyalty WooCommerce plugin from your dashboard or the link provided.

2. Upload to WordPress

Go to Plugins → Add New → Upload Plugin
Select the useloyalty-woocommerce.zip file
Click Install Now
Click Activate

3. Connect to useLoyalty

Go to WooCommerce → useLoyalty
Enter your useLoyalty API URL
Enter your Private API Key
Click Connect

The plugin will:

Validate your API credentials
Register webhooks with your store
Create a project if needed
Generate a webhook secret

4. Configure Settings

Setting	Default	Description
Points per Dollar	1	Points earned per $1 spent
Rounding Mode	FLOOR	How to round points
Min Order Amount	None	Minimum order to earn points
Exclude Shipping	Yes	Don't count shipping
Exclude Tax	Yes	Don't count tax
Exclude Guest	Yes	Require account
Points On Status	completed	When to award points
Show in My Account	Yes	Display points tab

Webhook Configuration

The plugin registers these WooCommerce webhooks:

Topic	Trigger	Action
`order.updated`	Order status change	Award/refund points
`customer.created`	New customer	Create member
`customer.updated`	Customer update	Sync member data

Points Award Timing

Configure when points are awarded:

Status	Use Case
`completed`	Physical products (after delivery)
`processing`	Digital products (immediate)

// Default: Award on completed
'pointsOnStatus' => 'completed'

// Alternative: Award on processing
'pointsOnStatus' => 'processing'

Points Calculation

Formula

Eligible = Order Total [- Shipping] [- Tax]
Points = Eligible × Points per Dollar × Product Multiplier

Example

Order Total: $89.99
Shipping: $5.99
Tax: $7.20
Points per Dollar: 1

Eligible = $89.99 - $5.99 - $7.20 = $76.80
Points = floor(76.80 × 1) = 76 points

Product Multipliers

Set bonus earning rates for products:

{
  "productOverrides": {
    "123": { "multiplier": 2.0 },
    "456": { "multiplier": 1.5 }
  }
}

Products in the override list earn bonus points:

Regular Product: 100 × 1.0 = 100 points
2x Product: 100 × 2.0 = 200 points

My Account Integration

The plugin adds a "My Points" tab to WooCommerce My Account:

Features

Current points balance
Points history
Available rewards
Redemption interface

Template Customization

Override the template in your theme:

your-theme/
  woocommerce/
    myaccount/
      points-dashboard.php

Disable My Account Tab

// In your theme's functions.php
add_filter('useloyalty_show_points_in_account', '__return_false');

Or via plugin settings:

Uncheck "Show Points in My Account"

Coupon Rewards

Create rewards that generate WooCommerce coupons:

Setup in useLoyalty Dashboard

{
  "name": "15% Off Coupon",
  "type": "COUPON",
  "pointsCost": 500,
  "discountConfig": {
    "type": "PERCENTAGE",
    "value": 15
  }
}

Coupon Types

Type	Example	WooCommerce Type
Percentage	10% off	`percent`
Fixed Cart	$10 off cart	`fixed_cart`
Fixed Product	$5 off product	`fixed_product`

Generated Coupon Settings

Usage Limit: 1 per customer
Individual Use: Yes
Expiry: Configurable
Minimum Spend: Optional

API Reference

Connect Store

POST /api/woocommerce/connect

{
  "siteUrl": "https://mystore.com",
  "consumerKey": "ck_xxxxx",
  "consumerSecret": "cs_xxxxx",
  "organizationId": "org_123"
}

Disconnect Store

DELETE /api/woocommerce/connect

Get Store Settings

GET /api/woocommerce/stores/:id/settings

Update Settings

PATCH /api/woocommerce/stores/:id/settings

{
  "pointsPerDollar": 2,
  "excludeShipping": true,
  "excludeTax": true,
  "pointsOnStatus": "completed"
}

Create Coupon

POST /api/woocommerce/coupons

{
  "storeId": "store_123",
  "rewardClaimId": "claim_456",
  "discountType": "PERCENTAGE",
  "discountValue": 10
}

WordPress Hooks

Filters

// Modify points calculation
add_filter('useloyalty_calculate_points', function($points, $order) {
    // Custom logic
    return $points;
}, 10, 2);

// Filter eligible products
add_filter('useloyalty_eligible_products', function($products, $order) {
    // Exclude certain products
    return array_filter($products, function($product) {
        return $product->get_type() !== 'subscription';
    });
}, 10, 2);

Actions

// After points awarded
add_action('useloyalty_points_awarded', function($member_id, $points, $order_id) {
    // Send notification, update CRM, etc.
}, 10, 3);

// After reward claimed
add_action('useloyalty_reward_claimed', function($member_id, $reward, $coupon_code) {
    // Custom logic
}, 10, 3);

Add the loyalty widget to your WooCommerce theme:

Using Shortcode

[useloyalty_widget]

Using PHP

<?php if (is_user_logged_in()): ?>
  <?php echo do_shortcode('[useloyalty_widget]'); ?>
<?php endif; ?>

Template Location

Add to footer.php or a custom location:

<?php
if (function_exists('useloyalty_render_widget')) {
    useloyalty_render_widget();
}
?>

Refund Handling

Order Cancelled

All points are refunded:

Original: 100 points earned
Cancelled: -100 points
Balance: 0 change

Partial Refund

Points refunded proportionally:

Original Order: $100 → 100 points
Refund: $25 (25%)
Points Refunded: 100 × 0.25 = 25 points
Net Points: 75 points

Manual Adjustment

For edge cases, use the Server SDK:

$useloyalty_api->adjust_points($member_id, -50, 'Manual refund adjustment');

Troubleshooting

Connection Failed

Verify API URL is correct
Check API key is valid (starts with sk_)
Ensure HTTPS is enabled
Check firewall allows outbound connections

Webhooks Not Firing

Go to WooCommerce → Status → Logs
Check for webhook delivery errors
Verify webhook URLs are accessible
Test with manual order

Points Not Awarded

Check order status matches pointsOnStatus
Verify customer has account (if guest excluded)
Check order meets minimum amount
Review webhook delivery status

Duplicate Points

The system prevents duplicates via order ID tracking:

SELECT * FROM wp_useloyalty_order_transactions
WHERE wc_order_id = 123;

Data Model

Plugin Options

get_option('useloyalty_platform_url');     // API URL
get_option('useloyalty_api_key');          // Private key
get_option('useloyalty_webhook_secret');   // Webhook secret
get_option('useloyalty_store_id');         // Store ID
get_option('useloyalty_project_id');       // Project ID
get_option('useloyalty_connected');        // Connection status

Database Tables

The plugin doesn't create custom tables. All data is stored:

In useLoyalty (member points, transactions)
In WooCommerce (coupons, order meta)

Security

Credential Storage

Consumer keys stored encrypted
Webhook secrets unique per store
API keys never exposed to frontend

Webhook Verification

All webhooks verified with HMAC-SHA256:

$signature = base64_encode(
    hash_hmac('sha256', $payload, $webhook_secret, true)
);

User Permissions

Only admins can configure plugin
Member data scoped to logged-in user
API requests authenticated

WooCommerce Integration

On this page