Cart Credits Redemption API

Simplified API for applying store credits to orders in custom checkout flows or POS integrations.

A simplified API for applying store credits to orders in custom checkout flows or POS integrations. This endpoint handles credit reservation and provides transaction details for order attributes.

Endpoint

Property	Value
Base URL	`{store}.myshopify.com/apps/subscribfy-api/checkout/store-credits/use`
Method	`POST`
Content-Type	`application/x-www-form-urlencoded`

Parameters

Parameter	Type	Required	Description
`customer_id`	integer	Yes	Shopify customer ID
`cid`	integer	Yes	Same as customer_id (compatibility)
`customer_email`	string	Yes	Customer email address
`cart_total`	integer	Yes	Cart total in whole units (e.g., 140 for $140)
`st`	integer	Yes	Store credits to redeem (e.g., 20 for $20)
`exm`	integer	Yes	Fixed value: `5`
`for_pass_stores`	integer	Yes	Fixed value: `4633169`

Request Example

curl -X POST "https://your-store.myshopify.com/apps/subscribfy-api/checkout/store-credits/use" \
  -d "customer_id=6664481865927" \
  -d "cid=6664481865927" \
  -d "customer_email=customer@example.com" \
  -d "cart_total=140" \
  -d "st=20" \
  -d "exm=5" \
  -d "for_pass_stores=4633169"

Response

Success Response

{
  "_exm_st_amount": -12,
  "_exm_st_cid": 6664481865927,
  "_exm_st_id": 2314674,
  "_exm_st_key": "PVT",
  "_exm_st_t": 1740412734
}

Response Fields

Field	Type	Description
`_exm_st_amount`	integer	Validated credit amount (negative value)
`_exm_st_cid`	integer	Shopify customer ID
`_exm_st_id`	integer	Store credit transaction ID
`_exm_st_key`	string	Transaction key (internal use)
`_exm_st_t`	integer	Unix timestamp of transaction

Order Attributes

After a successful API response, add these attributes to the Shopify order for Subscribfy to process the redemption:

Attribute	Value
`subscribfy_store_credits_code`	`"StoreCredits"`
`subscribfy_store_credits`	Absolute value of `_exm_st_amount`
`subscribfy_store_credits_id`	Value of `_exm_st_id`

Example Order Attributes

{
  "subscribfy_store_credits_code": "StoreCredits",
  "subscribfy_store_credits": 12,
  "subscribfy_store_credits_id": 2314674
}

Code Examples

async function redeemStoreCredits(customerId, email, cartTotal, creditAmount) {
    const store = 'your-store.myshopify.com';
    const response = await fetch(
        `https://${store}/apps/subscribfy-api/checkout/store-credits/use`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: new URLSearchParams({
                customer_id: customerId,
                cid: customerId,
                customer_email: email,
                cart_total: cartTotal,
                st: creditAmount,
                exm: 5,
                for_pass_stores: 4633169
            })
        }
    );

    const data = await response.json();

    if (data._exm_st_amount) {
        // Store these for order attributes
        return {
            code: 'StoreCredits',
            amount: Math.abs(data._exm_st_amount),
            id: data._exm_st_id
        };
    }
    throw new Error('Failed to redeem credits');
}

// Usage
const redemption = await redeemStoreCredits(
    6664481865927,
    'customer@example.com',
    140,
    20
);
console.log(`Redeemed: $${redemption.amount}`);

// Add to order attributes when creating order
const orderAttributes = {
    subscribfy_store_credits_code: redemption.code,
    subscribfy_store_credits: redemption.amount,
    subscribfy_store_credits_id: redemption.id
};

function redeemStoreCredits($customerId, $email, $cartTotal, $creditAmount) {
    $store = 'your-store.myshopify.com';
    $url = "https://{$store}/apps/subscribfy-api/checkout/store-credits/use";

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query([
            'customer_id' => $customerId,
            'cid' => $customerId,
            'customer_email' => $email,
            'cart_total' => $cartTotal,
            'st' => $creditAmount,
            'exm' => 5,
            'for_pass_stores' => 4633169
        ]),
        CURLOPT_RETURNTRANSFER => true
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);

    if (!empty($data['_exm_st_amount'])) {
        return [
            'code' => 'StoreCredits',
            'amount' => abs($data['_exm_st_amount']),
            'id' => $data['_exm_st_id']
        ];
    }
    throw new Exception('Failed to redeem credits');
}

// Usage
$redemption = redeemStoreCredits(
    6664481865927,
    'customer@example.com',
    140,
    20
);

// Add to Shopify order attributes
$orderAttributes = [
    'subscribfy_store_credits_code' => $redemption['code'],
    'subscribfy_store_credits' => $redemption['amount'],
    'subscribfy_store_credits_id' => $redemption['id']
];

import requests

def redeem_store_credits(customer_id, email, cart_total, credit_amount):
    store = 'your-store.myshopify.com'
    url = f'https://{store}/apps/subscribfy-api/checkout/store-credits/use'

    response = requests.post(url, data={
        'customer_id': customer_id,
        'cid': customer_id,
        'customer_email': email,
        'cart_total': cart_total,
        'st': credit_amount,
        'exm': 5,
        'for_pass_stores': 4633169
    })

    data = response.json()

    if data.get('_exm_st_amount'):
        return {
            'code': 'StoreCredits',
            'amount': abs(data['_exm_st_amount']),
            'id': data['_exm_st_id']
        }
    raise Exception('Failed to redeem credits')

# Usage
redemption = redeem_store_credits(
    6664481865927,
    'customer@example.com',
    140,
    20
)

# Add to order attributes
order_attributes = {
    'subscribfy_store_credits_code': redemption['code'],
    'subscribfy_store_credits': redemption['amount'],
    'subscribfy_store_credits_id': redemption['id']
}

Customer Balance Metafield

You can display the customer's available balance using Liquid:

{% if customer.metafields.exison.exison_st %}
  Available Store Credits: ${{ customer.metafields.exison.exison_st }}
{% endif %}

Important Notes

st is positive - Request the amount to redeem as a positive number
_exm_st_amount is negative - Response returns negative value; use absolute value for order attributes
Fixed parameters - Always include exm=5 and for_pass_stores=4633169
Amount validation - API validates and may return less than requested if balance is insufficient
Order completion required - Credits are reserved until order is completed or abandoned

Flow Diagram

Customer enters credit amount
         ↓
Call API with parameters
         ↓
API validates and reserves credits
         ↓
Store response values
         ↓
Add attributes to Shopify order
         ↓
Order completes → Credits deducted
         OR
Order abandoned → Credits released

Error Handling

If the API returns an error or empty response:

Verify customer_id and email match
Check customer has sufficient balance
Ensure all required parameters are included
Verify the store domain is correct