Appearance

Referrals API ​

Manage your store's referral program, track referrals, and access referral statistics.

List Referrals ​

http
GET /api/external/v1/referrals

Query Parameters ​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 15, max: 100)
statusstringFilter: successful, pending
searchstringSearch by name or email

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals?status=successful" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Player123",
      "email": "player@example.com",
      "referred_at": "2025-01-15T10:30:00Z",
      "referrer": {
        "id": 2,
        "name": "TopReferrer",
        "email": "referrer@example.com",
        "referral_code": "ABC12345"
      },
      "status": "successful",
      "first_order_at": "2025-01-16T14:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Get Referral Statistics ​

http
GET /api/external/v1/referrals/statistics

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/statistics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": {
    "total_referrals": 150,
    "successful_referrals": 89,
    "conversion_rate": 59.33,
    "rewards_claimed": 45,
    "total_coupons_value": 450.00
  }
}

Get Referral Leaderboard ​

http
GET /api/external/v1/referrals/leaderboard

Query Parameters ​

ParameterTypeDescription
limitintegerNumber of entries (default: 10, max: 100)

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/leaderboard?limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "TopReferrer",
      "referral_count": 25
    },
    {
      "id": 2,
      "name": "Player456",
      "referral_count": 18
    }
  ]
}

Get Top Referrers ​

http
GET /api/external/v1/referrals/top-referrers

Query Parameters ​

ParameterTypeDescription
limitintegerNumber of entries (default: 10, max: 100)

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/top-referrers?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "TopReferrer",
      "email": "top@example.com",
      "referral_code": "ABC12345",
      "total_referrals": 30,
      "successful_referrals": 25,
      "rewards_claimed": 3
    }
  ]
}

Validate Referral Code ​

http
POST /api/external/v1/referrals/validate

Request Body ​

FieldTypeRequiredDescription
codestringYesThe referral code to validate

Example Request ​

bash
curl -X POST "https://yourstore.pixlpay.net/api/external/v1/referrals/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC12345"}'

Response ​

json
{
  "success": true,
  "data": {
    "valid": true,
    "referrer": {
      "id": 1,
      "name": "TopReferrer"
    }
  }
}

Invalid Code Response ​

json
{
  "success": true,
  "data": {
    "valid": false,
    "error": "Invalid referral code"
  }
}

List Referral Tiers ​

http
GET /api/external/v1/referrals/tiers

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/tiers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Bronze Referrer",
      "description": "Reward for 5 successful referrals",
      "referrals_required": 5,
      "reward_type": "percentage_discount",
      "reward_value": "10.00",
      "reward_currency": null,
      "coupon_validity_days": 30,
      "is_active": true,
      "sort_order": 1,
      "formatted_reward": "10.00% off",
      "claims_count": 12
    },
    {
      "id": 2,
      "name": "Silver Referrer",
      "description": "Reward for 15 successful referrals",
      "referrals_required": 15,
      "reward_type": "fixed_discount",
      "reward_value": "25.00",
      "reward_currency": "USD",
      "coupon_validity_days": 60,
      "is_active": true,
      "sort_order": 2,
      "formatted_reward": "$25.00 off",
      "claims_count": 5
    }
  ]
}

Create Referral Tier ​

http
POST /api/external/v1/referrals/tiers

Request Body ​

FieldTypeRequiredDescription
namestringYesTier name (max 255 characters)
descriptionstringNoTier description (max 1000 characters)
referrals_requiredintegerYesNumber of referrals required to unlock
reward_typestringYespercentage_discount or fixed_discount
reward_valuenumberYesDiscount value (min 0.01)
reward_currencystringNoCurrency code for fixed discounts (e.g., USD)
coupon_validity_daysintegerNoCoupon expiry days (1-365, default: 30)
is_activebooleanNoWhether tier is active (default: true)
sort_orderintegerNoDisplay order (default: 0)

Example Request ​

bash
curl -X POST "https://yourstore.pixlpay.net/api/external/v1/referrals/tiers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold Referrer",
    "description": "Reward for 25 successful referrals",
    "referrals_required": 25,
    "reward_type": "percentage_discount",
    "reward_value": 20,
    "coupon_validity_days": 90,
    "is_active": true,
    "sort_order": 3
  }'

Response ​

json
{
  "success": true,
  "data": {
    "id": 3,
    "name": "Gold Referrer",
    "description": "Reward for 25 successful referrals",
    "referrals_required": 25,
    "reward_type": "percentage_discount",
    "reward_value": "20.00",
    "reward_currency": null,
    "coupon_validity_days": 90,
    "is_active": true,
    "sort_order": 3,
    "formatted_reward": "20.00% off",
    "created_at": "2025-01-20T10:00:00Z",
    "updated_at": "2025-01-20T10:00:00Z"
  },
  "message": "Referral tier created successfully"
}

Update Referral Tier ​

http
PUT /api/external/v1/referrals/tiers/{id}

Request Body ​

All fields are optional. Only include fields you want to update.

FieldTypeDescription
namestringTier name (max 255 characters)
descriptionstringTier description (max 1000 characters)
referrals_requiredintegerNumber of referrals required
reward_typestringpercentage_discount or fixed_discount
reward_valuenumberDiscount value
reward_currencystringCurrency code for fixed discounts
coupon_validity_daysintegerCoupon expiry days (1-365)
is_activebooleanWhether tier is active
sort_orderintegerDisplay order

