Wbcom Credits SDK

WP Career Board overviewFree + ProGet WP Career Board →

Use this page to register a credit-spending feature, add a credit source, or read and write the credit ledger. The credit system is built on the Wbcom Credits SDK - a bundled library at libs/wbcom-credits-sdk/ (kept in libs/, not vendor/, so it always ships in the release zip). It provides:

An append-only ledger (the {prefix}_credit_ledger table; for this plugin the prefix is wcb, so wp_wcb_credit_ledger).
A consumer pattern (entities that spend credits - job posting, featured upgrade).
An adapter pattern for e-commerce plugins (WooCommerce, WC Subscriptions, WC Memberships, PMPro, MemberPress).
A gateway pattern for direct payment processors (Stripe, PayPal).

This doc covers the contract for registering a slug and writing your own consumer, adapter, or gateway.

Architecture

            +-------------------------------------------+
            |  Wbcom Credits SDK (libs/)                |
            |                                           |
            |  +--------------+                         |
            |  | Ledger       |  <- single source       |
            |  | (DB writes)  |     of truth            |
            |  +--------------+                         |
            |        ^                                  |
            |   +----+----+----------+                  |
            |   |         |          |                  |
            | Consumers  Adapters  Gateways             |
            | (job_post, (Woo,     (Stripe,             |
            |  featured)  WCS, WCM, PayPal -            |
            |             PMPro,   direct)              |
            |             MemberPress)                  |
            +-----^----------^----------^---------------+
                  |          |          |
              hold/deduct  on order  on webhook
              on actions   completed verified

Registering your slug with the SDK

A plugin registers everything (slug, prefix, consumers, settings) in one call on the wbcom_credits_sdk_registry action, which fires before the SDK loads. Pro does this in wp-career-board-pro.php:

add_action( 'wbcom_credits_sdk_registry', function ( \Wbcom\Credits\Registry $registry ) {
    $registry->register( array(
        'slug'      => 'wp-career-board',
        'prefix'    => 'wcb',              // table prefix: {wp}_wcb_credit_ledger
        'version'   => WCBP_VERSION,
        'file'      => WCBP_FILE,
        'user_type' => 'employer',
        'consumers' => array( /* see below */ ),
        'settings'  => array(
            'low_threshold'       => 5,
            'purchase_url'        => '',
            'admin_settings_hook' => 'wcb_admin_settings_tabs',
        ),
    ) );
} );

Consumers - what can spend credits

A “consumer” is something the SDK debits credits FOR. Each consumer declares three lifecycle actions: hold_on (reserve credits), deduct_on (settle the hold permanently), and refund_on (release the hold). The SDK adds the listeners; you fire the actions. The cost callback receives the item id and returns the credit cost.

Pro registers two consumers inside the consumers array of its register() call. Neither uses the hold_on / deduct_on / refund_on actions. Pro’s JobCharge class drives them from the job’s lifecycle instead, so every path is covered (auto-publish, approving a draft, resubmitting, changing board, bulk and command-line approval):

'consumers' => array(
    array(
        'id'    => 'job_post',
        'label' => __( 'Job Posting', 'wp-career-board-pro' ),
        // Priced for the job's author, never the current user.
        'cost'  => static function ( int $item_id ): int {
            $user_id  = (int) get_post_field( 'post_author', $item_id );
            $board_id = (int) get_post_meta( $item_id, '_wcb_board_id', true );
            $base     = $board_id > 0
                ? (int) ( ( new \WCB\Pro\Modules\Boards\BoardSettings() )->get( $board_id )['credit_cost'] ?? 0 )
                : 0;
            return (int) apply_filters( 'wcbp_consumer_cost', $base, $user_id, $item_id, $board_id, 'job_post' );
        },
    ),
    array(
        'id'    => 'featured_upgrade',
        'label' => __( 'Featured Upgrade', 'wp-career-board-pro' ),
        'cost'  => static function ( int $item_id ): int {
            $user_id = (int) get_post_field( 'post_author', $item_id );
            $base    = (int) get_option( 'wcbp_featured_upgrade_cost', 10 );
            return (int) apply_filters( 'wcbp_consumer_cost', $base, $user_id, $item_id, 0, 'featured_upgrade' );
        },
    ),
),

JobCharge places a hold when an employer submits a job (a 402 if the balance is short), settles it when the job goes live, and releases it when the job is rejected, trashed or deleted before it went live. Pro does not fire wcb_featured_upgrade_requested, _completed or _failed.

To add your own consumer, append another entry to the consumers array in your own register() call (or call $registry->register() again for a separate slug). The cost callback signature is function ( int $item_id ): int. Either give the entry hold_on, deduct_on and refund_on action names and fire those actions when the lifecycle events happen in your code, or drive the consumer yourself as JobCharge does. The SDK takes care of the ledger writes.

Adapters - automatic credit grants from e-commerce plugins

An “adapter” listens for a specific plugin’s purchase event and writes a topup ledger row. The SDK ships five adapters, which register themselves when their host plugin is active:

