Discounts & Promotions

​

What You Can Do

• Create coupons: a percentage or a fixed amount off, limited to some products, a total number of uses and an expiry, with a code customers type at checkout
• Hand out more promotion codes for the same coupon, each with its own customer restrictions — eligible emails, uses per customer, a minimum amount — one per influencer or campaign channel, or a batch of single-use codes
• Let customers type a code on the checkout page, share a product link with a code already applied, or apply a coupon or pre-fill a promotion code from your server when you create a checkout session

​

Coupons and Promotion Codes

​

Creating Coupons

​

Via Dashboard

​

Via API or SDK

import { CouponDiscountType, WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { coupon } = await client.coupons.create(
  {
    storeId: "STO_xxx",
    name: "Spring sale",
    discount: { type: CouponDiscountType.Percentage, percentOff: 20 },
    maxRedemptions: 500,
    code: "SPRING-20", // the coupon's own code; omit it for a random one
    // Promotion codes created together with the coupon (up to 20), each with its own restrictions
    promotionCodes: [{ code: "SPRING-NEW", restrictions: { perCustomerLimit: 1 } }],
  },
  { idempotencyKey: "coupon-spring-2026" },
);

// A code for one influencer: 100 uses, at least $50 before tax
await client.promotionCodes.create({
  couponId: coupon.id,
  code: "KOL-ALICE",
  restrictions: { maxRedemptions: 100, minimumAmount: { USD: "50.00" } },
});

res, err := client.Coupons.Create(ctx, pancake.CreateCouponParams{
    StoreID:        "STO_xxx",
    Name:           "Spring sale",
    Discount:       pancake.CouponDiscount{Type: pancake.CouponDiscountTypePercentage, PercentOff: pancake.Ptr(20.0)},
    MaxRedemptions: pancake.Ptr(500),
    Code:           pancake.Ptr("SPRING-20"),
    PromotionCodes: []pancake.CreateCouponPromotionCodeParams{{
        Code:         pancake.Ptr("SPRING-NEW"),
        Restrictions: &pancake.PromotionCodeRestrictions{PerCustomerLimit: pancake.Ptr(1)},
    }},
}, pancake.WithIdempotencyKey("coupon-spring-2026"))

​

Common Campaigns

await client.coupons.create({
  storeId: "STO_xxx",
  name: "Launch sale",
  code: "LAUNCH-20",
  discount: { type: CouponDiscountType.Percentage, percentOff: 20 },
  maxRedemptions: 500,
  redeemBy: "2026-11-15T00:00:00.000Z",
});

await client.promotionCodes.create({
  couponId: "CPN_xxx",
  code: "KOL-ALICE",
  restrictions: { maxRedemptions: 200, minimumAmount: { USD: "30.00" } },
});

const { promotionCodes } = await client.promotionCodes.generate({
  couponId: "CPN_xxx",
  count: 500,
  prefix: "NEWS-",
  restrictions: { maxRedemptions: 1 },
});

await client.promotionCodes.create({
  couponId: "CPN_xxx",
  code: "COMEBACK-30",
  restrictions: { customerEmails: ["jane.doe@example.com"], perCustomerLimit: 1 },
});

// In your server code, after checking the customer's tier
const session = await client.checkout.createSession({
  storeId: "STO_xxx",
  productId: "PROD_xxx",
  currency: "USD",
  couponId: tier === "gold" ? "CPN_gold" : undefined,
  buyerEmail: customer.email,
});
redirect(session.checkoutUrl);

await client.coupons.create({
  storeId: "STO_xxx",
  name: "Annual upgrade",
  code: "GO-ANNUAL",
  discount: { type: CouponDiscountType.Percentage, percentOff: 25 },
  duration: CouponDuration.Repeating,
  durationInPeriods: 3,
  productIds: ["PROD_annual"],
});

​

Applying Discounts at Checkout

​

Code Entry Field

const session = await client.checkout.createSession({
  productId: "PROD_xxx",
  currency: "USD",
  allowPromotionCodes: true,
});

​

Scenarios

​

Product Link with a Code

https://pancake.waffo.ai/store/{store-slug}/product/{productId}?currency=USD&discount_code=SPRING-20

​

Coupon Set by Your Server

const session = await client.checkout.authenticated.create({
  productId: "PROD_xxx",
  currency: "USD",
  buyerIdentity: "userIdInYourSystem",
  couponId: "CPN_xxx",
});

​

Promotion Code Set by Your Server

const session = await client.checkout.createSession({
  productId: "PROD_xxx",
  currency: "USD",
  promotionCode: "KOL-ALICE",
  allowPromotionCodes: true, // let the customer replace or remove it
});

​

When a Code Cannot Be Used

• For a guest checkout, only paid orders count toward the code’s total uses: the code is refused at entry only once its paid uses reach the limit. Unpaid orders and the per-customer limit are checked when the order is placed — if other customers’ unpaid orders hold the remaining uses, the order is refused then.
• For a signed-in customer, their own unpaid order with the same code does not count against the use limits — except an unpaid plan change that still holds the use: one already confirmed and waiting for its switch date, or one the current discount is being carried over to.
• A customer who leaves the payment page without paying can come back and enter the same code again. When they place the new order, it takes over the use held by their unpaid order.

​

Subscriptions

​

How Many Periods Are Discounted

​

Trials

​

When a Use Is Counted

• A use is counted once, when the first discounted charge succeeds: the first paid charge, or the trial charge for a paid trial. Renewals do not count again.
• Until then the subscription holds the use. If the subscription ends before that charge — canceled during a free trial, or its first payment never succeeds — the use is given back and the customer can use the code again. A subscription order left unpaid for more than 72 hours is not canceled, but it no longer holds the use: the next order that uses the same coupon, with any of its promotion codes, takes it back.
• If the coupon expires before that charge and the customer is charged the full price, the use is given back as well.
• A new order by the same customer with the same code takes over the use only from an earlier order that was never paid. An active subscription in its free trial keeps its hold: the new order does not take it over, and the held use counts toward the code’s limits.

​

When the Discount Ends

• When the duration runs out, renewals are charged the full price.
• The coupon’s expiry also ends discounts already on subscriptions: renewals after it are charged the full price, even with forever. A promotion code’s own expiry only stops new uses.
• Deactivating a coupon does not end discounts already on subscriptions until their next plan change — see Plan Changes.
• Canceling a subscription ends its discount for good. Undoing the cancellation before the period ends keeps the discount.
• A plan change ends the discount, unless it carries over to the new plan — see Plan Changes.

​

Plan Changes

• The first period. On a change that takes effect immediately, the new subscription’s first period costs the new plan’s price minus the credit for the unused part of the current period — or the amount you set with changeAmount or changeCreditAmount. When that is above zero, the discount applies to it and it uses up one period. The discount is worked out on the new plan’s full price, and then the credit is taken off: a percentage coupon takes its percentage of the new plan’s price, a fixed amount stays the same, and the discount is capped at the first period’s price, so the customer pays the first period’s price minus the discount, never below zero. A first period whose discount covers it in full still uses up one period. When it is zero — usually a downgrade whose credit covers the new plan — it takes no discount and uses no period, and the discount starts with the second period. A change that takes effect next period starts with a regular-price period, and a change that grants a trial follows the trial rules above.
• The credit is based on what the customer pays. The credit for the unused part of the current period is worked out from what that period costs the customer: the discounted amount when the period is discounted, the list price otherwise.
• A promotion code’s minimum amount is checked against the new plan’s regular price, before the discount and tax. The credit is not taken off.
• When a use is counted. A new code is counted when the first discounted charge of the new subscription succeeds — the first period, or the second period when the first is zero. If the change does not go through — the customer does not finish it, the payment channel reports it failed, or the change scheduled for next period is canceled — the use is given back. A change that is started but never completes stops holding its use after 72 hours, and the next order that uses the same coupon, with any of its promotion codes, takes it back — the same goes for a use being carried over to it from a subscription that has since ended. When the current subscription’s own code is still waiting for its first discounted charge, a discount that carries over takes that held use along to the new subscription; a new code or no code gives it back.

​

Amounts on Subscription Payments

• The subscription order keeps the list price. Each payment records what Pancake expects for that period: the original price, the discount and the amount to pay. The subscription.payment_succeeded webhook carries them in listPrice (listTotal, discountAmount, total).
• A charge that does not match the expected discount — the discount ended early, or the customer paid more or less — is reconciled by Pancake internally. The payment keeps the expected amounts; what was actually taken is in chargedAmount on the webhook.
• The first receipt — for the trial charge of a paid trial, or for the first charge without a trial — lists the original price, the discount, the subtotal, the tax and the amount paid when that charge is discounted. A free trial’s first receipt is for $0 and shows no breakdown.
• Each renewal receipt shows the same breakdown when its period is discounted. The first charge after a trial sends no renewal receipt — with a free trial, that is the first discounted period. The customer sees its expected amount in the upcoming-charge reminder.
• The next charge shown in emails includes the discount only when that period is still discounted.
• After a plan change, the new subscription’s first payment expects the first period’s amounts (see Plan Changes), but no receipt is sent for it. When the first period is zero, this first payment is a $0 payment; later payments expect the regular-period amounts. The customer gets a plan-changed email instead, which shows the new plan’s regular price before any discount, the next billing date, and the next charge amount — discounted when that period still gets the discount. It doesn’t show the first period’s amount or a discount breakdown. The payment record keeps the first period’s amounts. Later renewals get receipts as described above.

​

Amounts, Receipts and Usage

• The discount applies to the tax-inclusive price. A percentage discount is rounded down to the currency’s smallest unit; a fixed amount never takes the total below zero, and a 100% discount produces a free order.
• Orders, payments, receipts and the Dashboard show three amounts: the original price, the discount, and what the customer paid. Refunds are capped at what the customer paid.
• An order’s price snapshot keeps the list price. Its total is the tax-inclusive price before the discount, for one-time and subscription orders alike. The discounted amount of each charge is on the payment (snapshotAmountDetails.total).
• A discounted receipt lists the original price, the discount, the subtotal (after the discount, excluding tax), the tax and the amount paid. The subtotal and tax lines appear only when tax applies.
• A use is counted when the payment succeeds — for a subscription, the first discounted charge (see Subscriptions). A canceled or expired order gives the use back, so the customer can use the code again. A refund does not give the use back.

​

Next Steps