Store Credit Management API

Manage and update customer store credits programmatically. Use this API to retrieve balances, add credits, or make adjustments from your backend systems.

Endpoint

Property	Value
URL	`https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php`
Method	`POST`
Content-Type	`application/x-www-form-urlencoded`

Authentication

All requests require your Subscribfy API key. From Shopify -> Subscribfy -> Integration > API.

Parameters

Required for All Requests

Parameter	Type	Description
`key`	string	Your Subscribfy API key
`cid`	integer	Shopify Customer ID (numeric part of GID)
`email`	string	Customer's email address (must match exactly)
`action`	string	`get` or `update`

Additional Parameters for action=update

Parameter	Type	Description
`update_value`	float	Amount to adjust. Positive = add, Negative = deduct
`update_reason`	string	Reason for the adjustment (required, non-empty)
`update_type`	string	Type of adjustment (see Update Types)

Update Types

Type	Allowed Values	Description
`manual admin adjustment`	Positive or negative	Manual adjustment by admin
`reconciled`	Negative only	Credit reconciliation/correction
`forfeit`	Negative only	Forfeited credits (e.g., policy violation)
`expired`	Negative only	Expired credits removal

Actions

Get Balance (action=get)

Retrieve a customer's current store credit balance.

curl -X POST "https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php" \
  -d "key=your_api_key" \
  -d "cid=123456789" \
  -d "email=customer@example.com" \
  -d "action=get"

Response:

{
  "gid": "123456789",
  "email": "customer@example.com",
  "store_credit_balance": 50.00,
  "store_credit_in_use_at_checkout": 0
}

Response Fields

Field	Type	Description
`gid`	string	Shopify Customer ID
`email`	string	Customer email
`store_credit_balance`	float	Available balance
`store_credit_in_use_at_checkout`	float	Credits reserved during active checkout

About store_credit_in_use_at_checkout

When a customer applies store credits at checkout, that amount is temporarily reserved to prevent double-spending:

Reserved credits appear in store_credit_in_use_at_checkout
store_credit_balance shows remaining available credit
If order completes: reserved credits are consumed
If checkout abandoned: reserved credits are released back to balance

Update Balance (action=update)

Add or deduct store credits from a customer's account.

curl -X POST "https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php" \
  -d "key=your_api_key" \
  -d "cid=123456789" \
  -d "email=customer@example.com" \
  -d "action=update" \
  -d "update_value=-10" \
  -d "update_reason=Store credit converted to gift card" \
  -d "update_type=reconciled"

Success Response:

{
  "gid": "123456789",
  "email": "customer@example.com",
  "store_credit_balance": 40.00,
  "result": {
    "status": "success"
  }
}

Code Examples

PHP

class SubscribfyStoreCredits {
    private $apiKey;
    private $endpoint = 'https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php';    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }    public function getBalance($customerId, $email) {
        return $this->request([
            'key' => $this->apiKey,
            'cid' => $customerId,
            'email' => $email,
            'action' => 'get'
        ]);
    }    public function addCredits($customerId, $email, $amount, $reason) {
        return $this->updateCredits($customerId, $email, abs($amount), $reason, 'manual admin adjustment');
    }    public function deductCredits($customerId, $email, $amount, $reason, $type = 'manual admin adjustment') {
        return $this->updateCredits($customerId, $email, -abs($amount), $reason, $type);
    }    private function updateCredits($customerId, $email, $value, $reason, $type) {
        return $this->request([
            'key' => $this->apiKey,
            'cid' => $customerId,
            'email' => $email,
            'action' => 'update',
            'update_value' => $value,
            'update_reason' => $reason,
            'update_type' => $type
        ]);
    }    private function request($data) {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->endpoint,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => http_build_query($data),
            CURLOPT_RETURNTRANSFER => true
        ]);
        $response = curl_exec($ch);
        curl_close($ch);
        return json_decode($response, true);
    }
}// Usage
$credits = new SubscribfyStoreCredits('your_api_key');// Get balance
$balance = $credits->getBalance('123456789', 'customer@example.com');
echo "Balance: $" . $balance['store_credit_balance'];// Add credits
$result = $credits->addCredits('123456789', 'customer@example.com', 25.00, 'Loyalty reward');// Deduct credits
$result = $credits->deductCredits('123456789', 'customer@example.com', 10.00, 'Converted to gift card', 'reconciled');

