SiteVibes Loyalty API Implementation Guide

Developer Note: For detailed API reference documentation, visit SiteVibes Loyalty API Documentation

Overview

This guide covers the implementation of loyalty features using the SiteVibes Enterprise API. The API allows you to fully integrate loyalty program functionality into your existing systems, manage customer points, handle rewards, and track program performance.

Authentication

All API requests require authentication using a bearer token. This token uniquely identifies your application and ensures secure access to the API.

Authorization: Bearer YOUR_ENTERPRISE_API_TOKEN

Base URLs

The API provides separate endpoints for development and production to allow safe testing:

Production: https://api.sitevibes.com/v1
Development: https://dev.sitevibes.com/api/v1

Field References

Global Fields

These fields are commonly used across multiple endpoints:

app_id: Your unique application identifier provided by SiteVibes during setup
email: Customer's email address used for identification
cid: Your internal customer ID that maps to your system

Core Components Implementation

1. Customer Management

Creating a New Loyalty Customer

Required fields and where to find them:

const customerData = {
  // Required fields:
  app_id: "your-app-id",           // From SiteVibes dashboard setup
  cid: "100001",                   // Your internal customer ID
  email: "[email protected]",    // Customer's email address
  first_name: "John",              // Customer's first name
  last_name: "Smith",              // Customer's last name
  
  // Optional fields:
  loyalty_points: 0,               // Starting points balance
  birthday_day: 21,                // 1-31
  birthday_month: 12,              // 1-12
  instagram_username: "username"    // Customer's Instagram handle
};

// Implementation
fetch('https://api.sitevibes.com/v1/loyalty/customer', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(customerData)
});

Retrieving Customer Data

Available include parameters and implementation:

const params = new URLSearchParams({
  app_id: 'your-app-id',    // From SiteVibes dashboard setup
  email: '[email protected]',
  
  // Optional include flags - all default to false:
  ways_to_earn: true,       // Get point earning methods
  ways_to_redeem: true,     // Get available rewards
  activity: true,           // Get point history
  rewards: true,            // Get active rewards
  points_exchange: true,    // Get points exchange rates
  active_promotion: true    // Get active promotional offers
});

