Developer 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.
Property Value Base URL {store}.myshopify.com/apps/subscribfy-api/v1/loyaltyMethod GETAuthentication Shopify App Proxy (automatic)
Endpoint Description GET /rulesList all loyalty rules GET /rules/{id}Get single rule with progress GET /customers/{shopify_id}Get customer loyalty data GET /customers/{shopify_id}/couponsGet customer's earned coupons
Retrieve all loyalty rules for the store, optionally filtered by type or status.
GET /apps/subscribfy-api/v1/loyalty/rules
Parameter Type Required Description typestring No Filter by rule type (see Rule Types) statusinteger No Filter by status: 1 = Active, 0 = Inactive
curl "https://your-store.myshopify.com/apps/subscribfy-api/v1/loyalty/rules?type=points_for_purchases&status=1"
{
"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
}
]
}
Retrieve a specific rule by ID. When a logged-in customer is detected, includes their completion progress.
GET /apps/subscribfy-api/v1/loyalty/rules/{rule_id}
{
"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
}
}
}
Type Description birthday_rewardReward on customer's birthday goal_spendReward when spending goal is reached points_for_purchasesEarn points for every purchase custom_actionCustom trigger-based rewards punch_cardBuy X get Y free create_accountReward for account creation email_subscriptionReward for email opt-in sms_subscriptionReward for SMS opt-in anniversary_rewardReward on membership anniversary socialSocial media engagement rewards referralReferral program rewards customer_tagTag-based automatic rewards reviewsReward for product reviews upload_receiptReceipt upload rewards membership_recharge_punch_cardMembership billing punch card product_recharge_punch_cardSubscription billing punch card
Retrieve all coupons earned by a customer through the loyalty program.
GET /apps/subscribfy-api/v1/loyalty/customers/{shopify_customer_id}/coupons
Parameter Type Required Description typestring No Filter by coupon type (see Coupon Types) statusinteger No Filter by status: 1 = Active, 0 = Inactive
curl "https://your-store.myshopify.com/apps/subscribfy-api/v1/loyalty/customers/7211677024514/coupons?status=1"
{
"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"
}
]
}
Type Description amount_off_productsFixed amount off specific products amount_off_ordersFixed amount off entire order buy_x_get_yBuy X get Y discount free_shippingFree shipping discount free_productFree product added to order
Field Type Description idinteger Internal rule ID statusinteger 1 = Active, 0 = Inactive typestring Rule type identifier namestring Display name descriptionstring Rule description rulesobject Rule configuration (varies by type) reward_rulesobject Reward configuration start_datestring Rule start date (YYYY-MM-DD) end_datestring|null Rule end date or null if ongoing completion_progressobject|null Customer's progress (if logged in)
Field Type Description idinteger Internal coupon ID shopify_idstring Shopify discount GID discount_codestring Code to apply at checkout statusinteger 1 = Active, 0 = Inactive usage_countinteger Times the coupon has been used expires_atstring|null Expiration timestamp infoobject Coupon details (type, amount, rule) created_atstring Creation timestamp updated_atstring Last update timestamp
JavaScript PHP Python
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' ] } " )
Display loyalty information in Shopify themes using Liquid:
{% if customer .metafields.exison.loyalty_points %}
Your Points: {{ customer .metafields.exison.loyalty_points }}
{% endif %}
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);
});
});
Cache rule listings - Rules don't change frequently; cache for 5-10 minutes
Filter by status - Always filter by status=1 for customer-facing displays
Handle expiration - Check expires_at before displaying coupons
Show progress - Use completion_progress to motivate customers
Validate customer - Coupon endpoints require the customer to be logged in
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