Adapter	File	Listens to
WooCommerce	`libs/wbcom-credits-sdk/src/Adapters/WooCommerce.php`	`woocommerce_order_status_completed` and `woocommerce_order_status_processing`
WC Subscriptions	`libs/wbcom-credits-sdk/src/Adapters/WooSubscriptions.php`	`woocommerce_subscription_payment_complete` and `woocommerce_subscription_renewal_payment_complete`
WC Memberships	`libs/wbcom-credits-sdk/src/Adapters/WooMemberships.php`	`wc_memberships_user_membership_status_changed`
Paid Memberships Pro	`libs/wbcom-credits-sdk/src/Adapters/PMPro.php`	`pmpro_after_change_membership_level` and `pmpro_subscription_payment_completed`
MemberPress	`libs/wbcom-credits-sdk/src/Adapters/MemberPress.php`	`mepr_event_transaction_completed`

Each adapter implements AdapterInterface (libs/wbcom-credits-sdk/src/Adapters/AdapterInterface.php). Note the methods are instance methods, not static:

interface AdapterInterface {
    public function get_id(): string;
    public function get_label(): string;
    public function is_available(): bool;             // host plugin active?
    public function register_hooks( string $slug ): void;
    public function get_mappable_items(): array;       // products/levels for the admin mapping UI
}

To add a new adapter (e.g. for Easy Digital Downloads), implement the interface, hook the host plugin’s purchase event in register_hooks(), and write a topup row with Credits::topup(). Register the adapter from the SDK’s wbcom_credits_register_adapters action, which passes the adapter registry and the slug:

namespace MyAddon\Credits;

use Wbcom\Credits\Adapters\AdapterInterface;
use Wbcom\Credits\Credits;

class EDD implements AdapterInterface {

    public function get_id(): string {
        return 'edd';
    }

    public function get_label(): string {
        return 'Easy Digital Downloads';
    }

    public function is_available(): bool {
        return class_exists( 'Easy_Digital_Downloads' );
    }

    public function register_hooks( string $slug ): void {
        add_action( 'edd_complete_purchase', function ( $payment_id ) use ( $slug ) {
            $user_id = (int) edd_get_payment_user_id( $payment_id );
            foreach ( edd_get_payment_meta_cart_details( $payment_id ) as $item ) {
                $credits = (int) $this->credits_for_product( $slug, (int) $item['id'] );
                if ( $credits > 0 ) {
                    // Signature: topup( $slug, $user_id, $amount, $note )
                    Credits::topup( $slug, $user_id, $credits, 'EDD order #' . $payment_id );
                }
            }
        });
    }

    public function get_mappable_items(): array {
        // Return EDD products in the shape the admin mapping UI expects.
        return array();
    }

    private function credits_for_product( string $slug, int $product_id ): int {
        $mappings = (array) get_option( "{$slug}_credit_mappings", array() );
        foreach ( $mappings as $row ) {
            if ( 'edd' === ( $row['adapter'] ?? '' ) && (int) $row['item_id'] === $product_id ) {
                return (int) $row['credits'];
            }
        }
        return 0;
    }
}

SDK REST routes

The SDK registers its own REST surface per registered slug, under the SDK’s own wbcom-credits/v1 namespace - separate from the plugin’s wcb/v1 namespace (Pro’s GET /wcb/v1/employers/{id}/credits, documented in 02-extending-free.md, is a thin Pro-side read of the same ledger, not part of this surface).

Registry::register() wires the REST class, which registers three routes:

GET   /wbcom-credits/v1/wp-career-board/balance   Current user's balance (or ?user_id= for an admin).
GET   /wbcom-credits/v1/wp-career-board/history   Paginated ledger entries (user_id, limit, offset; default limit 50).
POST  /wbcom-credits/v1/wp-career-board/topup     Admin manual credit change: { user_id, amount, note }. The amount is signed.

balance and history need a logged-in user reading their own data, or an administrator (manage_options) reading anyone’s through user_id. topup needs manage_options.

Gateways - direct payment processors

A “gateway” is for selling credits directly without an e-commerce plugin in between (Stripe Checkout, PayPal). The SDK ships two gateways: Stripe and PayPal (libs/wbcom-credits-sdk/src/Gateways/).

The SDK’s Webhook_Controller registers four more REST routes per slug, in the same wbcom-credits/v1 namespace:

POST  /wbcom-credits/v1/wp-career-board/checkout/{gateway}   Logged in. Create a hosted checkout session.
POST  /wbcom-credits/v1/wp-career-board/webhook/{gateway}    Public, provider-signed. Adjusts the ledger.
POST  /wbcom-credits/v1/wp-career-board/claim/{gateway}      Logged in. Credit a paid checkout when the buyer returns, body { session_id }.
POST  /wbcom-credits/v1/wp-career-board/refund/{gateway}     Administrator. Refund a prior checkout.

The webhook checks the gateway’s verify_signature() before it handles an event, so the request itself is authenticated by the provider signature. The claim route lets a site without a working webhook credit a paid checkout on return; the payment details come from the provider, not from the browser.

