# PATCH /subscriptions/{subscription_id}

**Update a subscription**

Updates a subscription using its ID.

When making changes to items or the next billing date for a subscription, you must include the `proration_billing_mode` field to tell Paddle how to bill for those changes.

Send the complete list of items that you'd like to be on a subscription — including existing items. If you omit items, they're removed from the subscription.

For each item, send `price_id` and `quantity`. Paddle responds with the full price object for each price. If you're updating an existing item, you can omit the `quantity` if you don't want to update it.

If successful, your response includes a copy of the updated subscription entity. When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed.

**Required permissions:** `subscription.write`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscription_id` | string | required | Paddle ID of the subscription entity to work with. |

## Request body

- `customer_id`: string — Paddle ID of the customer that this subscription is for, prefixed with `ctm_`. Include to change the customer for a subscription. (pattern: `^ctm_[a-z\d]{26}$`)
- `address_id`: string — Paddle ID of the address that this subscription is for, prefixed with `add_`. Include to change the address for a subscription. (pattern: `^add_[a-z\d]{26}$`)
- `business_id` — Paddle ID of the business that this subscription is for, prefixed with `biz_`. Include to change the business for a subscription.
- `currency_code`: string — Supported three-letter ISO 4217 currency code. Include to change the currency that a subscription bills in. When changing `collection_mode` to `manual`, you may need to change currency code to `USD`, `EUR`, or `GBP`.
- `next_billed_at`: string (date-time) — RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date.
- `discount` — Details of the discount applied to this subscription. Include to add a discount to a subscription. `null` to remove a discount.
- `collection_mode`: string — How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices.
- `billing_details` — Details for invoicing. Required if `collection_mode` is `manual`. `null` if changing `collection_mode` to `automatic`.
- `scheduled_change`: null — Change that's scheduled to be applied to a subscription. When updating, you may only set to `null` to remove a scheduled change. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes.
- `items`: array — List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items to retain. (Items: 1–100)
- `custom_data` — Your own structured key-value data.
- `proration_billing_mode`: string — How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making
changes that impact billing.

For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that
collects for payment immediately is used.
- `on_payment_failure`: string — How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`.

### Request example

```json
{
  "items": [
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
      "quantity": 20
    },
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
      "quantity": 1
    },
    {
      "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
      "quantity": 1
    }
  ],
  "proration_billing_mode": "prorated_immediately"
}
```

## Response (200)

- `data`: object (required) — Represents a subscription entity.
  - `id`: string (required) — Unique Paddle ID for this subscription entity, prefixed with `sub_`. (pattern: `^sub_[a-z\d]{26}$`)
  - `status`: string (required) — Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.
  - `customer_id`: string (required) — Paddle ID of the customer that this subscription is for, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`)
  - `address_id`: string (required) — Paddle ID of the address that this subscription is for, prefixed with `add_`. (pattern: `^add_[a-z\d]{26}$`)
  - `business_id` (required) — Paddle ID of the business that this subscription is for, prefixed with `biz_`.
  - `currency_code`: string (required) — Supported three-letter ISO 4217 currency code. Transactions for this subscription are created in this currency. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `started_at` (required) — RFC 3339 datetime string of when this subscription started. This may be different from `first_billed_at` if the subscription started in trial.
  - `first_billed_at` (required) — RFC 3339 datetime string of when this subscription was first billed. This may be different from `started_at` if the subscription started in trial.
  - `next_billed_at` (required) — RFC 3339 datetime string of when this subscription is next scheduled to be billed.
  - `paused_at` (required) — RFC 3339 datetime string of when this subscription was paused. Set automatically by Paddle when the pause subscription operation is used. `null` if not paused.
  - `canceled_at` (required) — RFC 3339 datetime string of when this subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. `null` if not canceled.
  - `discount` (required) — Details of the discount applied to this subscription.
  - `collection_mode`: string (required) — How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices.
  - `billing_details` (required) — Details for invoicing. Required if `collection_mode` is `manual`.
  - `current_billing_period` (required) — Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. `null` for `paused` and `canceled` subscriptions.
  - `billing_cycle`: object (required) — How often this subscription renews. Set automatically by Paddle based on the prices on this subscription.
    - `interval`: string (required) — Unit of time.
    - `frequency`: integer (required) — Amount of time. (Min: 1)
  - `scheduled_change` (required) — Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. `null` if no scheduled changes.
  - `management_urls`: object (required) — Customer portal deep links for this subscription.

Authenticated links are only returned when your API key has Customer portal session (Write) permission. For security, the `token` appended to authenticated links is temporary. You shouldn't store them.
    - `update_payment_method` (required) — Link to the page for this subscription in the customer portal with the payment method update form pre-opened. Use as part of workflows to let customers update their payment details. `null` for manually-collected subscriptions.
    - `cancel`: string (uri) (required) — Link to the page for this subscription in the customer portal with the subscription cancellation form pre-opened. Use as part of cancel subscription workflows.
  - `items`: array (required) — List of items on this subscription. Only recurring items are returned. (Items: 1–100)
  - `custom_data` (required) — Your own structured key-value data.
  - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported.
  - `consent_requirements`: array (required) — List of active consent requirements for the subscription's current billing period.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```json
{
  "data": {
    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
    "status": "active",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T10:38:00.761Z",
    "updated_at": "2024-04-12T10:49:38.771Z",
    "started_at": "2024-04-12T10:37:59.556997Z",
    "first_billed_at": "2024-04-12T10:37:59.556997Z",
    "next_billed_at": "2024-05-12T10:37:59.556997Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-12T10:37:59.556997Z",
      "ends_at": "2024-05-12T10:37:59.556997Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 20,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:49:38.76Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "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-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:38:00.761Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "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-09T07:23:00.907834Z"
        },
        "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-04-12T10:49:38.765Z",
        "updated_at": "2024-04-12T10:49:38.765Z",
        "previously_billed_at": "2024-04-12T10:49:38.765Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "standard",
          "description": "Monthly (recurring addon)",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "25000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:59:52.159927Z",
          "updated_at": "2024-04-09T07:27:48.018296Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "VIP support",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "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_01hv8y5ehszzq0yv20ttx3166y/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel"
    },
    "discount": null,
    "import_meta": null,
    "consent_requirements": []
  },
  "meta": {
    "request_id": "fd763d79-df30-41dd-9c59-adde4cf02cd3"
  }
}
```