Add non-catalog products and prices to a transaction

What's new?

We updated the Paddle platform so that now you can create transactions for products and prices that aren't in your catalog.

When creating or updating a transaction, you can now pass price and product attributes directly to a transaction, as well as passing existing price IDs.

In future updates, we'll release functionality to let you bill one-time non-catalog items to a subscription, then work with recurring non-catalog items on a subscription. These changes are scheduled for Q1 2024.

How it works

As well as creating transactions for items in your product catalog, you can create transactions for non-catalog items by passing a price and (optionally) a product object directly to a transaction when creating or updating.

Adding non-catalog items to a transaction is great for one-off or bespoke items that are specific to that transaction. They let you manage your product catalog outside of Paddle. When adding a custom item to a transaction, you can:

• Pass a price object for an existing product to charge for a custom price for a catalog product
• Pass a price object and a product object to charge for a custom price for a custom product

This means you have the flexibility to manage your catalog in the way that best suits the way that you work. For example:

• If you work with third-party app stores, you can manage your product catalog centrally and pass custom prices and products to transactions.
• When invoicing enterprise customers, you can agree custom prices for existing products when negotiating.
• You can use Paddle to bill for large product catalogs where prices may change daily, like eBook resellers or customers who may show personalized prices to different users.

Summary of changes to fields

Request bodies

This is a summary of the changes to fields in the Paddle API in request bodies:

Examples

Create a transaction for a one-time item

This example creates a draft transaction for a one-time non-catalog item. It's for a custom product.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "items": [
3    {
4      "quantity": 1,
5      "price": {
6        "description": "New user price (FTUE)",
7        "name": "Welcome price",
8        "unit_price": {
9          "amount": "999",
10          "currency_code": "USD"
11        },
12        "product": {
13          "name": "Invigaron Berries Hoard",
14          "tax_category": "standard",
15          "description": "Start the game with 20 extra seconds play time!"
16        }
17      }
18    }
19  ],
20  "currency_code": "USD"

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_01hj3s8yt41c6kaqm8rx9zfgtf",
4    "status": "draft",
5    "customer_id": null,
6    "address_id": null,
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": "USD",
17    "discount_id": null,
18    "created_at": "2023-12-20T14:15:04.47996325Z",
19    "updated_at": "2023-12-20T14:15:04.47996325Z",
20    "billed_at": null,

Create a transaction for a recurring item

This example creates a draft invoice for a 50-user enterprise plan. It's for an existing product, related using the product_id field.

Collection mode is manual, meaning this transaction is an invoice. Once issued, Paddle sends an invoice to your customer for manual collection.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "items": [
3    {
4      "quantity": 50,
5      "price": {
6        "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
7        "description": "Globex annual 2024",
8        "name": "Annual (per seat) deal for Globex",
9        "billing_cycle": {
10          "interval": "year",
11          "frequency": 1
12        },
13        "unit_price": {
14          "amount": "50000",
15          "currency_code": "USD"
16        }
17      }
18    }
19  ],
20  "customer_id": "ctm_01h8441jn5pcwrfhwh78jqt8hk",

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_01hj3ryktw234aj7s0wt5sp69g",
4    "status": "ready",
5    "customer_id": "ctm_01h8441jn5pcwrfhwh78jqt8hk",
6    "address_id": "add_01h848pep46enq8y372x7maj0p",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "manual",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": {
15      "enable_checkout": false,
16      "payment_terms": {
17        "interval": "day",
18        "frequency": 14
19      },
20      "purchase_order_number": "PO-2400",

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. You can continue creating transactions by passing price IDs for items in your product catalog. We recommend this for customers who sell a set of digital products at the same price points.

You can create or update transactions using the API to start charging for non-catalog items.

This is part of a set of changes around non-catalog items. In future updates, we'll release functionality to let you bill one-time non-catalog items to a subscription, then work with recurring non-catalog items on a subscription. These changes are scheduled for Q1 2024.

Learn more