The browser side of checkout/{gateway} doesn’t need a hand-rolled fetch(): the SDK ships a reusable helper, assets/js/checkout.js, registered as the wbcom-credits-checkout script handle (once, however many plugins register) and localized with wbcomCreditsCfg = { restRoot, nonce }. Enqueue it where you render a buy button and call the global it exposes:

wp_enqueue_script( 'wbcom-credits-checkout' ); // Where the buy button renders.

// JS: on click
window.wbcomCreditsCheckout( {
    slug:      'wp-career-board',
    gateway:   'stripe',
    pack_id:   'pack_50',
    credits:   50,
    returnUrl: window.location.href,
} );
// POSTs to /{slug}/checkout/{gateway} with the REST nonce, then redirects
// the browser to the hosted checkout URL the SDK returns.
// Optional: billing (object) and coupon (string). Send pack_id or credits.

The same script exposes window.wbcomCreditsClaim( slug ), which calls the claim route when the page is a checkout return.

If you’re writing a custom gateway, implement GatewayInterface (libs/wbcom-credits-sdk/src/Gateways/GatewayInterface.php). Extend Abstract_Gateway, which supplies the webhook handling: you implement normalize_event() and the other interface methods, and do not override handle_webhook(). Register your gateway from the wbcom_credits_register_gateways action, which passes the gateway registry and the slug:

interface GatewayInterface {
    public function get_id(): string;
    public function get_label(): string;
    public function is_available(): bool;
    public function get_settings_fields(): array;
    public function create_checkout( string $slug, int $user_id, int $credits,
                                     int $price_cents, string $currency = 'USD',
                                     ?string $return_url = null ): string;
    public function verify_signature( string $raw_body, array $headers ): bool;
    public function normalize_event( array $payload ): ?Gateway_Event;
    public function handle_webhook( string $slug, array $payload ): \WP_REST_Response;
    public function refund( string $slug, string $session_id, ?int $amount_cents = null ): bool;
}

The ledger

Every credit movement writes one row. The table is named {wp_prefix}{prefix}_credit_ledger (for this plugin, wp_wcb_credit_ledger); the SDK creates one ledger table per registered prefix, so the table itself scopes the data and there is no slug column. Schema:

Column	Type	Notes
`id`	bigint unsigned PK	Auto-increment
`user_id`	bigint unsigned	The credit holder (employer)
`item_id`	bigint unsigned	The consumed entity (job, etc.); `0` for top-ups/adjustments
`entry_type`	varchar(20)	One of `topup`, `hold`, `deduction`, `refund`
`amount`	int	Signed: positive for `topup`/`refund`, negative for `hold`/`deduction`
`note`	varchar(255)	Free-form context string
`expires_at`	datetime, null	When the credits lapse; empty for never
`reason`	varchar(32)	What happened, such as `topup`, `purchase`, `spend` or `hold_release`
`reference`	varchar(191)	The order or session the row came from
`hold_id`	bigint unsigned	The hold this row settles or releases; `0` otherwise
`created_at`	datetime	Defaults to `CURRENT_TIMESTAMP`

The balance is the sum of amount for the user. Rows are only added, except that cancel_hold() deletes an open hold.

To read the ledger:

$balance = \Wbcom\Credits\Credits::get_balance( 'wp-career-board', $user_id );
$rows    = \Wbcom\Credits\Credits::get_ledger( 'wp-career-board', $user_id, 50 );
// or directly: \Wbcom\Credits\Ledger::get_history( 'wcb', $user_id, $limit, $offset )

Never INSERT/UPDATE the ledger directly - use the Credits helpers, which use these exact signatures:

Credits::topup(  string $slug, int $user_id, int $amount, string $note = '', ?string $expires_at = null, string $reason = 'topup', string $reference = '', int $item_id = 0 ): int|false;
Credits::hold(   string $slug, int $user_id, int $amount, int $item_id, string $note = '' ): int|false;
Credits::deduct( string $slug, int $user_id, int $amount, int $item_id, string $note = '' ): bool;
Credits::refund( string $slug, int $user_id, int $amount, int $item_id, string $note = '' ): int|false;
Credits::cancel_hold( string $slug, int $user_id, int $item_id ): void;
Credits::adjust( string $slug, int $user_id, int $amount, string $note = '' ): int|false;
Credits::get_cost( string $slug, string $consumer_id, int $item_id = 0 ): int;
Credits::get_purchase_url( string $slug ): string;

The 4th argument to topup() is a string note, not an array. Credits::deduct() settles an open hold: it writes a refund row that releases the held amount and a deduction row for the cost, in one transaction. It returns false when there is no open hold.

Where to read further

libs/wbcom-credits-sdk/src/ - the SDK source (bundled, not loaded over the network).
Pro hooks for credits in 03-hooks-reference.md: wcbp_consumer_cost (cost filter), wcbp_credit_consumed, wcbp_credits_low, and wcbp_credits_topped_up (re-emitted from the SDK’s wbcom_credits_deducted, wbcom_credits_low and wbcom_credits_topped_up).