SiteVibes Loyalty API Implementation Guide

Modified on Tue, 11 Feb at 11:44 AM

Developer Note: For detailed API reference documentation, visit SiteVibes 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_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
};

Retrieving Customer Data

Available include parameters:

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
});

2. Points Management

Adding Points

Field reference 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
};

Adjusting Points Balance

Field explanations 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
};

3. Rewards Management

Redeeming Points for Rewards

Field reference 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
};

Available reward types:

Found in Loyalty -> Ways to Redeem section of dashboard
Types include:
- 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 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
};

4. Tier Management

Updating Customer's Paid Tier

Field reference 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
};

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

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
    throw error;
  }
}

Security

Keep API tokens secure
Validate webhook signatures
Use HTTPS for all requests
Implement request timeouts

Testing

Use development endpoints first
Test all point calculations
Verify tier progression logic
Test reward redemption flow

Common Scenarios

Order Completion

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

Returns/Refunds

async function handleOrderRefund(refundData) {
  try {
    const pointsToRevoke = calculateRefundPoints(refundData);
    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);
  }
}

Technical Support

For implementation assistance:

Review API documentation at SiteVibes API Documentation
Contact SiteVibes support