Apply non-catalog discounts to a transaction

What's new?

We updated the Paddle API so you can create, update, or preview a transaction with a discount that isn't in your catalog.

How it works

Discounts can be applied to transactions to reduce the amount a customer has to pay. You can create discounts as part of promotions, or as a way to incentivize customers to upgrade or buy more.

Previously, you could only apply a discount from your catalog to transactions by providing the discount_id of that discount. Now, you can apply a non-catalog discount to a transaction by passing a discount object directly to the transaction when creating, updating, or previewing a transaction.

The discount object accepts a selection of the same fields used to create a catalog discount. If you provide a type of flat or flat_per_seat, you must also provide a currency_code on the transaction that specifies the currency for both the transaction and the discount.

Listing discounts won't return any non-catalog discounts. However, you can fetch non-catalog discounts individually through the API. Non-catalog discounts have a mode of custom.

When to use non-catalog discounts

Non-catalog discounts are one-off, non-transferable discounts which won't be listed in your discounts catalog. They're useful for when you have targeted discounts only valid for a specific customer on a specific transaction.

If your discount isn't intended to be broadly distributed and used, or you don't need to have a record of the discount to manage or track its performance, you should apply a non-catalog discount. For example, you might offer a discounted price on a high-profile customer's next transaction to prevent churn.

Examples

Request

This example creates a transaction with a non-catalog discount applied directly to the transaction. It includes a currency_code on the transaction because the discount type is flat.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
1{
2  "items": [
3    {
4      "quantity": 10,
5      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
6    }
7  ],
8  "customer_id": "ctm_01gzgmxdmgkgc7p94b5kgqq82p",
9  "address_id": "add_01gzkce0amtjsqv8xxd1rv3dna",
10  "currency_code": "GBP",
11  "discount": {
12    "type": "flat",
13    "description": "Custom loyalty discount",
14    "amount": "500",
15    "recur": true,
16    "maximum_recurring_intervals": 6
17  }
18}

Response

If successful, the response includes the new transaction entity. It includes the discount_id of the non-catalog discount applied to the transaction, and the amount discounted in details.totals.discount.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01gzkcdstcwq4cj8waj812v9my",
4    "status": "ready",
5    "customer_id": "ctm_01gzgmxdmgkgc7p94b5kgqq82p",
6    "address_id": "add_01gzkce0amtjsqv8xxd1rv3dna",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "automatic",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "GBP",
17    "discount_id": "dsc_01gy7s3d0n20p1m8b8q8v7e5k4",
18    "created_at": "2025-05-04T12:40:07.834144Z",
19    "updated_at": "2025-05-04T12:40:07.834144Z",
20    "billed_at": null,

This discount won't show when you list discounts but can be fetched individually using the discount_id.

Summary of changes

Fields

This is a summary of the changes to fields in the Paddle API and webhooks:

Next steps

This change is available in version 1 of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations.

Read more on discounts, non-catalog discounts, and how to apply discounts to transactions.

Related pages