Discount Codes

Learn how to take a percentage off a paid order when a shopper enters a Discount Code during checkout.

A Discount Code reduces what the shopper pays for products in your catalog. Gift Codes and Free Items grant a reward with no charge. A Discount Code applies to a one-time purchase of those paid products: Tokenz applies the percentage to each product's unit price, then calculates tax on the discounted prices and collects the result.

Create the campaign in the Tokenz Dashboard, then send the shopper to Tokenz Checkout. There they can add or remove a Discount Code before they pay.

Overview

A Discount Code campaign has:

Percentage: A percentage discount you set for the campaign, applied to the whole order.
Codes: one or more codes that share that percentage, the schedule, and the campaign limits
One code per order: a second code is rejected until the first is removed
One-time purchase: subscription checkouts and payment-gateway orders are rejected

Campaign setup and management

Create and manage Discount Code campaigns in the Tokenz Dashboard. If you do not see Discount Codes there yet, contact Tokenz support to confirm availability for your account.

In the Tokenz Dashboard, you can:

Name the campaign and describe it
Set the percentage, from 1 to 99
Add one or more codes that share that percentage
Set a campaign-wide redemption cap, a per-player cap, and a campaign budget
Set a redemption cap on an individual code, no higher than the campaign total
Publish, pause, resume, or end the campaign

Discount Code campaigns use the same statuses as Gift Code campaigns:

draft: Work in progress. Codes are rejected. All fields are editable.
scheduled: Published and queued. A code can be applied once the configured start time has been reached.
active: The campaign is live and a code can be applied.
paused: Manually paused. Codes are rejected. Can be resumed to active.
ended: The campaign is finished. Codes are rejected. This state is irreversible.

A Discount Code is active or deactivated. A deactivated code is rejected even when the campaign is active.

Player identifiers

Per-player limits use the player identifier on the checkout. Tokenz treats it as your identifier for the player and does not look it up in your game.

For a merchant-owned shop, pass the player identifier when you create the checkout. For the Tokenz Web Shop, Tokenz takes the player identifier from the shop session. A campaign with a per-player cap cannot be applied when the checkout has no player identifier.

Tokenz applies these rules when a per-player cap is enforced:

Leading and trailing whitespace is stripped
A blank value is rejected
The value can be at most 100 characters
The value is matched exactly, including letter case

Player identifiers are case-sensitive. Player_123 and player_123 are different players with separate allowances. Use one stable identifier, including capitalization, on every checkout for that player. A player who checks out from another device or session is still the same player when the identifier matches.

When the campaign has no per-player cap, a player identifier is optional. If you send one, Tokenz still records that player against the campaign.

What you send to checkout

Create the checkout with the paid products the shopper is buying. Include a player identifier when the campaign has a per-player cap, and whenever you want redemptions attributed to a player.

The product price is your selling price. A Discount Code does not create or change a price plan.

Coupons and points you include on the checkout are taken off the order before a Discount Code is applied. The code then takes its percentage off what remains. It does not replace those coupons or points, and they do not replace the code.

A ¥1,000 product with ¥100 of points is ¥900 before any Discount Code. Omit coupons and points when the shopper has none.

During checkout

In Tokenz Checkout, the shopper can enter a Discount Code, see the updated total, remove it, or replace it with another one. Only one Discount Code is active on the order at a time. Tokenz trims surrounding whitespace and matches the rest of the code exactly, including letter case.

When the shopper applies a code, Tokenz checks that it is valid and creates a reservation against your campaign limits and budget for that order. Removing the code releases the reservation and restores the price. A successful payment uses the reservation (the redemption and budget stay spent). If the order fails, is canceled, is blocked, or expires without payment, the reservation is released as well. See Reservations and limits.

On the example above, a 20% code takes ¥180 off the ¥900 that remains after points. The discounted amount before tax is ¥720, and tax is calculated on ¥720. The ¥100 of points stays on the order. The Discount Code's own amount is only its share, ¥180.