Example Request ​

bash
curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/referrals/tiers/3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reward_value": 25,
    "coupon_validity_days": 120
  }'

Response ​

json
{
  "success": true,
  "data": {
    "id": 3,
    "name": "Gold Referrer",
    "description": "Reward for 25 successful referrals",
    "referrals_required": 25,
    "reward_type": "percentage_discount",
    "reward_value": "25.00",
    "reward_currency": null,
    "coupon_validity_days": 120,
    "is_active": true,
    "sort_order": 3,
    "formatted_reward": "25.00% off"
  },
  "message": "Referral tier updated successfully"
}

Delete Referral Tier ​

http
DELETE /api/external/v1/referrals/tiers/{id}

WARNING

Tiers with existing claims will be deactivated instead of deleted.

Example Request ​

bash
curl -X DELETE "https://yourstore.pixlpay.net/api/external/v1/referrals/tiers/3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response (No Claims) ​

json
{
  "success": true,
  "message": "Referral tier deleted successfully"
}

Response (Has Claims) ​

json
{
  "success": true,
  "message": "Referral tier has been deactivated (has existing claims)"
}

Toggle Tier Status ​

http
POST /api/external/v1/referrals/tiers/{id}/toggle

Example Request ​

bash
curl -X POST "https://yourstore.pixlpay.net/api/external/v1/referrals/tiers/1/toggle" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Bronze Referrer",
    "is_active": false,
    "formatted_reward": "10.00% off"
  },
  "message": "Tier deactivated"
}

Get Referral Settings ​

http
GET /api/external/v1/referrals/settings

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": {
    "referral_enabled": true,
    "referral_reward_event": "first_purchase",
    "referral_welcome_discount_enabled": true,
    "referral_welcome_discount_type": "percentage",
    "referral_welcome_discount_value": 10
  }
}

Update Referral Settings ​

http
PUT /api/external/v1/referrals/settings

Request Body ​

FieldTypeDescription
referral_enabledbooleanEnable/disable referral program
referral_reward_eventstringWhen to count: signup or first_purchase
referral_welcome_discount_enabledbooleanEnable welcome discount for referred customers
referral_welcome_discount_typestringpercentage or fixed
referral_welcome_discount_valuenumberDiscount value

Example Request ​

bash
curl -X PUT "https://yourstore.pixlpay.net/api/external/v1/referrals/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_enabled": true,
    "referral_reward_event": "first_purchase",
    "referral_welcome_discount_enabled": true,
    "referral_welcome_discount_type": "percentage",
    "referral_welcome_discount_value": 15
  }'

Response ​

json
{
  "success": true,
  "data": {
    "referral_enabled": true,
    "referral_reward_event": "first_purchase",
    "referral_welcome_discount_enabled": true,
    "referral_welcome_discount_type": "percentage",
    "referral_welcome_discount_value": 15
  },
  "message": "Referral settings updated successfully"
}

List Reward Claims ​

http
GET /api/external/v1/referrals/claims

Query Parameters ​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 15, max: 100)

Example Request ​

bash
curl -X GET "https://yourstore.pixlpay.net/api/external/v1/referrals/claims" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response ​

json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "customer": {
        "id": 1,
        "name": "TopReferrer",
        "email": "referrer@example.com"
      },
      "tier": {
        "id": 1,
        "name": "Bronze Referrer",
        "referrals_required": 5
      },
      "coupon": {
        "id": 10,
        "code": "REF-A1B2C3D4",
        "times_used": 1
      },
      "claimed_at": "2025-01-18T12:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "total": 25
  }
}

Referral Object ​

FieldTypeDescription
idintegerUnique identifier of referred customer
namestringCustomer name
emailstringCustomer email
referred_atstringISO 8601 timestamp of referral
referrerobjectReferrer customer details
statusstringsuccessful (has paid order) or pending
first_order_atstringFirst paid order timestamp (if any)

Referrer Object ​

FieldTypeDescription
idintegerUnique identifier
namestringCustomer name
emailstringCustomer email
referral_codestringUnique referral code

Referral Tier Object ​

FieldTypeDescription
idintegerUnique identifier
namestringTier name
descriptionstringTier description
referrals_requiredintegerNumber of referrals to unlock
reward_typestringpercentage_discount or fixed_discount
reward_valuestringDiscount value
reward_currencystringCurrency code (for fixed discounts)
coupon_validity_daysintegerDays until coupon expires
is_activebooleanWhether tier is active
sort_orderintegerDisplay order
formatted_rewardstringHuman-readable reward (e.g., "10.00% off")
claims_countintegerNumber of times this tier has been claimed

Statistics Object ​

FieldTypeDescription
total_referralsintegerTotal number of referred customers
successful_referralsintegerReferrals that made a purchase
conversion_ratenumberPercentage of referrals that converted
rewards_claimedintegerTotal reward claims made
total_coupons_valuenumberTotal value of used referral coupons

Errors ​

StatusErrorDescription
401UnauthorizedInvalid or missing token
403ForbiddenToken lacks referrals:read or referrals:write scope
404Not FoundReferral tier doesn't exist
422UnprocessableValidation error (e.g., invalid reward type)

Built for game developers, by game developers.

Copyright 2025 Pixlpay. All rights reserved.