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

# Add recurring non-catalog products and prices to a subscription

Add recurring items to a subscription without having to add them to your product catalog by passing price or product attributes when updating a subscription.

---

## What's new?

We updated the Paddle platform so that now you can add recurring items that aren't in your catalog when updating subscriptions.

## How it works

Recently, we [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. We followed that up with an update that lets you [bill non-catalog one-time charges to a subscription](https://developer.paddle.com/changelog/2023/bill-custom-items-one-time-subscription-charge.md).

With this update, you can pass price and product attributes directly when updating subscriptions, too. This means that you can work with both recurring and one-time non-catalog items on subscriptions.

Adding [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.

## Example

This example adds a new item for a non-catalog price for an existing product to a subscription, along with two catalog items that already existed on the subscription.

It includes `prorated_immediately` as the billing mode, meaning Paddle calculates a prorated charge for the new items and bills for it right away.

If successful, Paddle returns a copy of the updated subscription entity.

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

```json {% title="Request" %}
{
  "items": [
    {
      "quantity": 1,
      "price": {
        "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
        "description": "Reporting module",
        "name": "Reporting module with monthly specialist data export",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "unit_price": {
          "amount": "10000",
          "currency_code": "USD"
        }
      }
    },
    {
      "quantity": 10,
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    },
    {
      "quantity": 1,
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
    }
  ],
  "proration_billing_mode": "prorated_immediately"
}
```

```json {% title="Response" %}
{
  "data": {
    "id": "sub_01j48ynsppxshcen117ewqe8xy",
    "status": "active",
    "customer_id": "ctm_01j48yn43190mxmde4r6necxqn",
    "address_id": "add_01j48yn43gz7cbvjabnf1dpf8h",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-08-02T07:08:12.886Z",
    "updated_at": "2024-08-02T07:22:41.449Z",
    "started_at": "2024-08-02T07:08:12.117331Z",
    "first_billed_at": "2024-08-02T07:08:12.117331Z",
    "next_billed_at": "2024-09-02T07:08:12.117331Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-08-02T07:08:12.117331Z",
      "ends_at": "2024-09-02T07:08:12.117331Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2024-08-02T07:08:12.886Z",
        "updated_at": "2024-08-02T07:08:12.886Z",
        "previously_billed_at": "2024-08-02T07:08:12.117331Z",
        "next_billed_at": "2024-09-02T07:08:12.117331Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "product": {
          "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "name": "AeroEdit Pro",
          "type": "standard",
          "tax_category": "standard",
          "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": true,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:46.605Z",
          "updated_at": "2024-04-05T15:53:44.687Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-08-02T07:08:12.886Z",
        "updated_at": "2024-08-02T07:08:12.886Z",
        "previously_billed_at": "2024-08-02T07:08:12.117331Z",
        "next_billed_at": "2024-09-02T07:08:12.117331Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-12T10:42:45.476453Z"
        },
        "product": {
          "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "name": "Analytics addon",
          "type": "standard",
          "tax_category": "standard",
          "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-06-01T13:30:50.302Z",
          "updated_at": "2024-04-05T15:47:17.163Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-08-02T07:22:41.446Z",
        "updated_at": "2024-08-02T07:22:41.446Z",
        "previously_billed_at": "2024-08-02T07:22:41.446Z",
        "next_billed_at": "2024-09-02T07:08:12.117331Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01j48zg9w828t9ws6p87df240c",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "custom",
          "description": "Reporting module",
          "name": "Reporting module with monthly specialist data export",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2024-08-02T07:22:41.416924Z",
          "updated_at": "2024-08-02T07:22:41.416924Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "Reporting module",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get access to comprehensive reports and customizable analytics dashboards.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T13:58:17.615Z",
          "updated_at": "2024-04-05T15:44:02.893Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01j48ynsppxshcen117ewqe8xy/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01j48ynsppxshcen117ewqe8xy/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "6fce7595-fbfc-4dcb-acd0-415bf1e22813"
  }
}
```

{% /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 [update a subscription](https://developer.paddle.com/api-reference/subscriptions/update-subscription.md) using the API to start charging for non-catalog items.
## Summary of changes

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