Store Credits
Store Credit Management API
Backend API for retrieving and updating customer store credit balances with full audit trail support.
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 |
|---|---|
| Base 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 | Required | Description |
|---|---|---|---|
key | string | Yes | Your Subscribfy API key |
cid | integer | Yes | Shopify Customer ID (numeric part of GID) |
email | string | Yes | Customer's email address (must match exactly) |
action | string | Yes | get or update |
Additional Parameters for action=update
| Parameter | Type | Required | Description |
|---|---|---|---|
update_value | float | Yes | Amount to adjust. Positive = add, Negative = deduct |
update_reason | string | Yes | Reason for the adjustment (required, non-empty) |
update_type | string | Yes | Type of adjustment (see Update Types) |
Update Types
| Type | Description |
|---|---|
manual admin adjustment | Manual adjustment by admin |
reconciled | Credit reconciliation/correction |
forfeited | Forfeited credits (e.g., policy violation) |
expired | 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.0,
"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_balanceshows 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
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'
);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'
);import requests
class 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 |
|---|---|
| Missing required parameters | Required parameters missing |
| Invalid API key | API key not found or invalid |
| Store not found | Store inactive or doesn't exist |
| Customer not found | Customer ID/email mismatch or not found |
| Invalid update value | Non-numeric value provided |
| Invalid update type | Unknown update type |
| Cannot add with this type | Positive value for negative-only type |
| Update failed | 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_checkoutwhen 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