Skip to main content

​
Overview

The Zupy Loyalty API enables you to build comprehensive customer loyalty programs with points management, rewards, customer segmentation, and transaction tracking.

​
Authentication

All API requests require authentication using a Bearer token in the Authorization header: 
Authorization: Bearer {your_api_key}

​
Base URLs

https://api.zupy.com/v1/

​
Quick Start

Get started with the Loyalty API in minutes:

​
1. Search for a Customer

curl -X GET "https://api.zupy.com/v1/loyalty/customers/search?whatsapp=+5511965958122" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
2. Create a New Customer

curl -X POST "https://api.zupy.com/v1/loyalty/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp": "+5511965958122",
    "name": "João Silva",
    "email": "[email protected]",
    "birth_date": "1990-05-15"
  }'

​
3. Record a Transaction

curl -X POST "https://api.zupy.com/v1/loyalty/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_code": "ZP-12345678",
    "amount": 150.00,
    "transaction_id": "TXN-001",
    "description": "Compra na loja física"
  }'

​
Core Features

Customer Management

Search, create, and manage customer profiles with comprehensive data tracking.

Transaction Processing

Record purchases, calculate points, and track transaction history.

Rewards System

Manage reward catalog, redemptions, and customer benefits.

Coupon Management

Create, validate, and track promotional coupons and discounts.

​
Points Configuration

Each business can configure their own points system: 
Points per R$1: 1
R$ 13,45 → 13 points (rounded down)

​
Customer Segmentation

Zupy automatically segments customers using RFM analysis:
  • Champions: High value, frequent, recent customers
  • Loyal Customers: Regular, consistent purchasers
  • Potential Loyalists: Recent customers with good potential
  • New Customers: Recently acquired customers
  • At Risk: Previously active customers becoming inactive
  • Can’t Lose Them: High value customers at risk of churning

​
Response Format

All API responses follow a consistent format: 
{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Error Handling

API errors return standardized error responses: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid customer data provided",
    "details": {
      "email": ["Invalid email format"]
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Rate Limits

  • Production: 1000 requests per minute
  • Staging: 100 requests per minute
Headers returned with each request: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1647891234

​
Support

Need help integrating? Contact our developer support: