create_discount
Create discounts in Paddle to reduce transaction totals using flat amounts, percentages, or per-unit pricing. Generate codes for customer checkout or apply manually during sales.
Instructions
This tool will create a new discount in Paddle.
Discounts reduce a transaction total. They're sometimes called coupons or promo codes.
Use discount codes to let customers apply discounts themselves at checkout, or apply discounts manually to transactions as part of the sales process.
Discounts can be added to a discount group to organize them. Only one discount group can be added at a time. List discounts by discount groups with the list_discount_groups tool to see which discounts are in which groups.
When selecting type, choose the one that best describes how to apply the discount to the total:
flat: Discounts a checkout or transaction by a flat amount, for example -$100. Requires currencyCode.
flat_per_seat: Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires currencyCode.
percentage: Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
When selecting mode, choose the one that best describes the use case:
standard: Standard discount. Can be considered part of the listed catalog and reused across transactions and subscriptions easily.
custom: Non-catalog discount. Custom, one-off discounts. Includes checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
Ensure you have all the information needed before making the call. Don't fabricate, imagine, or infer details and parameter values unless explicitly asked to. If anything is ambiguous, unknown, or unclear, ask the user for clarification or details before you proceed.
If successful, the response includes a copy of the new discount entity. Discounts can be applied to transactions, subscriptions, or passed to checkout through Paddle.js.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Short description for this discount. Not shown to customers. | |
| enabledForCheckout | No | Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). | |
| code | No | Unique code that customers can use to redeem this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive. If omitted and `enabledForCheckout` is `true`, Paddle generates a random 10-character code. | |
| type | Yes | Type of discount. Determines how this discount impacts the checkout or transaction total. | |
| mode | No | Discount mode. Standard discounts are considered part of the listed catalog and are shown in the Paddle dashboard. | |
| amount | Yes | Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. | |
| currencyCode | No | Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`. | |
| recur | No | Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). If omitted, defaults to `false`. | |
| maximumRecurringIntervals | No | Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. Subscription renewals, mid-cycle changes, and one-time charges billed to a subscription aren't considered a redemption. `timesUsed` is not incremented in these cases. | |
| usageLimit | No | Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times. Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, mid-cycle changes, and one-time charges aren't considered a redemption. | |
| restrictTo | No | Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. | |
| expiresAt | No | RFC 3339 datetime string of when this discount expires. Discount can no longer be redeemed after this date has elapsed. `null` if this discount can be redeemed forever. Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions. | |
| customData | No | Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties. |
Implementation Reference
- src/functions.ts:731-738 (handler)The handler function that implements the core logic of the 'create_discount' tool by calling the Paddle SDK's discounts.create method with the provided parameters.
export const createDiscount = async (paddle: Paddle, params: z.infer<typeof Parameters.createDiscountParameters>) => { try { const discount = await paddle.discounts.create(params); return discount; } catch (error) { return error; } }; - src/api.ts:67-67 (registration)Registration of the 'create_discount' tool method to its handler function (createDiscount) in the toolMap used by the PaddleAPI.
[TOOL_METHODS.CREATE_DISCOUNT]: funcs.createDiscount, - src/tools.ts:130-140 (schema)Tool definition including schema (parameters), description, name, and required actions for 'create_discount'.
{ method: "create_discount", name: "Create a discount", description: prompts.createDiscountPrompt, parameters: params.createDiscountParameters, actions: { discounts: { write: true, create: true, }, }, - src/constants.ts:59-59 (registration)Constant definition for the 'create_discount' tool method name.
CREATE_DISCOUNT: "create_discount",