REST API v2

X-Joy-Loyalty-App-Key: your_app_key_here
X-Joy-Loyalty-Secret-Key: your_secret_key_here

curl -X GET "https://dev-api.joy.so/rest_api/v2/customers" \
  -H "X-Joy-Loyalty-App-Key: your_app_key" \
  -H "X-Joy-Loyalty-Secret-Key: your_secret_key" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}, // or []
  "meta": {
    "count": 25, // for list responses
    "pagination": { // for paginated responses
      "hasNext": true,
      "hasPre": false,
      "total": 1250, // when hasCount=true
      "totalPage": 63 // when hasCount=true
    }
  },
  "timestamp": "2023-07-28T07:27:54.123Z",
  "message": "Operation completed successfully" // optional
}

{
  "success": false,
  "error": {
    "message": "Resource not found",
    "code": "NOT_FOUND",
    "statusCode": 404,
    "details": {} // optional
  },
  "timestamp": "2023-07-28T07:27:54.123Z"
}

# First page
curl "https://dev-api.joy.so/rest_api/v2/customers?limit=20&hasCount=true"
 
# Next page (using last item's ID from previous response)
curl "https://dev-api.joy.so/rest_api/v2/customers?after=abc123&limit=20"
 
# Previous page (using first item's ID)
curl "https://dev-api.joy.so/rest_api/v2/customers?before=abc123&limit=20"

curl "https://dev-api.joy.so/rest_api/v2/customers?\
created_at_min=2023-01-01T00:00:00Z&\
created_at_max=2023-12-31T23:59:59Z&\
order=createdAt_desc&\
limit=50"

{
  "success": false,
  "error": {
    "message": "Customer not found",
    "code": "CUSTOMER_NOT_FOUND",
    "statusCode": 404
  },
  "timestamp": "2023-07-28T07:27:54.123Z"
}

{
  "success": false,
  "error": "daily_quota_exceeded",
  "message": "You've reached your daily API limit (200 requests/day) on the pro_3_2025 plan. Your limit resets at midnight UTC, or upgrade your plan for a higher limit.",
  "limit": 200,
  "used": 201,
  "resetsAt": "2026-10-24T00:00:00.000Z",
  "upgrade_url": "https://admin.shopify.com/store/<store>/apps/<app>/embed/subscription"
}

// Use hasCount sparingly to avoid performance impact
const customers = await fetch('/rest_api/v2/customers?hasCount=false');
 
// Navigate using document IDs, not page numbers
const nextPage = await fetch(`/rest_api/v2/customers?after=${lastCustomerId}`);

// Use proper ISO 8601 format for dates
const recentCustomers = await fetch(
  '/rest_api/v2/customers?created_at_min=2023-07-01T00:00:00Z'
);

async function handleApiCall(url) {
  const response = await fetch(url);
  const data = await response.json();
  
  if (!data.success) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }
  
  return data.data;
}

// Instead of multiple single requests
customers.forEach(id => updateCustomer(id)); // ❌ Inefficient
 
// Use bulk operations when available
await updateMultipleCustomers(customerIds); // ✅ Efficient

 
import JoyApi from 'joy-api-node';
 
const joy = new JoyApi({
  appKey: 'your-app-key',
  secretKey: 'your-secret-key',
  baseUrl: 'https://dev-api.joy.so', // optional, defaults to production
  timeout: 30000, // optional, request timeout in ms
  maxRetries: 3 // optional, number of retries for failed requests
});
 
// Get shop information
const shop = await joy.shop.whoami();
console.log(shop.data);

import requests
from typing import Dict, Optional
 
class JoyApiClient:
    def __init__(self, app_key: str, secret_key: str, base_url: str = 'https://dev-api.joy.so'):
        self.app_key = app_key
        self.secret_key = secret_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'X-Joy-Loyalty-App-Key': app_key,
            'X-Joy-Loyalty-Secret-Key': secret_key
        })
 
    def request(self, endpoint: str, method: str = 'GET', data: Optional[Dict] = None):
        url = f"{self.base_url}{endpoint}"
        response = self.session.request(method, url, json=data)
        
        result = response.json()
        if not result.get('success'):
            error = result.get('error', {})
            raise Exception(f"{error.get('code', 'UNKNOWN_ERROR')}: {error.get('message', 'Unknown error')}")
        
        return result
 
    def get_customers(self, **params):
        query_string = '&'.join([f"{k}={v}" for k, v in params.items()])
        endpoint = f"/rest_api/v2/customers?{query_string}"
        return self.request(endpoint)
 
    def award_points(self, shopify_customer_id: str, points: int, note: str = ''):
        return self.request('/rest_api/v2/transactions/points/award', 'POST', {
            'shopifyCustomerId': shopify_customer_id,
            'point': points,
            'adminNote': note
        })
 
# Usage
client = JoyApiClient('your-app-key', 'your-secret-key')
customers = client.get_customers(limit=20, order='createdAt_desc')

<?php
class JoyApiClient {
    private $appKey;
    private $secretKey;
    private $baseUrl;
 
    public function __construct($appKey, $secretKey, $baseUrl = 'https://dev-api.joy.so') {
        $this->appKey = $appKey;
        $this->secretKey = $secretKey;
        $this->baseUrl = $baseUrl;
    }
 
    public function request($endpoint, $method = 'GET', $data = null) {
        $url = $this->baseUrl . $endpoint;
        
        $headers = [
            'Content-Type: application/json',
            'X-Joy-Loyalty-App-Key: ' . $this->appKey,
            'X-Joy-Loyalty-Secret-Key: ' . $this->secretKey
        ];
 
        $curl = curl_init();
        curl_setopt_array($curl, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_POSTFIELDS => $data ? json_encode($data) : null
        ]);
 
        $response = curl_exec($curl);
        curl_close($curl);
 
        $result = json_decode($response, true);
        if (!$result['success']) {
            $error = $result['error'] ?? [];
            throw new Exception(($error['code'] ?? 'UNKNOWN_ERROR') . ': ' . ($error['message'] ?? 'Unknown error'));
        }
 
        return $result;
    }
 
    public function getCustomers($params = []) {
        $queryString = http_build_query($params);
        return $this->request("/rest_api/v2/customers?$queryString");
    }
 
    public function awardPoints($shopifyCustomerId, $points, $note = '') {
        return $this->request('/rest_api/v2/transactions/points/award', 'POST', [
            'shopifyCustomerId' => $shopifyCustomerId,
            'point' => $points,
            'adminNote' => $note
        ]);
    }
}
 
// Usage
$client = new JoyApiClient('your-app-key', 'your-secret-key');
$customers = $client->getCustomers(['limit' => 20]);
?>