Loyalty API
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 |
|
Method |
|
Authentication | Shopify App Proxy (automatic) |
Available Endpoints
Endpoint | Description |
| List all loyalty rules |
| Get single rule with progress |
| Get customer loyalty data |
| 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/rules
Query Parameters
Parameter | Type | Required | Description |
| string | No | Filter by rule type (see Rule Types) |
| integer | No | Filter by status: |
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 |
| Reward on customer's birthday |
| Reward when spending goal is reached |
| Earn points for every purchase |
| Custom trigger-based rewards |
| Buy X get Y free |
| Reward for account creation |
| Reward for email opt-in |
| Reward for SMS opt-in |
| Reward on membership anniversary |
| Social media engagement rewards |
| Referral program rewards |
| Tag-based automatic rewards |
| Reward for product reviews |
| Receipt upload rewards |
| Membership billing 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}/coupons
Query Parameters
Parameter | Type | Required | Description |
| string | No | Filter by coupon type (see Coupon Types) |
| integer | No | Filter by status: |
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 |
| Fixed amount off specific products |
| Fixed amount off entire order |
| Buy X get Y discount |
| Free shipping discount |
| Free product added to order |
Response Fields
Rule Fields
Field | Type | Description |
| integer | Internal rule ID |
| integer | 1 = Active, 0 = Inactive |
| string | Rule type identifier |
| string | Display name |
| string | Rule description |
| object | Rule configuration (varies by type) |
| object | Reward configuration |
| string | Rule start date (YYYY-MM-DD) |
| string|null | Rule end date or null if ongoing |
| object|null | Customer's progress (if logged in) |
Coupon Fields
Field | Type | Description |
| integer | Internal coupon ID |
| string | Shopify discount GID |
| string | Code to apply at checkout |
| integer | 1 = Active, 0 = Inactive |
| integer | Times the coupon has been used |
| string|null | Expiration timestamp |
| object | Coupon details (type, amount, rule) |
| string | Creation timestamp |
| string | Last update timestamp |
Code Examples
JavaScript
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}`); });
PHP
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']}
"; }
Python
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 %} <p>Your Points: ##{{ customer.metafields.exison.loyalty_points }}</p> {% endif %}
Active Coupons
<script> 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); }); }); </script>
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 displaysHandle expiration - Check
expires_atbefore displaying couponsShow progress - Use
completion_progressto motivate customersValidate 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