Partner API Overview

The Partner API provides advanced functionality for businesses managing multiple shops, locations, or franchises. It offers comprehensive control over loyalty programs with multi-shop management, advanced analytics, and enterprise-grade features.

The Partner API requires special credentials and is designed for businesses with multiple locations or complex loyalty program requirements.

API Characteristics

Multi-Shop Support

Manage multiple shops and locations from a single API integration with unified customer tracking.

Advanced Analytics

Access detailed analytics and reporting across all shops with comparative performance metrics.

Enterprise Features

Advanced features like bulk operations, custom rules, and white-label solutions for large businesses.

Dedicated Support

Priority support with dedicated account management and technical assistance.

Authentication

Partner API uses enhanced authentication with additional security measures:

curl -X POST 'https://staging-api.loyalty.lt/api/partners/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "partner@example.com",
    "password": "your_password",
    "remember": true
  }'

Response:

{
  "success": true,
  "data": {
    "access_token": "jwt_token_here",
    "refresh_token": "refresh_token_here",
    "partner": {
      "id": 123,
      "name": "ABC Retail Group",
      "email": "partner@example.com",
      "tier": "enterprise",
      "shops_count": 15
    }
  }
}

Base URLs

Staging Environment

Production Environment

Core API Sections

Shop Management

Shop Operations

GET /shopsList all shops managed by the partner

Shop Details

GET /shops/{id}Get detailed information about a specific shop

Create Shop

POST /shopsCreate a new shop location

Update Shop

PUT /shops/{id}Update shop information and settings

Customer Management

Unified Customer Database

Cross-shop customer profiles
Consolidated loyalty data
Multi-location transaction history
Unified communication preferences

Analytics and Reporting

Partner-Level Analytics

GET /analytics/overviewComprehensive analytics across all partner shops:

{
  "total_customers": 25000,
  "active_loyalty_cards": 18500,
  "total_points_issued": 2500000,
  "total_points_redeemed": 1200000,
  "revenue_impact": {
    "total_attributed": 850000,
    "avg_order_increase": 23.5,
    "customer_retention_rate": 67.2
  },
  "top_performing_shops": [...]
}

Shop Performance Comparison

Custom Reports

POST /analytics/reportsGenerate custom reports with specific metrics and date ranges:

{
  "report_type": "customer_behavior",
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  },
  "shops": [1, 2, 3],
  "metrics": [
    "customer_acquisition",
    "retention_rate",
    "avg_transaction_value"
  ],
  "format": "json"
}

Bulk Operations

Partner API provides powerful bulk operation capabilities for managing large volumes of data efficiently.

# Bulk import customers
POST /customers/bulk-import

# Bulk update customer data
PUT /customers/bulk-update

# Bulk point awards across customers
POST /points/bulk-award

# Bulk tier adjustments
POST /customers/bulk-tier-update

Advanced Features

Multi-Shop Point Management

curl -X POST 'https://staging-api.loyalty.lt/api/partners/points/cross-shop-award' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_jwt_token' \
  -H 'X-Partner-ID: 123' \
  -d '{
    "customer_id": "customer_456",
    "points": 100,
    "reason": "Cross-shop loyalty bonus",
    "source_shop_id": 1,
    "credited_to_shops": [1, 2, 3],
    "reference": "campaign_2024_q1"
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_cross_789",
    "customer_id": "customer_456",
    "total_points_awarded": 100,
    "cross_shop_distribution": [
      {
        "shop_id": 1,
        "points": 40,
        "new_balance": 540
      },
      {
        "shop_id": 2,
        "points": 30,
        "new_balance": 230
      },
      {
        "shop_id": 3,
        "points": 30,
        "new_balance": 330
      }
    ],
    "created_at": "2024-12-27T17:00:00Z"
  }
}

Campaign Management

Multi-Shop Campaigns

POST /campaignsCreate promotional campaigns across multiple shops

Campaign Analytics

GET /campaigns/{id}/analyticsTrack campaign performance and ROI

A/B Testing

POST /campaigns/ab-testRun split tests across different shop groups

Automated Campaigns

POST /campaigns/automatedSet up rule-based automated campaigns

Staff and Permissions

# List all staff across shops
GET /staff

# Add staff member to specific shop
POST /shops/{shop_id}/staff

# Update staff permissions
PUT /staff/{staff_id}/permissions

# Staff performance analytics
GET /staff/{staff_id}/analytics

Partner-Specific Endpoints

Partner Information

curl -X GET 'https://staging-api.loyalty.lt/api/partners/profile' \
  -H 'Authorization: Bearer your_jwt_token' \
  -H 'X-Partner-ID: 123'

