DeveloperLoyalty & 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

PropertyValue
Base URL{store}.myshopify.com/apps/subscribfy-api/v1/loyalty
MethodGET
AuthenticationShopify App Proxy (automatic)

Available Endpoints

EndpointDescription
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

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

ParameterTypeRequiredDescription
typestringNoFilter by rule type (see Rule Types)
statusintegerNoFilter 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

TypeDescription
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

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

ParameterTypeRequiredDescription
typestringNoFilter by coupon type (see Coupon Types)
statusintegerNoFilter 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

TypeDescription
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

Response Fields

Rule Fields

FieldTypeDescription
idintegerInternal rule ID
statusinteger1 = Active, 0 = Inactive
typestringRule type identifier
namestringDisplay name
descriptionstringRule description
rulesobjectRule configuration (varies by type)
reward_rulesobjectReward configuration
start_datestringRule start date (YYYY-MM-DD)
end_datestring|nullRule end date or null if ongoing
completion_progressobject|nullCustomer's progress (if logged in)

Coupon Fields

FieldTypeDescription
idintegerInternal coupon ID
shopify_idstringShopify discount GID
discount_codestringCode to apply at checkout
statusinteger1 = Active, 0 = Inactive
usage_countintegerTimes the coupon has been used
expires_atstring|nullExpiration timestamp
infoobjectCoupon details (type, amount, rule)
created_atstringCreation timestamp
updated_atstringLast update timestamp

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

StatusErrorCause
403ForbiddenCustomer not authorized to view this data
404Not FoundRule or customer does not exist
422Validation ErrorInvalid type or status parameter

Questions? Contact support@subscribfy.com

On this page