← ALL POSTS
22 NOVEMBER 2025

API Documentation Overview

API Documentation

Available Endpoints

The AIVA Merchant Data API provides 13 comprehensive REST endpoints:

Category Endpoint Description
Merchant GET /merchant/{id}/info Get store profile and settings
Customers GET /merchant/{id}/customers Get all customers with RFM segments
GET /merchant/{id}/customers/{customerId} Get individual customer details
Subscriptions GET /merchant/{id}/subscriptions Get subscription list with billing info
GET /merchant/{id}/subscriptions/{subId} Get individual subscription
POST /merchant/{id}/subscriptions/sync Trigger manual subscription sync
Affiliates GET /merchant/{id}/affiliates Get affiliate performance metrics
GET /merchant/{id}/affiliates/{affId} Get individual affiliate details
Prize Draws GET /merchant/{id}/prize-draws Get all prize draw campaigns
POST /merchant/{id}/prize-draws Create new prize draw
Orders GET /merchant/{id}/orders Get order history with filtering
Intelligence GET /merchant/{id}/intelligence Get comprehensive analytics dashboard
AIVA Messages POST /merchant/{id}/aiva/send Send AI-powered message to customer

Interactive Documentation

👉 Swagger UI: https://api.getaiva.ai/swagger

Features:

  • Try all endpoints directly in your browser

  • See request/response schemas

  • Copy working code snippets

  • Test authentication

  • Explore data models

Authentication

All API requests require the X-API-Key header:

X-API-Key: your-merchant-api-key-here

Security Best Practices:

  • Store keys in environment variables (never commit to Git)

  • Use HTTPS only (HTTP requests will be rejected)

  • Rotate keys quarterly

  • Use different keys for dev/staging/production

  • Implement rate limit handling (100 req/min)

RFM Customer Segmentation

One of AIVA's most powerful features is automatic RFM (Recency, Frequency, Monetary) segmentation:

Segment Criteria Marketing Strategy Expected Revenue Impact
Champions Recent buyer, frequent orders, high spend VIP treatment, referrals, exclusives 40-60% of revenue
Loyal Consistent buyer, moderate frequency Loyalty rewards, upsells, subscriptions 25-35% of revenue
At Risk Previously good, declining activity Win-back campaigns, discounts 15-25% recoverable
Hibernating No purchase 90+ days Aggressive reactivation, last chance 10-20% recoverable
New Recent first purchase Welcome series, education, incentives Future Champions

Example: Get At-Risk Customers

curl "https://api.getaiva.ai/api/merchant/{merchantId}/customers?segment=At%20Risk" \
  -H "X-API-Key: your-key"

Rate Limits & Performance

Endpoint Type Rate Limit Cache Duration
Read Operations 100 req/min 5-15 minutes
Write Operations 30 req/min N/A
Sync Operations 1 req/hour N/A
Intelligence 50 req/min 15 minutes

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1637251200
`" -
Want this working on your store? Aiva does the sales, marketing and service work - in your voice, around the clock.
Get Aiva