{
  "success": true,
  "data": {
    "id": 123,
    "name": "ABC Retail Group",
    "email": "partner@example.com",
    "phone": "+1234567890",
    "tier": "enterprise",
    "status": "active",
    "created_at": "2023-01-15T10:00:00Z",
    "billing_info": {
      "plan": "Enterprise Plus",
      "monthly_fee": 999.99,
      "transaction_limit": 100000,
      "api_rate_limit": 10000
    },
    "shops": {
      "total": 15,
      "active": 14,
      "pending": 1
    },
    "features": [
      "multi_shop_management",
      "advanced_analytics",
      "white_label_options",
      "priority_support",
      "custom_integrations"
    ]
  }
}

Partner Settings

Global Settings

PUT /settings/globalUpdate partner-wide settings that apply to all shops:

{
  "default_point_value": 0.01,
  "default_expiration_months": 12,
  "cross_shop_redemption": true,
  "unified_customer_profiles": true,
  "auto_tier_progression": true,
  "notification_preferences": {
    "email_alerts": true,
    "sms_notifications": false,
    "webhook_notifications": true
  }
}

Branding Configuration

PUT /settings/brandingConfigure partner branding across all applications:

{
  "logo_url": "https://example.com/logo.png",
  "primary_color": "#16A34A",
  "secondary_color": "#07C983",
  "font_family": "Inter",
  "custom_css": ".loyalty-card { border-radius: 12px; }",
  "email_templates": {
    "welcome": "custom_welcome_template_id",
    "points_earned": "custom_points_template_id"
  }
}

Integration Settings

PUT /settings/integrationsConfigure third-party integrations and webhooks:

{
  "webhooks": [
    {
      "url": "https://your-system.com/webhook",
      "events": ["points_awarded", "customer_tier_changed"],
      "secret": "webhook_secret_key"
    }
  ],
  "api_limits": {
    "requests_per_minute": 1000,
    "bulk_operation_size": 10000
  },
  "external_integrations": {
    "crm_system": "salesforce",
    "email_provider": "mailchimp",
    "analytics_platform": "google_analytics"
  }
}

Advanced Analytics

Cross-Shop Customer Journey

curl -X GET 'https://staging-api.loyalty.lt/api/partners/analytics/customer-journey?customer_id=456&date_range=6m' \
  -H 'Authorization: Bearer your_jwt_token' \
  -H 'X-Partner-ID: 123'

{
  "success": true,
  "data": {
    "customer_id": 456,
    "journey_summary": {
      "first_visit": "2024-06-15T14:30:00Z",
      "total_visits": 24,
      "shops_visited": [1, 2, 5, 8],
      "total_spent": 2400.50,
      "points_earned": 2450,
      "points_redeemed": 800,
      "current_tier": "gold"
    },
    "journey_timeline": [
      {
        "date": "2024-06-15T14:30:00Z",
        "shop_id": 1,
        "event": "first_visit",
        "transaction_amount": 45.99,
        "points_earned": 46
      },
      {
        "date": "2024-06-22T16:45:00Z",
        "shop_id": 2,
        "event": "cross_shop_visit",
        "transaction_amount": 89.99,
        "points_earned": 90
      },
      {
        "date": "2024-07-01T12:00:00Z",
        "shop_id": 1,
        "event": "tier_upgrade",
        "previous_tier": "bronze",
        "new_tier": "silver"
      }
    ],
    "predictive_insights": {
      "churn_risk": "low",
      "next_visit_probability": 0.82,
      "recommended_offers": [
        "10% off next purchase",
        "Double points weekend"
      ]
    }
  }
}

Business Intelligence

# Revenue attribution analysis
GET /analytics/revenue-attribution?period=month&shops=all

# Customer lifetime value by tier
GET /analytics/customer-ltv?group_by=tier

# Profit impact of loyalty program
GET /analytics/profit-impact?include_costs=true

White-Label Solutions

Enterprise partners can access white-label solutions for complete brand customization.

Custom Domain Configuration

curl -X POST 'https://staging-api.loyalty.lt/api/partners/white-label/domain' \
  -H 'Authorization: Bearer your_jwt_token' \
  -H 'X-Partner-ID: 123' \
  -d '{
    "domain": "loyalty.yourbrand.com",
    "ssl_certificate": "-----BEGIN CERTIFICATE-----...",
    "ssl_private_key": "-----BEGIN PRIVATE KEY-----...",
    "subdomain_config": {
      "portal": "partners.yourbrand.com",
      "api": "api.yourbrand.com",
      "mobile": "mobile.yourbrand.com"
    }
  }'

Mobile App Customization

App Configuration

POST /white-label/mobile-appConfigure custom mobile application:

