Skip to main content

Loyalty API

Query loyalty rules, track customer progress, and retrieve earned coupons for storefront loyalty integrations.

Updated over a month ago

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

{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/rules

Query Parameters

Parameter

Type

Required

Description

type

string

No

Filter by rule type (see Rule Types)

status

integer

No

Filter by status: 1 = Active, 0 = Inactive

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}/coupons

Query Parameters

Parameter

Type

Required

Description

type

string

No

Filter by coupon type (see Coupon Types)

status

integer

No

Filter by status: 1 = Active, 0 = Inactive

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

Field

Type

Description

id

integer

Internal rule ID

status

integer

1 = Active, 0 = Inactive

type

string

Rule type identifier

name

string

Display name

description

string

Rule description

rules

object

Rule configuration (varies by type)

reward_rules

object

Reward configuration

start_date

string

Rule start date (YYYY-MM-DD)

end_date

string|null

Rule end date or null if ongoing

completion_progress

object|null

Customer's progress (if logged in)

Coupon Fields

Field

Type

Description

id

integer

Internal coupon ID

shopify_id

string

Shopify discount GID

discount_code

string

Code to apply at checkout

status

integer

1 = Active, 0 = Inactive

usage_count

integer

Times the coupon has been used

expires_at

string|null

Expiration timestamp

info

object

Coupon details (type, amount, rule)

created_at

string

Creation timestamp

updated_at

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=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


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

Did this answer your question?