Price and tax

The percentage applies to each product's unit price before tax. Tokenz then uses your existing tax behavior. Rounding is per unit, so the total discount can differ slightly from one percentage of the order total.

Budget

The campaign budget is a cap on the total discount amount the campaign can give, in the budget currency. It is a campaign total, not a cap on a single order.

Applying a code includes a budget reservation for the full discount on that order, converted into the budget currency. If the remaining budget cannot cover that full amount, the code is rejected. Tokenz does not lower the percentage to fit the remainder.

A successful payment keeps that budget as spent. Removing the code, or the order failing, being canceled, blocked, or expiring, releases the budget reservation. A refund does not put the budget back.

What the percentage cannot do

The percentage stays inside 1–99. A code that would reduce the amount due to zero is rejected. Fixed amounts, a discount on one product only, a minimum order amount, a maximum discount per order, and more than one code on an order are outside this campaign type.

Reservations and limits

When a shopper applies a code in checkout, Tokenz creates a reservation for that order. The reservation counts toward your limits and budget immediately—it does not wait for payment. That way two shoppers cannot both pass a cap while checkout is still open.

For the life of that order, the reservation includes:

One redemption toward the campaign total
One redemption toward the code cap, when that code has its own cap
One redemption toward the per-player cap, when the checkout has a player identifier and the campaign has that cap
The discount amount toward the campaign budget

While the shopper has not paid yet, the reservation lasts 5 minutes. That window starts again when the order is waiting for payment again, including after a declined payment. While a payment is being processed, the reservation stays in place until that attempt succeeds, fails, or expires. If the 5 minutes pass and no payment is in progress, Tokenz releases the reservation and removes the code. The price returns to the amount without the Discount Code.

These are the limits the reservation counts against:

Campaign total: redemptions across every code and player. Once the cap is reached, further codes are rejected.
Code cap: redemptions of that one code, when the code has its own cap. The reservation counts against it for the life of the order, together with the campaign total. A code cap cannot be set higher than the campaign total.
Per-player cap: redemptions for one player. Once the cap is reached, that player is rejected. Other players are unaffected. A checkout with no player identifier is rejected when the campaign has this cap.

A code that fails validation creates no reservation.

Orders and refunds

When the order succeeds, it keeps the campaign, the code, the percentage, and the discount amount. Fulfill the paid products the way you already fulfill a successful order. There is no separate redemption notice and no reward to grant.

Refund the amount the shopper actually paid. A partial refund follows the discounted unit prices. Refunding an order does not restore the campaign total, the code cap, the per-player cap, or the budget.

When a code cannot be used

The shopper sees an error in checkout and the price stays unchanged. A code is rejected when:

The order already has a Discount Code. The shopper must remove it before entering another.
The checkout is for a subscription.
The order is a payment-gateway order. Discount Codes apply to merchant-of-record purchases.
The code would reduce the amount due to zero.
The campaign has a per-player cap and the checkout has no usable player identifier.
The checkout has no region, so tax cannot be recalculated.
Automatic tax is not configured on your account.
The order is no longer waiting for payment.
The code was not found for this account, or it belongs to the other mode (test versus live).
The code is not active.
The code has reached its own redemption cap.
The campaign is not available. This includes draft, paused, ended, and a scheduled campaign whose start time has not been reached.
The campaign is at or past its end time.
The code does not belong to a Discount Code campaign.
The campaign has reached its total redemption cap.
This player has reached the per-player cap.
The remaining campaign budget cannot cover the full discount for this order.

Testing

Use test mode while you try the campaign:

Create the campaign and its codes in the Tokenz Dashboard in test mode.
Test campaigns and codes are isolated from live data. A test checkout can only use a test code, and a live checkout can only use a live code.
In Tokenz Checkout, apply a code, remove it, and complete a test payment. The discounted total should appear while the code is on the order, disappear after the shopper removes it, and stay on a successful test order.