fetch(`https://api.sitevibes.com/v1/loyalty/customer?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

2. Points Management

Adding Points

Field reference and implementation for point addition:

const pointsData = {
  // Required fields:
  app_id: "your-app-id",
  email: "[email protected]",
  
  // earn_type options (from Ways to Earn settings in dashboard):
  earn_type: "store_order",     // Available values:
                               // - store_signup: New account creation
                               // - store_order: Purchase completion
                               // - customer_birthday: Birthday bonus
                               // - store_review: Product review
                               // - sharing_media: Social media sharing
                               // - product_question_answer: Q&A participation
                               // - tagging_on_instagram: Instagram tags
                               // - following_on_instagram: Instagram follows
                               // - following_on_twitter: Twitter follows
                               // - following_on_tiktok: TikTok follows
                               // - Custom Action: Custom defined actions
  
  // Optional fields:
  amount: 39.99,                // Required for store_order type only
                               // Order amount to calculate points
  
  prevent_sending_points_email: false  // Control email notifications
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/add-points', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(pointsData)
});

Adjusting Points Balance

Field explanations and implementation for point adjustments:

const adjustmentData = {
  // Required fields:
  app_id: "your-app-id",
  email: "[email protected]",
  adjustment_value: 100,        // Positive or negative integer
                               // Positive: Add points
                               // Negative: Remove points
  
  // Optional fields:
  reason: "Bonus points added", // Free text for tracking
  apply_to_tier: true,         // Count towards tier progress
  apply_to_total: true         // Count in lifetime points
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/adjust-points', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(adjustmentData)
});

3. Rewards Management

Redeeming Points for Rewards

Field reference and implementation for reward redemption:

const redeemData = {
  // Required fields:
  app_id: "your-app-id",
  email: "[email protected]",
  reward_id: 15,               // From Ways to Redeem settings
                              // Found in dashboard under Loyalty -> Ways to Redeem
  
  // Optional fields:
  points: 1000                 // Required only for points_exchange type rewards
                              // Amount of points to exchange
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/redeem', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(redeemData)
});

Available reward types (found in Loyalty -> Ways to Redeem section of dashboard):

amount_discount: Fixed dollar amount off
percentage_discount: Percentage discount
free_shipping: Free shipping reward
free_product: Specific free product
points_exchange: Convert points to store credit

Exchange Points for Order Discount

Field reference and implementation for point exchange:

const exchangeData = {
  // Required fields:
  app_id: "your-app-id",
  email: "[email protected]",
  amount: 39.99                // Desired discount amount
                              // Must be within available points exchange value
                              // Check customer's points_exchange data for limits
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/redeem/exchange-points', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(exchangeData)
});

4. Tier Management

Updating Customer's Paid Tier

Field reference and implementation for paid tier management:

const tierData = {
  // Required fields:
  app_id: "your-app-id",
  email: "[email protected]",
  tier_id: 15                  // From Tiers settings in dashboard
                              // Found under Loyalty -> Member Tiers
                              // Only paid tiers are valid here
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/paid-tier', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(tierData)
});

Canceling Paid Tier

Implementation for removing paid tier status:

const cancelData = {
  app_id: "your-app-id",
  email: "[email protected]"
};

fetch('https://api.sitevibes.com/v1/loyalty/customer/paid-tier', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(cancelData)
});

Webhook Integration

Setting Up Webhooks

Field reference for webhook configuration:

const webhookData = {
  // Required fields:
  app_id: "your-app-id",
  scope: "customer/loyalty/updated",   // Available scopes:
                                      // - customer/loyalty/created: New member
                                      // - customer/loyalty/updated: Points changed
  
  destination: "https://your-domain.com/webhook-endpoint",  // Your endpoint URL
  enabled: true                       // Webhook status
};

Webhook Payload Fields

When receiving webhooks, you'll get these fields:

{
  scope: "customer/loyalty/updated",  // Event type that triggered webhook
  content: {
    // For customer/loyalty/created:
    cid: "100001",                    // Your customer ID
    identifier: "SV-10001",           // SiteVibes customer ID
    email: "[email protected]",
    loyalty_points: 12000,            // Current points balance
    loyalty_points_text: "12,000",    // Formatted points balance
    
    // For customer/loyalty/updated:
    // Same fields as above, plus:
    points_change: 100,               // Point change amount
    points_change_reason: "Purchase"  // Reason for change
  },
  hmac: "signature",                  // Verification signature
}

Best Practices

Error Handling

Always include error handling for API requests
Check response status codes and handle errors appropriately
Implement retry logic for failed requests
Log errors for debugging

async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }
    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    // Implement retry logic or error handling
    throw error;
  }
}

Rate Limiting

Implement request rate limiting
Cache frequently accessed data
Use batch endpoints when possible for multiple operations

Security

Never expose your API token in client-side code
Validate webhook signatures
Implement request timeouts
Use HTTPS for all API calls

Testing

Use the development API endpoint for testing
Test edge cases and error scenarios
Verify webhook handling
Test point calculations and tier progression
Validate reward redemption flow

Common Scenarios

Order Completion Flow

Create or update customer record
Add points for the purchase
Check for tier progression
Send confirmation to customer

async function handleOrderCompletion(orderData) {
  try {
    // Add points for purchase
    await addOrderPoints(orderData);
    
    // Get updated customer data
    const customerData = await getCustomerData(orderData.email);
    
    // Check for tier changes
    if (customerData.next_tier_id) {
      await checkTierProgression(customerData);
    }
    
  } catch (error) {
    console.error('Order completion error:', error);
    // Implement error handling
  }
}

Return/Refund Flow

Calculate points to revoke
Adjust customer's point balance
Update tier progress if necessary
Handle any active rewards

async function handleOrderRefund(refundData) {
  try {
    // Calculate points to revoke
    const pointsToRevoke = calculateRefundPoints(refundData);
    
    // Adjust customer points
    await adjustCustomerPoints({
      email: refundData.email,
      adjustment_value: -pointsToRevoke,
      reason: `Refund for order ${refundData.orderId}`,
      apply_to_tier: true
    });
    
  } catch (error) {
    console.error('Refund handling error:', error);
    // Implement error handling
  }
}

API Response Handling

Success Response Structure

{
  "message": "Success message",
  "status": true,
  "data": {
    // Response data specific to the endpoint
  }
}

Error Response Structure

{
  "message": "Error message",
  "status": false,
  "errors": {
    "field_name": [
      "Error description"
    ]
  }
}