Developer API functions

Simple Store CreditUpdated September 14, 2026

The plugin exposes a small set of functions intended as a stable integration surface for other plugins and custom code. Everything below is a plain global function – there is no class to instantiate. Guard calls with function_exists() so your code degrades safely if the plugin is deactivated.

Reading a balance

// PHP
sscp_get_balance( $user_id = 0 );            // account balance only
sscp_get_total_voucher_credit( $user_id );   // sum of active voucher balances
sscp_get_available_credit( $user_id = 0 );   // account balance + vouchers
sscp_get_credit_debt( $user_id );            // outstanding clawback debt

Passing 0 (or omitting the argument) uses the current user. All amounts are returned as floats in the shop’s base currency.

Awarding credit

sscp_award_credit() is the recommended way to grant earned credit, because it honours the store’s configured delivery method rather than assuming a balance exists.

// PHP
$result = sscp_award_credit( $user_id, 10.00, array(
    'note'         => 'Survey completion reward',
    'source'       => 'earn',       // becomes the activity log type
    'order_id'     => 0,
    'delivery'     => 'account',    // 'account' or 'voucher'
    'expires_days' => 0,            // 0 uses the global expiry setting
) );

// $result = array( 'balance' => float, 'voucher_id' => int, 'delivery' => string, 'awarded' => float )

Check $result['awarded'] rather than assuming success. If a voucher could not be created the function falls back to the account balance, and on a voucher-only store where no fallback exists it returns 0 with a WP_Error under $result['error'].

Adjusting a balance directly

// PHP
sscp_add_credit( $user_id, 25.00, 'Goodwill gesture' );     // returns the new balance
sscp_deduct_credit( $user_id, 5.00, 'Manual correction' );  // clamps at zero

// All-or-nothing: returns false if the full amount is not available.
$ok = sscp_deduct_balance_if_available( $user_id, 40.00, 'spend', 'Booking fee' );

// Takes what it can and tells you how much was actually removed.
$taken = sscp_deduct_credit_capped( $user_id, 40.00, 'spend', 'Booking fee' );

Use sscp_deduct_balance_if_available() whenever you are gating an action on payment: it either takes the whole amount or does nothing, so you cannot end up granting something for a partial deduction. Use sscp_deduct_credit_capped() when a shortfall is acceptable but you need to record the true figure.

All three run their read-modify-write inside a per-user advisory lock, so concurrent requests cannot lose one another’s updates. Do not write _sscp_balance user meta directly – that bypasses the lock, the activity log and the expiry tracking.

Vouchers

// PHP
$voucher_id = sscp_create_voucher( array(
    'user_id'      => $user_id,   // 0 leaves the voucher unassigned
    'amount'       => 20.00,
    'source'       => 'admin',
    'note'         => 'Competition prize',
    'date_expires' => null,       // null uses the global voucher expiry
) );  // int on success, WP_Error on failure

sscp_get_voucher( $id_or_code );
sscp_get_user_vouchers( $user_id, 'active' );

History and formatting

// PHP
sscp_get_user_log( $user_id, $limit = 20, $offset = 0 );
sscp_credit_label();                  // the configured label, e.g. "Store Credit"
sscp_format_credit( $amount );        // formatted for the active currency
sscp_get_credit_delivery_method();    // 'account' or 'voucher'