HytaleCharts Integration

Reward your customers for voting on HytaleCharts with automatic coupon codes and Discord roles.

Overview

The HytaleCharts integration allows you to:

• Track votes from your HytaleCharts server listing
• Reward customers with discount coupons or free products
• Assign Discord roles as vote rewards
• Set milestones (e.g., 10 votes, 50 votes, 100 votes)
• Send email notifications when rewards are earned

How It Works

Customer votes on HytaleCharts
         |
         v
+------------------+
|  Pixlpay polls   |
|  HytaleCharts    |
|  (every 15 min)  |
+--------+---------+
         |
         v
Vote matched to customer via Discord ID
         |
         v
+------------------+
|  Reward created  |
|  (pending claim) |
+--------+---------+
         |
         v
Email sent to customer
         |
         v
Customer claims reward in store account
         |
         v
Coupon code generated or Discord role queued

Matching Votes to Customers

Votes are matched using Discord ID. For this to work:

• Your customer must be logged in via Discord OAuth
• The same Discord account must be used when voting on HytaleCharts

Setting Up HytaleCharts

Prerequisites

1. A server listed on HytaleCharts
2. An API token from HytaleCharts
3. Discord OAuth enabled in your store (for customer matching)

Step 1: Get Your HytaleCharts API Token

1. Log in to HytaleCharts
2. Go to your server's dashboard
3. Navigate to API Settings or Integrations
4. Generate or copy your API Token

Step 2: Configure in Pixlpay

1. Go to Settings > Integrations > HytaleCharts in your store dashboard
2. Enter your server details:
   • Server ID - Your HytaleCharts server ID
   • Server Slug - Your server's URL slug (e.g., my-awesome-server)
   • API Token - The token from Step 1
3. Click Test Connection to verify
4. Click Save

Step 3: Create Vote Rewards

After connecting, you can create rewards:

1. Click Add Reward
2. Choose a reward type:
   • Discount Coupon - Percentage or fixed amount off
   • Free Product - 100% off a specific product
   • Discord Role - Assign a role when claimed
3. Choose the reward model:
   • Per Vote - Every vote earns the reward
   • Milestone - Unlock at specific vote counts
4. Configure the reward details
5. Click Save

Reward Types

Discount Coupon

Give customers a discount code they can use at checkout.

Setting	Description
Discount Type	Percentage (e.g., 10% off) or Fixed Amount (e.g., $5 off)
Discount Value	The amount of the discount
Validity Days	How long the coupon is valid (default: 30 days)
Applicable Products	Limit to specific products (optional)

Free Product

Give customers a 100% discount on a specific product.

Setting	Description
Product	The product to give for free
Validity Days	How long the coupon is valid

Discord Role

Assign a Discord role when the reward is claimed.

Setting	Description
Discord Server	Your connected Discord server
Role	The role to assign

INFO

Discord role rewards require the Custom Discord Bot to be configured.

Reward Models

Per-Vote Rewards

Customers earn the reward for every vote they cast.

Best for:

• Small, repeatable rewards
• Encouraging daily voting
• Building engagement

Example: 5% off coupon for every vote

Milestone Rewards

Customers unlock rewards at specific vote counts (e.g., 10, 25, 50, 100 votes).

Best for:

• Larger, one-time rewards
• Recognizing loyal voters
• Creating progression/goals

Example:

• 10 votes: 10% off coupon
• 25 votes: 20% off coupon
• 50 votes: Free product
• 100 votes: VIP Discord role

Customer Experience

Finding Rewards

Customers can find their vote rewards in several places:

1. Account Dashboard - Main rewards widget
2. Navigation Menu - "Vote Rewards" link (shows badge with count)
3. Floating Button - Gift icon appears when rewards are available
4. Order Confirmation - CTA to vote after purchase

Claiming Rewards

1. Customer logs into their account
2. Goes to Account Dashboard
3. Clicks "Claim" on any pending reward
4. For coupons: Receives unique code to use at checkout
5. For Discord roles: Uses /claim command in Discord

Email Notifications

Customers receive an email when they earn a new reward containing:

• Reward details (type, value)
• Their total vote count
• Link to claim the reward
• Expiration date
• Link to vote again

Polling & Sync

Pixlpay automatically polls HytaleCharts for new votes:

Setting	Default
Poll Interval	Every 15 minutes
Lookback Period	24 hours

You can also manually trigger a sync from the dashboard by clicking Sync Now.

Statistics

The dashboard shows key metrics:

• Total Votes Tracked - All votes from your server
• Matched Customers - Votes linked to store accounts
• Rewards Issued - Total rewards given out
• Active Rewards - Currently configured rewards

Troubleshooting

Votes Not Being Matched

Problem: Votes appear but aren't linked to customers.

Solutions:

1. Ensure customers log in via Discord OAuth
2. Verify the Discord ID matches between HytaleCharts and your store
3. Check that the customer has made at least one purchase or has an account

Rewards Not Appearing

Problem: Customer voted but doesn't see a reward.

Solutions:

1. Wait for the next poll cycle (up to 15 minutes)
2. Click "Sync Now" to force an immediate sync
3. Verify the customer's Discord account is linked
4. Check that rewards are configured and enabled

API Connection Failed

Problem: Test connection fails.

Solutions:

1. Verify your API token is correct
2. Check that your server is listed on HytaleCharts
3. Ensure the server slug matches exactly
4. Try regenerating the API token

Best Practices

1. Start small - Begin with per-vote rewards to encourage voting
2. Add milestones - Create progression with milestone rewards
3. Mix reward types - Combine coupons with Discord roles
4. Set reasonable expiry - 30 days is a good default
5. Promote voting - Add vote links to your store and Discord

API Reference

For developers, vote rewards can be accessed via the API:

# Check if vote rewards are available
GET /v1/storefront/vote-rewards/available

# Get customer's vote status (authenticated)
GET /v1/customer/vote-rewards/status

# Get claimable rewards (authenticated)
GET /v1/customer/vote-rewards

# Claim a reward (authenticated)
POST /v1/customer/vote-rewards/{id}/claim