Loyalty & Churn APIs
Loyalty API
Query loyalty rules, track customer progress, and retrieve earned coupons for storefront loyalty integrations.
Query loyalty rules, track customer progress, and retrieve earned coupons. This API enables storefront integrations for loyalty programs, rewards tracking, and coupon management.
Endpoint
| Property | Value |
|---|---|
| Base URL | {store}.myshopify.com/apps/subscribfy-api/v1/loyalty |
| Method | GET |
| Authentication | Shopify App Proxy (automatic) |
Available Endpoints
| Endpoint | Description |
|---|---|
GET /rules | List all loyalty rules |
GET /rules/{id} | Get single rule with progress |
GET /customers/{shopify_id} | Get customer loyalty data |
GET /customers/{shopify_id}/coupons | Get customer's earned coupons |
List Rules
Retrieve all loyalty rules for the store, optionally filtered by type or status.
Request
GET /apps/subscribfy-api/v1/loyalty/rulesQuery Parameters
Prop
Type
Example Request
curl "https://your-store.myshopify.com/apps/subscribfy-api/v1/loyalty/rules?type=points_for_purchases&status=1"Response
{"data": [ { "id": 123, "status": 1, "type": "points_for_purchases", "name": "Earn 1 point per $1 spent", "description": "Get rewarded for every purchase", "rules": { "points_per_dollar": 1, "minimum_order": 10 }, "reward_rules": { "reward_type": "discount", "discount_amount": 5 }, "start_date": "2024-01-01", "end_date": null, "completion_progress": null }]}Get Single Rule
Retrieve a specific rule by ID. When a logged-in customer is detected, includes their completion progress.
Request
GET /apps/subscribfy-api/v1/loyalty/rules/{rule_id}Response
{"data": { "id": 456, "status": 1, "type": "punch_card", "name": "Buy 5 Get 1 Free", "description": "Complete 5 purchases to earn a free item", "rules": { "required_purchases": 5, "minimum_order_amount": 25 }, "reward_rules": { "reward_type": "free_product", "product_id": "gid://shopify/Product/123456" }, "start_date": "2024-01-01", "end_date": "2024-12-31", "completion_progress": { "current": 3, "required": 5, "percentage": 60 }}}Rule Types
| Type | Description |
|---|---|
birthday_reward | Reward on customer's birthday |
goal_spend | Reward when spending goal is reached |
points_for_purchases | Earn points for every purchase |
custom_action | Custom trigger-based rewards |
punch_card | Buy X get Y free |
create_account | Reward for account creation |
email_subscription | Reward for email opt-in |
sms_subscription | Reward for SMS opt-in |
anniversary_reward | Reward on membership anniversary |
social | Social media engagement rewards |
referral | Referral program rewards |
customer_tag | Tag-based automatic rewards |
reviews | Reward for product reviews |
upload_receipt | Receipt upload rewards |
membership_recharge_punch_card | Membership billing punch card |
product_recharge_punch_card | Subscription billing punch card |
Get Customer Coupons
Retrieve all coupons earned by a customer through the loyalty program.
Request
GET /apps/subscribfy-api/v1/loyalty/customers/{shopify_customer_id}/couponsQuery Parameters
Prop
Type
Example Request
curl "https://your-store.myshopify.com/apps/subscribfy-api/v1/loyalty/customers/7211677024514/coupons?status=1"Response
{"data": [ { "id": 789, "shopify_id": "gid://shopify/DiscountCodeNode/123456789", "discount_code": "LOYALTY-ABC123", "status": 1, "usage_count": 0, "expires_at": "2024-12-31T23:59:59Z", "deleted_at": null, "info": { "type": "amount_off_orders", "amount": 10, "rule_name": "Birthday Reward" }, "created_at": "2024-06-15T10:30:00Z", "updated_at": "2024-06-15T10:30:00Z" }]}Coupon Types
| Type | Description |
|---|---|
amount_off_products | Fixed amount off specific products |
amount_off_orders | Fixed amount off entire order |
buy_x_get_y | Buy X get Y discount |
free_shipping | Free shipping discount |
free_product | Free product added to order |
Response Fields
Rule Fields
Prop
Type
Coupon Fields
Prop
Type
Code Examples
class LoyaltyAPI {
constructor(store) {
this.baseUrl = `https://${store}/apps/subscribfy-api/v1/loyalty`;
}
async getRules(filters = {}) {
const params = new URLSearchParams(filters);
const response = await fetch(`${this.baseUrl}/rules?${params}`);
return response.json();
}
async getRule(ruleId) {
const response = await fetch(`${this.baseUrl}/rules/${ruleId}`);
return response.json();
}
async getCustomerCoupons(customerId, filters = {}) {
const params = new URLSearchParams(filters);
const response = await fetch(
`${this.baseUrl}/customers/${customerId}/coupons?${params}`
);
return response.json();
}
}
// Usage
const loyalty = new LoyaltyAPI('your-store.myshopify.com');
// Get all active rules
const rules = await loyalty.getRules({ status: 1 });
console.log(`Found ${rules.data.length} active rules`);
// Get punch card rules only
const punchCards = await loyalty.getRules({ type: 'punch_card', status: 1 });
// Get customer's active coupons
const coupons = await loyalty.getCustomerCoupons('7211677024514', { status: 1 });
coupons.data.forEach(coupon => {
console.log(`Code: ${coupon.discount_code}, Expires: ${coupon.expires_at}`);
});class LoyaltyAPI {
private $store;
public function __construct($store) {
$this->store = $store;
}
private function request($endpoint, $params = []) {
$url = "https://{$this->store}/apps/subscribfy-api/v1/loyalty{$endpoint}";
if (!empty($params)) {
$url .= '?' . http_build_query($params);
}
$response = file_get_contents($url);
return json_decode($response, true);
}
public function getRules($filters = []) {
return $this->request('/rules', $filters);
}
public function getRule($ruleId) {
return $this->request("/rules/{$ruleId}");
}
public function getCustomerCoupons($customerId, $filters = []) {
return $this->request("/customers/{$customerId}/coupons", $filters);
}
}
// Usage
$loyalty = new LoyaltyAPI('your-store.myshopify.com');
// Get active rules
$rules = $loyalty->getRules(['status' => 1]);
echo "Found " . count($rules['data']) . " active rules";
// Get specific rule with progress
$rule = $loyalty->getRule(123);
if ($rule['data']['completion_progress']) {
$progress = $rule['data']['completion_progress'];
echo "Progress: {$progress['current']}/{$progress['required']}";
}
// Get customer coupons
$coupons = $loyalty->getCustomerCoupons('7211677024514', ['status' => 1]);
foreach ($coupons['data'] as $coupon) {
echo "Code: {$coupon['discount_code']}";
}import requests
class LoyaltyAPI:
def __init__(self, store):
self.base_url = f'https://{store}/apps/subscribfy-api/v1/loyalty'
def get_rules(self, filters=None):
response = requests.get(f'{self.base_url}/rules', params=filters or {})
return response.json()
def get_rule(self, rule_id):
response = requests.get(f'{self.base_url}/rules/{rule_id}')
return response.json()
def get_customer_coupons(self, customer_id, filters=None):
response = requests.get(
f'{self.base_url}/customers/{customer_id}/coupons',
params=filters or {}
)
return response.json()
# Usage
loyalty = LoyaltyAPI('your-store.myshopify.com')
# Get active rules
rules = loyalty.get_rules({'status': 1})
print(f"Found {len(rules['data'])} active rules")
# Get points rules
points_rules = loyalty.get_rules({'type': 'points_for_purchases', 'status': 1})
# Get customer coupons
coupons = loyalty.get_customer_coupons('7211677024514', {'status': 1})
for coupon in coupons['data']:
print(f"Code: {coupon['discount_code']}, Expires: {coupon['expires_at']}")Liquid Integration
Display loyalty information in Shopify themes using Liquid:
Customer Points Balance
{% if customer.metafields.exison.loyalty_points %}
Your Points: {{ customer.metafields.exison.loyalty_points }}
{% endif %}Active Coupons
fetch('/apps/subscribfy-api/v1/loyalty/customers/{{ customer.id }}/coupons?status=1')
.then(r => r.json())
.then(data => {
data.data.forEach(coupon => {
console.log('Available coupon:', coupon.discount_code);
});
});Best Practices
- Cache rule listings - Rules don't change frequently; cache for 5-10 minutes
- Filter by status - Always filter by
status=1for customer-facing displays - Handle expiration - Check
expires_atbefore displaying coupons - Show progress - Use
completion_progressto motivate customers - Validate customer - Coupon endpoints require the customer to be logged in
Error Responses
| Status | Error | Cause |
|---|---|---|
| 403 | Forbidden | Customer not authorized to view this data |
| 404 | Not Found | Rule or customer does not exist |
| 422 | Validation Error | Invalid type or status parameter |
Questions? Contact support@subscribfy.com
Was this page helpful?