Node.js

const axios = require('axios');class SubscribfyStoreCredits {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.endpoint = 'https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php';
    }    async getBalance(customerId, email) {
        return this.request({
            key: this.apiKey,
            cid: customerId,
            email: email,
            action: 'get'
        });
    }    async addCredits(customerId, email, amount, reason) {
        return this.request({
            key: this.apiKey,
            cid: customerId,
            email: email,
            action: 'update',
            update_value: Math.abs(amount),
            update_reason: reason,
            update_type: 'manual admin adjustment'
        });
    }    async deductCredits(customerId, email, amount, reason, type = 'manual admin adjustment') {
        return this.request({
            key: this.apiKey,
            cid: customerId,
            email: email,
            action: 'update',
            update_value: -Math.abs(amount),
            update_reason: reason,
            update_type: type
        });
    }    async request(data) {
        const response = await axios.post(this.endpoint, new URLSearchParams(data));
        return response.data;
    }
}// Usage
const credits = new SubscribfyStoreCredits('your_api_key');// Get balance
const balance = await credits.getBalance('123456789', 'customer@example.com');
console.log(`Balance: $${balance.store_credit_balance}`);// Add credits
await credits.addCredits('123456789', 'customer@example.com', 25.00, 'Loyalty reward');// Deduct credits
await credits.deductCredits('123456789', 'customer@example.com', 10.00, 'Converted to gift card', 'reconciled');

Python

import requestsclass SubscribfyStoreCredits:
    def __init__(self, api_key):
        self.api_key = api_key
        self.endpoint = 'https://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php'    def get_balance(self, customer_id, email):
        return self._request({
            'key': self.api_key,
            'cid': customer_id,
            'email': email,
            'action': 'get'
        })    def add_credits(self, customer_id, email, amount, reason):
        return self._request({
            'key': self.api_key,
            'cid': customer_id,
            'email': email,
            'action': 'update',
            'update_value': abs(amount),
            'update_reason': reason,
            'update_type': 'manual admin adjustment'
        })    def deduct_credits(self, customer_id, email, amount, reason, update_type='manual admin adjustment'):
        return self._request({
            'key': self.api_key,
            'cid': customer_id,
            'email': email,
            'action': 'update',
            'update_value': -abs(amount),
            'update_reason': reason,
            'update_type': update_type
        })    def _request(self, data):
        response = requests.post(self.endpoint, data=data)
        return response.json()# Usage
credits = SubscribfyStoreCredits('your_api_key')# Get balance
balance = credits.get_balance('123456789', 'customer@example.com')
print(f"Balance: ${balance['store_credit_balance']}")# Add credits
credits.add_credits('123456789', 'customer@example.com', 25.00, 'Loyalty reward')# Deduct credits
credits.deduct_credits('123456789', 'customer@example.com', 10.00, 'Converted to gift card', 'reconciled')

Error Responses

Error	Cause
`{"error": "Bad request. Missing required fields."}`	Required parameters missing
`{"error": "Invalid api key."}`	API key not found or invalid
`{"error": "Store not found."}`	Store inactive or doesn't exist
`{"error": "Customer not found."}`	Customer ID/email mismatch or not found
`{"error": "Invalid update_value. Must be numeric."}`	Non-numeric value provided
`{"error": "Invalid update_type. Must be one of..."}`	Unknown update type
`{"error": "For 'reconciled', update_value must not be positive."}`	Positive value for negative-only type
`{"error": "Failed to update store credit: ..."}`	Internal error during update

Best Practices

Validate email match - Email must exactly match the customer record
Use descriptive reasons - Reasons appear in credit history for customer and admin
Check balance before deducting - Verify sufficient balance to avoid errors
Log all transactions - Keep records of API calls for reconciliation
Handle checkout reserves - Account for store_credit_in_use_at_checkout when showing available balance

Use Cases

Gift card conversion - Convert store credits to Shopify gift cards
External rewards - Sync credits from external loyalty programs
Bulk adjustments - Process credit adjustments from spreadsheets
Expiration management - Remove expired credits automatically
Customer service tools - Allow agents to adjust credits via custom UI

Store Credits

Collection API

Membership Management API

Softlogin Store Credits API

Cart Credits Redemption API