Subscribfy
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

PropertyValue
Base URLhttps://subscribfy.com/shopify-app/api/v1/store-credit-management-api.php
MethodPOST
Content-Typeapplication/x-www-form-urlencoded

Authentication

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

Parameters

Required for All Requests

ParameterTypeRequiredDescription
keystringYesYour Subscribfy API key
cidintegerYesShopify Customer ID (numeric part of GID)
emailstringYesCustomer's email address (must match exactly)
actionstringYesget or update

Additional Parameters for action=update

ParameterTypeRequiredDescription
update_valuefloatYesAmount to adjust. Positive = add, Negative = deduct
update_reasonstringYesReason for the adjustment (required, non-empty)
update_typestringYesType of adjustment (see Update Types)

Update Types

TypeDescription
manual admin adjustmentManual adjustment by admin
reconciledCredit reconciliation/correction
forfeitedForfeited credits (e.g., policy violation)
expiredExpired 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:

FieldTypeDescription
gidstringShopify Customer ID
emailstringCustomer email
store_credit_balancefloatAvailable balance
store_credit_in_use_at_checkoutfloatCredits 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

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

ErrorCause
Missing required parametersRequired parameters missing
Invalid API keyAPI key not found or invalid
Store not foundStore inactive or doesn't exist
Customer not foundCustomer ID/email mismatch or not found
Invalid update valueNon-numeric value provided
Invalid update typeUnknown update type
Cannot add with this typePositive value for negative-only type
Update failedInternal 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

On this page