{
  "app_name": "Your Brand Loyalty",
  "bundle_id": "com.yourbrand.loyalty",
  "app_icon": "base64_encoded_icon_data",
  "splash_screen": "base64_encoded_splash_data",
  "color_scheme": {
    "primary": "#FF6B6B",
    "secondary": "#4ECDC4",
    "accent": "#45B7D1"
  },
  "features": {
    "qr_scanning": true,
    "push_notifications": true,
    "social_sharing": true,
    "offline_mode": true
  }
}

App Store Deployment

Enterprise Integration

ERP System Integration

# Configure SAP connection
POST /integrations/sap/configure

# Sync customer data with SAP
POST /integrations/sap/sync-customers

# Real-time transaction sync
POST /integrations/sap/transaction-webhook

Data Export and Compliance

GDPR Compliance

GET /compliance/gdpr/customer-data/{id}Export all customer data for GDPR requests

Data Anonymization

POST /compliance/anonymize-customerAnonymize customer data while preserving analytics

Audit Trail

GET /compliance/audit-trailComplete audit trail of all partner operations

Data Retention

PUT /compliance/retention-policyConfigure automated data retention policies

Rate Limits and Quotas

Partner API endpoints have different rate limits based on your partner tier and plan.

Rate Limit Information

API Calls: 10,000 per hour
Bulk Operations: 50,000 records per batch
Concurrent Requests: 100
Data Export: Unlimited
Real-time Webhooks: Unlimited

Rate Limit Headers

All API responses include rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1640995200
X-RateLimit-Tier: enterprise

Error Handling

Partner-Specific Errors

Status Code: 403

{
  "success": false,
  "error": {
    "code": "PARTNER_TIER_REQUIRED",
    "message": "This operation requires Enterprise partner tier",
    "current_tier": "professional",
    "required_tier": "enterprise",
    "upgrade_url": "https://partners.loyalty.lt/upgrade"
  }
}

Shop Access Errors

Bulk Operation Errors

Status Code: 422

{
  "success": false,
  "error": {
    "code": "BULK_OPERATION_TOO_LARGE",
    "message": "Bulk operation exceeds maximum allowed size",
    "provided_size": 75000,
    "maximum_size": 50000,
    "suggestion": "Split into smaller batches"
  }
}

Support and Resources

Partner Support Channels

Priority Support

Enterprise partners get priority support:

Dedicated account manager
2-hour response time SLA
Direct developer access
Emergency hotline available

Technical Resources

Advanced technical documentation:

Integration guides for enterprise systems
Custom development examples
Architecture consultation
Performance optimization guidance

Business Consultation

Strategic business support:

Loyalty program optimization
Industry best practices
ROI improvement strategies
Competitive analysis insights

Training and Certification

Partner education programs:

Advanced API training courses
Loyalty program management certification
Regular webinars and workshops
Partner conference access

Next Steps

Partners Portal

Learn about the web-based Partners Portal interface.

Shop Management API

Detailed documentation for shop management endpoints.

Analytics API

Advanced analytics and reporting API endpoints.

White-Label Solutions

Custom branding and white-label integration options.

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

​Partner API Overview

​API Characteristics

Multi-Shop Support

Advanced Analytics

Enterprise Features

Dedicated Support

​Authentication

​Base URLs

​Core API Sections

​Shop Management

Shop Operations

Shop Details

Create Shop

Update Shop

​Customer Management

​Analytics and Reporting

​Bulk Operations

​Advanced Features

​Multi-Shop Point Management

​Campaign Management

Multi-Shop Campaigns

Campaign Analytics

A/B Testing

Automated Campaigns

​Staff and Permissions

​Partner-Specific Endpoints

​Partner Information

​Partner Settings

​Advanced Analytics

​Cross-Shop Customer Journey

​Business Intelligence

​White-Label Solutions

​Custom Domain Configuration

​Mobile App Customization

​Enterprise Integration

​ERP System Integration

​Data Export and Compliance

GDPR Compliance

Data Anonymization

Audit Trail

Data Retention

​Rate Limits and Quotas

​Rate Limit Information

​Rate Limit Headers

​Error Handling

​Support and Resources

​Partner Support Channels

Priority Support

Technical Resources

Business Consultation

Training and Certification

​Next Steps

Partners Portal

Shop Management API

Analytics API

White-Label Solutions

Partner API Overview

API Characteristics

Authentication

Base URLs

Core API Sections

Shop Management

Customer Management

Analytics and Reporting

Bulk Operations

Advanced Features

Multi-Shop Point Management

Campaign Management

Staff and Permissions

Partner-Specific Endpoints

Partner Information

Partner Settings

Advanced Analytics

Cross-Shop Customer Journey

Business Intelligence

White-Label Solutions

Custom Domain Configuration

Mobile App Customization

Enterprise Integration

ERP System Integration

Data Export and Compliance

Rate Limits and Quotas

Rate Limit Information

Rate Limit Headers

Error Handling

Support and Resources

Partner Support Channels

Next Steps