Redemption Codes

Redemption codes let merchants distribute single-use or limited-use alphanumeric codes that customers can redeem to add a fixed or percentage-based credit directly to their wallet balance. Use them for promotions, gift campaigns, loyalty rewards, or refund alternatives.

Overview

Redemption codes are distinct from coupon codes applied at checkout. Instead of discounting an order, a redemption code deposits credit into the customer's wallet balance, which they can then spend across future orders. This makes them well-suited for:

• Welcome bonuses for new account holders
• Influencer or affiliate campaign codes
• Refund-as-credit offers (instead of reversing a payment)
• Gift cards distributed offline or via email
• Event or seasonal promotional campaigns

Each code tracks its own usage count, per-customer usage limit, expiry date, and redemption history. Codes that exceed their usage cap or expiry date are automatically rejected at the point of redemption.

How It Works

1. A merchant creates one or more codes in WooCommerce > WalletPro > Redemption Codes, specifying the credit value, usage limits, and optional expiry.
2. The merchant distributes the code via email, social media, printed materials, or any other channel.
3. The customer navigates to My Account > Wallet > Redeem a Code and enters the code.
4. WalletPro validates the code (active status, usage cap, expiry, per-customer limit, KYC gate if configured) and, on success, credits the wallet balance immediately.
5. A transaction record appears on the customer's wallet statement and in the merchant's audit ledger.

Creating Redemption Codes

Navigate to WooCommerce > WalletPro > Redemption Codes > Add New Code.

Click Save Code. The code appears in the codes list with its current redemption count and status.

Bulk Code Generation

To generate many unique codes at once (for example, to distribute individually in a mailer), use the Bulk Generate button on the Redemption Codes list screen. A modal appears with the following options:

• Number of Codes, how many unique codes to create (max 10,000 per batch)
• Code Prefix, optional string prepended to each generated code (e.g., SUMMER25-)
• Code Length, total character length of the random portion (8 to 24 characters)
• All other fields (credit type, limits, expiry) are shared across the batch

After generation, click Export CSV on the confirmation screen to download a spreadsheet of all generated codes.

Managing Existing Codes

The Redemption Codes list at WooCommerce > WalletPro > Redemption Codes shows:

• Code string
• Credit value
• Redeemed / Total Usage Limit counts
• Expiry date
• Status (Active / Inactive / Expired / Exhausted)

Use the Bulk Actions dropdown to activate, deactivate, or delete multiple codes at once. Use the Search field or status filter tabs to locate specific codes.

Clicking a code opens its edit screen, where you can adjust limits and expiry but cannot change the code string itself once it has been redeemed at least once.

Redemption History

Within each code's edit screen, a Redemption History table lists every redemption event:

To export the history for a single code, click Export History (CSV) in the Redemption History section header.

Rate Limiting

WalletPro applies rate limiting to the redemption endpoint to prevent brute-force code discovery. Configure the limits at WooCommerce > WalletPro > Settings > Redemption Codes:

Customer Experience

Redeeming a Code

1. Log in to the store and navigate to My Account > Wallet.
2. Locate the Redeem a Code section (displayed as a card below the balance summary).
3. Enter the code in the text field. The field is case-insensitive and ignores leading/trailing whitespace.
4. Click Apply Code.
5. On success, a confirmation message displays the credited amount and the updated wallet balance. The transaction appears immediately in the wallet statement.

If the code is invalid, expired, exhausted, or the customer has already reached their per-customer limit, a generic error message is shown: "This code could not be applied. Please check the code and try again."

Transaction Statement Entry

A successfully redeemed code creates a wallet transaction visible in the customer's statement with:

• Type: Redemption Code
• Description: Code redeemed: [CODE] (the code string is shown to the customer who redeemed it)
• Amount: credited value
• Running balance after credit

Settings Reference

All redemption code settings are at WooCommerce > WalletPro > Settings > Redemption Codes.

Developer Reference

REST API

Redemption code resources are available under the walletpro/v1 namespace. All endpoints require authentication via WooCommerce API keys or a logged-in nonce.

List Codes

# List all redemption codes (admin only)
GET /wp-json/walletpro/v1/redemption-codes

# Query parameters
# ?status=active|inactive|expired|exhausted
# ?per_page=25&page=1
# ?search=SUMMER

Create a Code

POST /wp-json/walletpro/v1/redemption-codes
Content-Type: application/json

{
  "code": "SUMMER25",
  "credit_type": "fixed",
  "credit_amount": "15.00",
  "currency": "USD",
  "usage_limit": 500,
  "usage_limit_per_user": 1,
  "expiry_date": "2026-08-31",
  "status": "active"
}

