Add recurring non-catalog products and prices to 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 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.

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

PATCH /subscriptions/{subscription_id}

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"
}

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"
  }
}

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 using the API to start charging for non-catalog items.

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

Add recurring non-catalog products and prices to a subscription

What's new?

How it works

Example

Next steps

Summary of changes

Was this page helpful?