Help
Promo codes and coupons
Issue a discount code your customers type in at checkout, on a one-time payment or a subscription, with a total-use cap and an optional per-customer cap, so a code can be generous without being abusable.
View as Markdown (for LLMs / AI agents)What it is
A promo code is a customer-facing string (like SUMMER20) that applies a discount defined by you: a percentage off, or a fixed amount off in your own settlement currency. Every payment link and Universal Checkout page you create can accept one, with a box the customer can expand and type into. Applying a valid code recalculates the total live, before they commit to paying.
Creating a code
From your dashboard, go to Promo codes and choose a code, a discount type, and how it applies:
1. Percentage or fixed amount
A percentage off the price, or a fixed amount off in your own settlement currency (a fixed discount only applies to a payment already in that same currency).
2. Where it can be used
One-time payments only, subscriptions only, or both - and on a subscription, whether the discount applies to just the first billing cycle or every renewal.
3. An expiry date
Optional. A code with no expiry stays valid until you pause or delete it yourself.
Total and per-customer limits
Two independent caps, either of which can be left blank for unlimited:
Max uses
A hard cap on how many times the code can be redeemed in total, across every customer. Once reached, the code stops applying for anyone, even someone who hasn't used it before.
Uses per customer
A separate cap on how many times the same customer can redeem it, identified by the phone number or email they check out with. Leave it blank for a code any one customer can reuse as many times as they like (up to the total cap, if you set one). Set it to 1 for a classic single-use-per-customer first-order discount, while still letting different customers each redeem it once.
Both caps are enforced at the moment a payment actually succeeds, not when the code is typed in - abandoning checkout after applying a code never counts against either limit.
One-time payments vs. subscriptions
A code that applies to subscriptions can discount just the first billing cycle, or every renewal for as long as the subscription stays active. A discount that would cover 100% of the price forever isn't allowed on a subscription (no payment rail can charge nothing on every renewal indefinitely) - restrict it to the first cycle only, or to one-time payments, instead.
What the customer sees
A collapsed "Have a promo code?" link on the checkout page expands into a field. Applying a valid code updates the price breakdown immediately - original price, the amount taken off, and the new total - before the customer commits to paying, on any payment method (mobile money, card, or PayPal).
Doing it by API
Everything above is also available over the API, so you can manage codes from your own backend instead of the dashboard:
POST /v1/business/promo-codes
X-API-Key: uk_live_...
{
"code": "SUMMER20",
"discount_type": "percentage",
"discount_value": 20,
"max_redemptions": 100,
"per_user_limit": 1,
"applies_to": "both",
"duration": "once"
}A customer applies it by passing promo_code on the checkout call, and the discount is recomputed and re-validated server-side at that exact moment - a client can never buy a bigger discount than the code actually allows.
A code per business you operate
Every promo code belongs to exactly one Ultraner business, keyed off the API key or dashboard login that created it. If you operate several businesses under Ultraner, each runs its own independent set of codes, its own limits, and its own redemption history - a code created for one never applies at another's checkout, even if you manage both. If people on your team need to create or manage codes without sharing your login, invite them with a role that includes promo code permissions from Team in your dashboard.