Store API

WalletPro extends the WooCommerce Store API (wc/store/v1) with a wallet namespace that exposes balance, top-up, and redemption data to Blocks-based checkouts and headless storefronts. This lets any client that can reach the Store API read a customer's wallet balance and apply wallet payments without coupling to the legacy shortcode checkout.

Overview

The WooCommerce Store API (/wp-json/wc/store/v1/) is the API surface consumed by the Blocks-based Cart and Checkout and by headless frontends. It is distinct from the authenticated Admin REST API (/wp-json/wc/v3/). WalletPro registers its extension into this namespace using WooCommerce's ExtendSchema mechanism, which injects namespaced data into existing endpoints without creating naming conflicts with other plugins.

WalletPro's Store API extension does two things:

• Injects wallet data (balance, currency, redemption eligibility) into the wc/store/v1/cart and wc/store/v1/checkout response objects under the extensions.walletpro key.
• Registers dedicated routes under wc/store/v1/walletpro/ for balance lookup, coupon/code redemption, and top-up initiation.

Authentication

Store API endpoints use the same nonce-based authentication as the core WooCommerce Store API. Obtain a nonce by calling the standard WooCommerce nonce endpoint or by reading the woocommerce-store-api-nonce value emitted in the page HTML by the Blocks runtime.

GET requests to balance endpoints use the active customer session cookie; no nonce is required to read balance.

Cart and Checkout Extension Data

WalletPro injects wallet context into the core cart and checkout responses. This data appears under response.extensions.walletpro and is available to custom Blocks, SlotFills, and headless clients reading these endpoints.

Extended Cart Response

Endpoint: GET /wp-json/wc/store/v1/cart

// Response, extensions key added by WalletPro
{
  "totals": { /* standard WooCommerce cart totals */ },
  "extensions": {
    "walletpro": {
      "balance": "42.50",
      "balance_minor": 4250,
      "currency_code": "USD",
      "currency_symbol": "$",
      "can_pay_full": true,
      "can_pay_partial": true,
      "applicable_amount": "29.99",
      "spending_limit": "100.00",
      "spending_limit_remaining_today": "57.50",
      "wallet_enabled": true,
      "gateway_id": "walletpro"
    }
  }
}

Extended Checkout Response

Endpoint: GET /wp-json/wc/store/v1/checkout

{
  "order_id": 0,
  "extensions": {
    "walletpro": {
      "balance": "42.50",
      "balance_minor": 4250,
      "step_up_required": false,
      "step_up_threshold": "50.00",
      "redemption_code_accepted": false,
      "redemption_code_value": null
    }
  }
}

Extension Schema Fields

Dedicated WalletPro Routes

These routes are registered under the Store API namespace. They follow the same nonce-based auth model as core Store API endpoints.

GET /wp-json/wc/store/v1/walletpro/balance

Returns the current customer's wallet balance. Uses the active session; no nonce required.

// Request
GET /wp-json/wc/store/v1/walletpro/balance

// Response 200
{
  "balance": "42.50",
  "balance_minor": 4250,
  "currency_code": "USD",
  "currency_symbol": "$",
  "currency_minor_unit": 2,
  "formatted": "$42.50"
}

Response codes: 200 OK | 401 Unauthorized (guest with no session) | 403 Forbidden (KYC gate active)

POST /wp-json/wc/store/v1/walletpro/apply-redemption

Validates and applies a redemption code to the current cart session. The code is consumed on successful payment; calling this endpoint only marks it as pending.

// Request
POST /wp-json/wc/store/v1/walletpro/apply-redemption
Nonce: <store-api-nonce>
Content-Type: application/json

{
  "code": "WELCOME25"
}

// Response 200, code valid
{
  "applied": true,
  "code": "WELCOME25",
  "credit_amount": "25.00",
  "credit_amount_minor": 2500,
  "expires_at": null,
  "message": "Code applied. $25.00 will be credited to your wallet on order completion."
}

// Response 422, code invalid or exhausted
{
  "code": "walletpro_invalid_code",
  "message": "This redemption code is invalid or has already been used.",
  "data": { "status": 422 }
}

DELETE /wp-json/wc/store/v1/walletpro/apply-redemption

Removes a previously applied redemption code from the current cart session without consuming it.

DELETE /wp-json/wc/store/v1/walletpro/apply-redemption
Nonce: <store-api-nonce>

// Response 200
{ "removed": true }

POST /wp-json/wc/store/v1/walletpro/topup/initiate

Initiates a wallet top-up order for the authenticated customer. Returns a checkout URL the client should redirect to, or a payment intent object for embedded payment UIs.

// Request
POST /wp-json/wc/store/v1/walletpro/topup/initiate
Nonce: <store-api-nonce>
Content-Type: application/json

{
  "amount": "50.00",
  "payment_method": "stripe",
  "return_url": "https://example.com/my-account/wallet/"
}