Response (201 Created):

{
  "id": 42,
  "code": "SUMMER25",
  "credit_type": "fixed",
  "credit_amount": "15.00",
  "currency": "USD",
  "usage_limit": 500,
  "usage_count": 0,
  "usage_limit_per_user": 1,
  "expiry_date": "2026-08-31T23:59:59+00:00",
  "status": "active",
  "created_at": "2026-06-20T10:00:00+00:00"
}

Redeem a Code (Customer)

POST /wp-json/walletpro/v1/redemption-codes/redeem
Content-Type: application/json
X-WP-Nonce: {nonce}

{
  "code": "SUMMER25"
}

Success response (200 OK):

{
  "success": true,
  "credit_applied": "15.00",
  "currency": "USD",
  "new_balance": "65.00",
  "transaction_id": 1087
}

Error response (422 Unprocessable Entity):

{
  "code": "walletpro_redemption_failed",
  "message": "This code could not be applied. Please check the code and try again.",
  "data": { "status": 422 }
}

Get Redemption History for a Code

GET /wp-json/walletpro/v1/redemption-codes/42/history?per_page=25&page=1

WP-CLI

# Create a redemption code
wp wallet code create --code=LAUNCH50 --type=fixed --amount=10.00 --limit=200 --expiry="2026-12-31"

# Generate 1000 unique codes in bulk
wp wallet code generate --count=1000 --prefix=GIFT- --type=fixed --amount=5.00 --export=./codes.csv

# Deactivate a code
wp wallet code update SUMMER25 --status=inactive

# Get usage stats for a code
wp wallet code get SUMMER25

# List all active codes with usage counts
wp wallet code list --status=active --format=table

# Manually redeem a code on behalf of a customer
wp wallet code redeem SUMMER25 --user=42

Hooks and Filters

Filter: Validate a code before redemption

/**
 * Add custom validation logic before a redemption code is applied.
 *
 * @param WP_Error|true $result   Pass WP_Error to reject, or true to allow.
 * @param array         $code_data  The code record from the database.
 * @param int           $user_id    The redeeming customer's user ID.
 */
add_filter( 'walletpro_validate_redemption_code', function( $result, $code_data, $user_id ) {
    // Example: require customer to have placed at least one order.
    $order_count = wc_get_customer_order_count( $user_id );
    if ( $order_count === 0 ) {
        return new WP_Error(
            'walletpro_no_prior_orders',
            'You must have placed at least one order to redeem this code.'
        );
    }
    return $result;
}, 10, 3 );

Action: After a code is successfully redeemed

/**
 * Fires after a redemption code is applied and wallet balance updated.
 *
 * @param int    $user_id        The customer who redeemed the code.
 * @param array  $code_data      The full code record.
 * @param string $credit_applied The amount actually credited.
 * @param int    $transaction_id The wallet transaction ID.
 */
add_action( 'walletpro_redemption_code_applied', function( $user_id, $code_data, $credit_applied, $transaction_id ) {
    // Example: tag the user in your CRM.
    my_crm_tag_user( $user_id, 'redeemed_code_' . $code_data['code'] );
}, 10, 4 );

Filter: Modify the credit amount before it is applied

/**
 * Adjust the credit amount for a redemption code.
 *
 * @param string $credit_amount  The calculated credit as a numeric string.
 * @param array  $code_data      The code record.
 * @param int    $user_id        The redeeming customer.
 * @return string                Modified credit amount.
 */
add_filter( 'walletpro_redemption_credit_amount', function( $credit_amount, $code_data, $user_id ) {
    // Example: double the credit for VIP customers.
    if ( in_array( 'vip_customer', (array) wp_get_current_user()->roles ) ) {
        $credit_amount = (string) ( (float) $credit_amount * 2 );
    }
    return $credit_amount;
}, 10, 3 );

Exporting Code Data

To export all codes and their redemption counts to CSV, go to WooCommerce > WalletPro > Redemption Codes, apply any filters you need (status, date range), then click Export Filtered Codes (CSV) in the screen toolbar.

The export includes: code string, credit type, credit amount, currency, usage limit, usage count, per-customer limit, expiry date, status, created date, and total credit value distributed to date.

Individual code redemption histories can also be exported from each code's edit screen (see Redemption History above). For a combined transaction-level export across all codes, use the GL-friendly CSV export at WooCommerce > WalletPro > Reports > Export Transactions and filter by transaction type Redemption Code.