Add non-catalog products and prices to a transaction
Charge for an item without having to add it to your product catalog by passing price or product attributes when working with 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:
Field | Change | Notes |
---|---|---|
transaction.items[].price_id | Validation change | This field is no longer required if you include a price object instead. |
transaction.items[].price | New field | You can send a price object instead of a price_id to bill for a non-catalog item. |
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.
12345678910111213141516171819201{
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"
If successful, Paddle responds with a copy of the new transaction entity.
The created transaction is draft
. You can pass this transaction to a checkout to capture customer and address information, and collect for payment.
12345678910111213141516171819201{
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 that must be paid manually.
12345678910111213141516171819201{
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",
If successful, Paddle responds with a copy of the new transaction entity.
The created invoice is ready
, since it includes all the required fields for it to be issued. Issue it to send it the customer.
12345678910111213141516171819201{
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.