// Response 200
{
  "order_id": 1842,
  "checkout_url": "https://example.com/checkout/order-pay/1842/?key=wc_order_xKF7...",
  "amount": "50.00",
  "currency_code": "USD"
}

Registering Your Own Extension Data

If you are building a custom Block or headless feature that needs to read WalletPro data alongside your own plugin data, you can register an additional ExtendSchema endpoint on top of WalletPro's. The two namespaces are independent and both appear under extensions.

To extend the cart or checkout endpoint from your own plugin:

use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema;
use Automattic\WooCommerce\StoreApi\Schemas\V1\CartSchema;

add_action( 'woocommerce_blocks_loaded', function() {
    $extend = StoreApi::container()->get( ExtendSchema::class );

    $extend->register_endpoint_data([
        'endpoint'        => CartSchema::IDENTIFIER,
        'namespace'       => 'my_plugin',
        'data_callback'   => function() {
            // Return data to inject under extensions.my_plugin
            return [ 'loyalty_tier' => get_user_meta( get_current_user_id(), 'loyalty_tier', true ) ];
        },
        'schema_callback' => function() {
            return [
                'loyalty_tier' => [
                    'description' => 'Customer loyalty tier',
                    'type'        => 'string',
                    'context'     => [ 'view', 'edit' ],
                    'readonly'    => true,
                    'optional'    => true,
                ],
            ];
        },
        'schema_type'     => ARRAY_A,
    ]);
} );

The resulting cart response will contain both extensions.walletpro and extensions.my_plugin independently.

Applying Wallet Payment at Checkout

To charge a customer's wallet via the Blocks checkout, set payment_method to "walletpro" in the POST body sent to wc/store/v1/checkout. WalletPro's payment gateway handles the debit atomically during order processing.

// Full wallet payment
POST /wp-json/wc/store/v1/checkout
Nonce: <store-api-nonce>
Content-Type: application/json

{
  "billing_address": {
    "first_name": "Jane",
    "last_name":  "Smith",
    "email":      "jane@example.com",
    "address_1":  "123 Main St",
    "city":       "Portland",
    "state":      "OR",
    "postcode":   "97201",
    "country":    "US"
  },
  "shipping_address": { /* same shape */ },
  "payment_method": "walletpro",
  "payment_data": [
    { "key": "walletpro_apply_full", "value": true }
  ]
}

// Response 200
{
  "order_id": 1899,
  "status":   "processing",
  "payment_result": {
    "payment_status": "success",
    "redirect_url":   "https://example.com/checkout/order-received/1899/"
  },
  "extensions": {
    "walletpro": {
      "deducted_amount":    "29.99",
      "balance_after":      "12.51",
      "balance_after_minor": 1251
    }
  }
}

Partial Payment

When the cart total exceeds the wallet balance and partial payment is enabled (WooCommerce > WalletPro > Checkout > Allow partial payment), submit both a wallet and a second gateway:

{
  "payment_method": "walletpro",
  "payment_data": [
    { "key": "walletpro_apply_partial", "value": true },
    { "key": "walletpro_secondary_gateway", "value": "stripe" },
    { "key": "walletpro_secondary_payment_data", "value": { "stripe_payment_method": "pm_..." } }
  ]
}

Configuration

The Store API extension is active automatically when WalletPro is installed. The following settings in WooCommerce > WalletPro > Checkout affect Store API behavior:

Error Codes

All WalletPro Store API errors follow the WooCommerce Store API error envelope format: {"code": "...", "message": "...", "data": {"status": NNN}}.

JavaScript Usage Example

The following snippet shows how a custom Block inner component reads wallet balance from the cart extensions and displays it, using the WooCommerce Blocks @woocommerce/block-data store.

import { useSelect } from '@wordpress/data';
import { CART_STORE_KEY } from '@woocommerce/block-data';

const WalletBalance = () => {
    const walletExtensions = useSelect( ( select ) => {
        const cart = select( CART_STORE_KEY ).getCartData();
        return cart?.extensions?.walletpro ?? null;
    } );

    if ( !walletExtensions?.wallet_enabled ) return null;

    return (
        <div className="walletpro-balance-display">
            Wallet balance: { walletExtensions.formatted }
            { walletExtensions.can_pay_full && (
                <span>, covers this order in full</span>
            ) }
        </div>
    );
};

Compatibility Notes

• The Store API extension requires WooCommerce 8.2 or later and the Blocks package bundled with it. It does not require the standalone Blocks plugin.
• HPOS (High-Performance Order Storage) is supported. All order reads and writes in WalletPro Store API routes use the OrderUtil abstraction.
• Multi-currency wallets: if a customer holds balances in multiple currencies, the balance returned in extension data matches the currency of the current cart. Use the /balance route directly to query other currency balances.
• The Store API extension is independent of the WalletPro Admin REST API (walletpro/v1). Store API routes use session auth; Admin REST API routes require application passwords or OAuth.