> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Bill one-time non-catalog items to a subscription

Bill a one-time item to a subscription without having to add it to your product catalog by passing price or product attributes.

---

## What's new?

We updated the Paddle platform so that now you can bill one-time charges to a subscription for [products](https://developer.paddle.com/api-reference/products/overview.md) and [prices](https://developer.paddle.com/api-reference/prices/overview.md) that aren't in your catalog.

{% callout type="info" %}
In a future update, we'll release functionality to let you work with recurring non-catalog items on subscriptions, too. This change is scheduled for Q1 2024.
{% /callout %}

## How it works

We [recently updated the Paddle platform](https://developer.paddle.com/changelog/2023/add-custom-items-transaction.md) so that you can create transactions for products and prices that aren't in your catalog. This update lets you bill non-catalog one-time charges to a subscription, too.

When [previewing or creating one-time charges for a subscription](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge.md), you can now pass price and product attributes directly.

Billing one-time [non-catalog items](https://developer.paddle.com/build/transactions/bill-create-custom-items-prices-products.md) to a subscription is great for one-off or bespoke items that are specific to that subscription. They let you manage your product catalog outside of Paddle.

It works in the same way that non-catalog items work when creating or updating a transaction, meaning 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

## Example

This example [bills a one-time charge](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge.md) for a non-catalog price for an existing product to a subscription.

### Create one-time charge

{% api-example method="POST" path="/subscriptions/{subscription_id}/charge" %}

```json {% title="Request" %}
{
  "effective_from": "immediately",
  "items": [
    {
      "price": {
        "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8",
        "description": "Loyalty offer 102",
        "name": "FLASH SALE Invigaron berries and seasonal skin",
        "unit_price": {
          "amount": "999",
          "currency_code": "USD"
        }
      },
      "quantity": 1
    }
  ]
}
```

{% /api-example %}

### Get related transaction

If successful, Paddle returns a preview of the updated subscription entity. The subscription entity doesn't include the item you just added. The `items` array only includes recurring items.

You can [send a follow-up request to get the related transaction that Paddle created](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge#get-charge.md) for this one-time charge.

{% api-example method="GET" path="/transactions?subscription_id={subscription_id}&origin=subscription_charge" %}

```json {% title="Response" %}
{
  "data": [
    {
      "id": "txn_01hj1992dn648813dfkw1kbt1x",
      "status": "completed",
      "customer_id": "ctm_01hh4fvwy9m5dz7s1qmxxk41b1",
      "address_id": "add_01hh4fvwyw5qj261rmjc32htx9",
      "business_id": null,
      "custom_data": null,
      "origin": "subscription_charge",
      "collection_mode": "automatic",
      "subscription_id": "sub_01hh4fwjc5w9hjrpf9mvechv5e",
      "invoice_id": "inv_01hj0y5zxygmr242ahsrcx9bmb",
      "invoice_number": "325-10333",
      "billing_details": null,
      "billing_period": {
        "starts_at": "2023-12-08T10:34:32.806947Z",
        "ends_at": "2024-01-08T10:34:32.806947Z"
      },
      "currency_code": "USD",
      "discount_id": null,
      "created_at": "2023-12-19T14:57:02.268791Z",
      "updated_at": "2023-12-19T14:57:05.783723Z",
      "billed_at": "2023-12-19T14:57:01.877466Z",
      "items": [
        {
          "price": {
            "id": "pri_01hj19929zp9h998zz1anjm8bq",
            "description": "Loyalty offer 102",
            "name": "FLASH SALE Invigaron berries and seasonal skin",
            "product_id": "pro_01he5kwnnvgdv2chtpgavk2rf8",
            "billing_cycle": null,
            "trial_period": null,
            "tax_mode": "account_setting",
            "unit_price": {
              "amount": "999",
              "currency_code": "USD"
            },
            "unit_price_overrides": [],
            "custom_data": null,
            "quantity": {
              "minimum": 1,
              "maximum": 100
            },
            "status": "active"
          },
          "quantity": 1
        }
      ],
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "999",
              "discount": "0",
              "tax": "89",
              "total": "1088"
            }
          }
        ],
        "totals": {
          "subtotal": "999",
          "tax": "89",
          "discount": "0",
          "total": "1088",
          "grand_total": "1088",
          "fee": "104",
          "credit": "0",
          "credit_to_balance": "0",
          "balance": "0",
          "earnings": "895",
          "currency_code": "USD"
        },
        "adjusted_totals": {
          "subtotal": "999",
          "tax": "89",
          "total": "1088",
          "grand_total": "1088",
          "fee": "104",
          "earnings": "895",
          "currency_code": "USD"
        },
        "payout_totals": {
          "subtotal": "999",
          "tax": "89",
          "discount": "0",
          "total": "1088",
          "credit": "0",
          "credit_to_balance": "0",
          "balance": "0",
          "grand_total": "1088",
          "fee": "104",
          "earnings": "895",
          "currency_code": "USD"
        },
        "adjusted_payout_totals": {
          "subtotal": "999",
          "tax": "89",
          "total": "1088",
          "fee": "104",
          "chargeback_fee": {
            "amount": "0",
            "original": null
          },
          "earnings": "895",
          "currency_code": "USD"
        },
        "line_items": [
          {
            "id": "txnitm_01hj1992sf3a3x5h5brk6p7xx3",
            "price_id": "pri_01hj19929zp9h998zz1anjm8bq",
            "quantity": 1,
            "totals": {
              "subtotal": "999",
              "tax": "89",
              "discount": "0",
              "total": "1088"
            },
            "product": {
              "id": "pro_01he5kwnnvgdv2chtpgavk2rf8",
              "name": "Invigaron berries pack",
              "description": null,
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/XBWZPsQoSc6YyViK5ocI_fire.png",
              "custom_data": null,
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "999",
              "tax": "89",
              "discount": "0",
              "total": "1088"
            }
          }
        ]
      },
      "payments": [
        {
          "payment_attempt_id": "b840a174-d28d-4d75-916b-f8c12a748588",
          "stored_payment_method_id": "d509416d-f8ec-4558-bfbc-7e2184bd6d8a",
          "amount": "1088",
          "status": "captured",
          "error_code": null,
          "method_details": {
            "type": "card",
            "card": {
              "type": "visa",
              "last4": "4242",
              "expiry_month": 1,
              "expiry_year": 2025,
              "cardholder_name": "Michael McGovern"
            }
          },
          "created_at": "2023-12-19T14:57:02.358501Z",
          "captured_at": "2023-12-19T14:57:03.652376Z"
        }
      ],
      "checkout": {
        "url": "https://aeroedit.com/pay?_ptxn=txn_01hj1992dn648813dfkw1kbt1x"
      }
    }
  ],
  "meta": {
    "request_id": "4ad70ade-89c1-4431-9c6f-901d6ccb9897",
    "pagination": {
      "per_page": 30,
      "next": "https://api.paddle.com/transactions?after=txn_01hj1992dn648813dfkw1kbt1x&origin=subscription_charge&subscription_id=sub_01hh4fwjc5w9hjrpf9mvechv5e",
      "has_more": false,
      "estimated_total": 1
    }
  }
}
```

{% /api-example %}

## 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 [bill one-time charges to a subscription](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge.md) using the API to start charging for non-catalog items.

This is part of a set of changes around non-catalog items. In a future update, we'll release functionality to let you work with recurring non-catalog items on subscriptions, too. This change is scheduled for Q1 2024.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `items[].price_id` | Field | updated | subscription | This field is no longer required if you include a price object instead. |
| `items[].price` | Field | added | subscription | You can send a price object instead of a price_id to bill for a non-catalog item. |