> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Set up and use Coupons
> Enable Coupons, configure Promotion Codes in Merchant Portal, and apply discounts through the API or Waffo Checkout.
A Coupon defines a discount rule. A Promotion Code is a customer- or Merchant-facing redemption code linked to a Coupon. Configure both in Merchant Portal, then apply the discount through the API or Waffo Checkout.
> [!NOTE]
>
> Coupon must be enabled by Waffo for each environment. Before integrating, contact your Waffo business or technical support representative and provide the Merchant ID and target environment.
## How it works
```mermaid theme={null}
flowchart LR
coupon["Coupon
Discount rule"] --> code["Promotion Code
Customer redemption credential"]
code --> result["Waffo Checkout or API
Apply the discount"]
coupon -->|Pass couponId through the API| result
```
## Supported scope
| Scope | Supported method | Notes |
| - | - | - |
| `ONE_TIME_PAYMENT` | `promotionInfo` in `POST /api/v1/order/create` | The Merchant can pass `promotionCode` or `couponId` |
| Waffo Checkout | Customer enters a `promotionCode` | Available for an enabled one-time payment order only when the Merchant did not apply a discount during order creation |
| `SUBSCRIPTION` | `promotionInfo` in `POST /api/v1/subscription/create` and `POST /api/v1/subscription/change` | The Merchant can pass `promotionCode` or `couponId`; the Coupon duration controls how long the discount applies |
| Merchant Portal | **Marketing → Coupons** and **Marketing → Promotion Codes** | Create, view, and manage Coupons and Promotion Codes |
## Configure Coupons in Merchant Portal
**1. Enable Coupon**
Ask Waffo to enable Coupon for your Sandbox or Production Merchant. Confirm each environment separately.
**2. Create a Coupon**
Log in to Merchant Portal, go to **Marketing → Coupons**, and configure the discount rule and scope as described below.
**3. Create a Promotion Code**
To let customers enter a redemption code, create a Promotion Code and link it to the Coupon. Create it from the Coupon details page, or create one or more codes from **Marketing → Promotion Codes**.
**4. Set redemption rules**
Configure redemption limits, first-transaction eligibility, minimum order amount, and expiration as needed, then save.
| Coupon setting | Rule |
| - | - |
| Coupon Name | Customer-visible; up to 40 characters |
| Percentage Off | Enter 1–100; 100% makes the order free |
| Fixed Amount Off | Configure a fixed discount for each supported currency; the Coupon cannot be used with an unconfigured currency |
| Duration | `Once` applies to one payment; `Repeating` applies to a specified number of Subscription billing periods; `Forever` applies to every Subscription billing period |
| Max Redemptions | Limits total redemptions across all Promotion Codes linked to the Coupon |
| Daily Redemption Limit | Limits how many times one customer can redeem the Coupon per day |
| Expiry Date | Prevents redemption after the specified date and time |
| Category Tags | Restricts eligible products; leave blank to allow all products |
| Metadata | Stores custom information from the Merchant |
You cannot change the discount type, amount, or duration after creating the Coupon. Review these settings before creation. You can continue to edit Coupon Name and Metadata. Deactivate or archive a Coupon to stop using it.
Configure a fixed discount amount for each supported currency.
Duration controls whether the discount applies once, for specified billing periods, or for every Subscription billing period.
If you cannot see the **Marketing** menu or a create button, ask your Merchant administrator to check your account permissions and contact Waffo to confirm that Coupon is enabled for that environment. Read-only accounts can view Marketing data but cannot create or edit it.
After creation, use **Marketing → Discount Analytics** to view redemptions, discount amount, average discount per order, redemption rate, and trends. You can filter or export the results by Coupon.
## Apply a Coupon through the API
`promotionInfo` accepts two mutually exclusive fields:
| Field | When to use it | Limit |
| - | - | - |
| `promotionInfo.promotionCode` | Your integration has a Promotion Code and should apply its linked Coupon | String, up to 64 characters |
| `promotionInfo.couponId` | Your integration has a specific Coupon instance ID and should apply that Coupon directly | String, up to 64 characters |
Pass only one field in each request. Do not send `promotionCode` and `couponId` together.
### One-time payment
Add `promotionInfo` to the [`POST /api/v1/order/create`](/docs/api-reference/order-create/create-new-order) request, and pass either `promotionCode` or `couponId`:
**promotionCode**
```json theme={null}
{
"orderCurrency": "USD",
"orderAmount": "100.00",
"promotionInfo": {
"promotionCode": "SAVE20"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT"
}
}
```
**couponId**
```json theme={null}
{
"orderCurrency": "USD",
"orderAmount": "100.00",
"promotionInfo": {
"couponId": "coupon_123"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT"
}
}
```
`orderAmount` is the order amount before the discount. After Waffo validates the Coupon, it recalculates the payable amount. In a [`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry) response, `originalAmount` is the pre-discount amount and `orderAmount` is the discounted Merchant order amount.
### Subscription
Add `promotionInfo` to a [`POST /api/v1/subscription/create`](/docs/api-reference/subscription-create/create-subscription) or [`POST /api/v1/subscription/change`](/docs/api-reference/subscription-change/subscription-change) request, and pass either `promotionCode` or `couponId`:
**promotionCode**
```json theme={null}
{
"currency": "USD",
"amount": "100.00",
"promotionInfo": {
"promotionCode": "SAVE20"
}
}
```
**couponId**
```json theme={null}
{
"currency": "USD",
"amount": "100.00",
"promotionInfo": {
"couponId": "coupon_123"
}
}
```
The Coupon duration determines whether the discount applies once, for a specified number of billing periods, or indefinitely. The Stripe adapter does not map Stripe Coupons or Promotion Codes to Waffo. To apply a discount, call the native Waffo Subscription API and pass `promotionInfo`.
## Let customers enter a Promotion Code in Waffo Checkout
To let a customer redeem a code, omit `promotionInfo` when creating the one-time payment order. The customer can enter a Promotion Code after opening `orderAction.webUrl`.
* Waffo shows the input only when Coupon is enabled for the Merchant and no discount was applied during order creation.
* Checkout accepts a Promotion Code, not a `couponId`.
* Waffo validates the Promotion Code, then recalculates and displays the payable amount.
* An invalid, expired, ineligible, or fully redeemed Promotion Code is rejected. The order does not silently continue at full price.
* If the Merchant applied a Coupon through the API, Checkout displays the discounted amount and hides the Promotion Code input.
## Refunds and payment results
* The maximum refundable amount is the discounted Merchant order amount, not the pre-discount amount.
* Treat the final state returned by a Webhook or inquiry endpoint as the payment result. Do not treat a browser redirect as proof of payment success.
* Store the `promotionCode` or `couponId` with your business order or Subscription so you can reconcile and troubleshoot the discount.
## Acceptance checklist
* Coupon is enabled for both Sandbox and the target Production Merchant.
* Authorized accounts can open **Coupons** and **Promotion Codes** in Merchant Portal and create and view records.
* One successful one-time payment uses `promotionCode`, and another uses `couponId`; each request contains only one field.
* A one-time payment without a pre-applied discount lets the customer enter a valid Promotion Code in Checkout and shows the recalculated amount.
* An invalid, expired, or ineligible Promotion Code shows an error and does not continue at full price.
* A Subscription create or change request applies a Coupon, and subsequent billing periods follow the configured Coupon duration.
* A Webhook or inquiry response confirms the final payment state. For a one-time payment, `originalAmount` and `orderAmount` match the pre-discount and post-discount amounts.
* The refund amount does not exceed the discounted Merchant order amount.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.