Paddle Billing
Search

Bill for non-catalog items

Charge for an item without adding it to your product catalog by passing price or product attributes when working with a transaction or a subscription.

As well as creating transactions for items in your product catalog, you can create transactions for non-catalog items. This is useful for one-off or bespoke items that are specific to that transaction. For example, you may agree a custom price with an enterprise customer.

You may also like to bill for non-catalog items if you work with products where the price changes often, or where you need to manage your product catalog outside of Paddle. For example, games companies typically manage their product catalog centrally because they need to work with app stores.

How it works

Transactions calculate and capture revenue in Paddle. To bill for an item, you add it to a transaction. There are two ways you can do this:

Using your product catalog

Create products and prices in Paddle, then pass prices IDs to transactions or Paddle.js to bill for them.

  • Manage items using the product catalog in Paddle.
  • Items can be reused across transactions easily.
  • Useful for companies who sell a set of digital products at the same price points.

For example:

  • SaaS companies who sell subscription plans and addons. Prices may vary by country, but items remain the same.
  • Companies who sell a selection of digital products or software licences where the items remain the same.

Billing for non-catalog items

Pass price and product attributes directly to a transaction when creating or updating to bill for them.

  • Manage items using your own product database.
  • Items are specific to a transaction.
  • Useful for companies with lots of items, or where item prices may change a lot.

For example:

  • Games companies who maintain a large catalog of items and may show different prices to different user segments.
  • eBook sellers, where publishers set prices and they may change daily.

How do non-catalog items relate to catalog items?

A complete product in Paddle is made up of a product entity that describes the item, and a related price entity that describes how much and how often a product is billed.

You can add non-catalog items to a transaction where:

  • Only the price is custom.

    This is great where the products you offer stay the same, but you might offer bespoke pricing from time to time. Your non-catalog price relates an existing catalog product entity in Paddle, sharing the same product name, image, and tax category.

  • Both the price and the product are custom.

    Where you manage your product catalog outside of Paddle, you can create entirely custom products. Your item uses a non-catalog price and a non-catalog product.

When you create or update a transaction with non-catalog items, Paddle creates a price entity and (optionally) a related product entity. They have a Paddle ID as normal, meaning you can use the get a product or get a price operations to work with them, but they're not added to your product catalog.

This means they're not returned by default when listing products or prices, and they're not shown in the Paddle dashboard.

Non-catalog price and product entities have a type of custom, so you can differentiate between entities in your catalog.

Subscriptions

This guide walks through adding non-catalog items to transactions, but you can also:

You can configure non-catalog items for a subscriptions in the same way as transactions.

Before you begin

Set your default payment link

To create a transaction, you'll need to first:

  • Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
  • Get your default payment link domain approved, if you're working with the live environment.

We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go live.

Bill for a non-catalog price for an existing product

You can add a non-catalog price for an existing product in your catalog to a transaction. In this case, the product you're billing for is the same, but you charge a specific price for it.

Add a custom price for a product to a transaction using the API in three steps:

  1. Build request

    Build a request that includes a list of items, where your item includes a price object.

  2. Preview your transaction (optional)

    Preview your transaction. Paddle returns a preview of the transaction, including tax and localized pricing. You may like to present this information to a customer, depending on your workflow.

  3. Create your transaction

    Send the request to create your transaction. Paddle creates it. Its status is draft or ready depending on the information you supplied.

Build request

Build an array of items, with an object containing a price object and quantity for each item.

Relate your custom price to an existing product in your catalog by including product_id with the Paddle ID of a product entity.

Recurring items on a transaction must have the same billing interval. For example, you can't have a transaction with some prices that are billed monthly and some products that are billed annually.

You may also include existing items by passing an object containing a price_id and quantity.

If you like, you can include customer, address, and business information to create a transaction that's ready for billing.

For a full list of the fields you can send when creating a transaction, see: Create a transaction

itemsarray[object]

List of items to charge for.

quantityinteger

Quantity of this item on the transaction.

priceobject

Price object for a non-catalog item to charge for. Include a product_id to relate this non-catalog price to an existing catalog price.

Preview request

Send a POST request to the /transactions/preview endpoint with the request you built.

POSThttps://api.paddle.com/transactions/preview

Send request

Send a POST request to the /transactions endpoint with the request you built.

POSThttps://api.paddle.com/transactions

Bill for a non-catalog price and a non-catalog-product

You can add a non-catalog price for a non-catalog product in your catalog to a transaction. This is useful if you manage your product catalog outside of Paddle, or you want to sell something entirely bespoke.

Add a custom price for a custom product to a transaction using the API in three steps:

  1. Build request

    Build a request that includes a list of items, where your item includes a price object with a product object.

  2. Preview your transaction (optional)

    Preview your transaction. Paddle returns a preview of the transaction, including tax and localized pricing. You may like to present this information to a customer, depending on your workflow.

  3. Create your transaction

    Send the request to create your transaction. Paddle creates it. Its status is draft or ready depending on the information you supplied.

Build request

Build an array of items, with an object containing a price object and quantity for each item.

Include a product object in your price object, with information about the product for this custom price.

Recurring items on a transaction must have the same billing interval. For example, you can't have a transaction with some prices that are billed monthly and some products that are billed annually.

You may also include existing items by passing an object containing a price_id and quantity.

If you like, you can include customer, address, and business information to create a transaction that's ready for billing.

For a full list of the fields you can send when creating a transaction, see: Create a transaction

itemsarray[object]

List of items to charge for.

quantityinteger

Quantity of this item on the transaction.

priceobject

Price object for a non-catalog item to charge for. Include a product object to create a non-catalog product for this non-catalog price.

Preview request

Send a POST request to the /transactions/preview endpoint with the request you built.

POSThttps://api.paddle.com/transactions/preview

Send request

Send a POST request to the /transactions endpoint with the request you built.

POSThttps://api.paddle.com/transactions

Update a non-catalog price or product

Non-catalog products and prices are created for specific transactions. They're not considered part of your product catalog. You shouldn't ordinarily need to update them.

Non-catalog products and prices have Paddle IDs, so you can update them using the update a product or update a price operations if needed. For example, you might correct a spelling error in a name or description — especially where an item is recurring.

See: Create products and prices

Add a non-catalog item to your catalog

If you find yourself adding similar non-catalog prices or products to transactions, you might like to add a custom item you've previously worked with to your product catalog.

We recommend that you create a new product or price in your catalog where you're adding an item to your standard offering.

You can also get an existing custom price or product using its ID, then change the type to standard.

Build request

Build a request that includes the type as standard.

The type field exists against both product and price entities.

typestring

Type of product or price. Standard products and prices are considered part of your product catalog and are shown on the Paddle dashboard.

Request

Send request

Send a PATCH request to the /products/{product_id} endpoint or the /prices/{price_id} endpoint with the request you built.

Response

If successful, Paddle returns a copy of the updated product or price entity. The type is standard, and it's now considered part of your product catalog.

Events

transaction.createdOccurs when a transaction is created initially. Other transaction events may follow, depending on the information included with your request.
price.createdOccurs when a custom price is created.
product.createdOccurs when a custom product is created.

Related pages