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

# Change billing dates

Change the billing date of a subscription to change when a customer next pays, and when their subscription renews in the future.

---

Subscriptions renew automatically when their billing period elapses. For example, a subscription might renew every week, month, or year.

Change the billing date of a subscription when customers want their subscription to renew on a certain day or time every period, like the first of the month or the first day of the financial year.

{% callout type="note" %}
Working with trialing subscriptions? You can extend a trial or cut a trial short to bill for it right away, see [Extend or activate a trial](https://developer.paddle.com/build/subscriptions/extend-activate-change-date-trials.md)
{% /callout %}

## How it works

Paddle automatically creates subscriptions when customers pay for recurring items using [the checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md), or when you [create and issue invoices](https://developer.paddle.com/build/invoices/create-issue-invoices.md) using manually-collected transactions.

By default, the billing date for each renewal is based on the date that the subscription was created. For example, if a subscription bills annually then its billing date is every year on the anniversary of its creation.

Change the billing date against a subscription to change when the subscription renews. This changes the next billing date of the subscription, and the day and time that it renews in the future.

When you change a subscription billing date, you can determine how Paddle should bill for any changes. This is called [proration](https://developer.paddle.com/concepts/subscriptions/proration.md). Paddle's subscription billing engine calculates proration to the minute, allowing for precise billing.

If you choose to prorate:

- When a customer moves their billing date **later** than their renewal, Paddle calculates the prorated **amount that they owe** and **bills** for it.
- When a customer moves their billing date **sooner** than their renewal, Paddle calculates the prorated **amount that they already paid** for and **creates a credit** for it.

You can also choose `do_not_bill` to change the billing date without charging or crediting.

## Before you begin

{% callout type="info" %}
You can't make changes to a subscription if the next billing period is within 30 minutes, or the subscription status is `past_due`.
{% /callout %}

To change the billing date of a subscription, you'll need to [get the subscription ID](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions.md) for the subscription you want to change.

You can use the `status` query parameter when listing with the value `active` to get a list of active subscriptions.

## Change billing dates

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

1. Go to **Paddle > Customers**, and find the customer whose subscription you want to change.
2. Find the subscription under the Subscriptions heading and click it.
3. From the subscription overview page, choose Change next billing date
4. Enter the new date, then click Save to proceed.

{% /tab-item %}
{% tab-item title="API" %}

Change billing dates using the API in two steps:

1. **Preview change** {% badge label="Optional" variant="outline" /%}  
   Preview how the proration will apply before committing the change. Present this to customers if you offer an in-app workflow.
2. **Update subscription**  
   Send a request to update the subscription with the new billing date.

### Preview change {% step=true badge="Optional" %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}/preview` endpoint to preview the changes you're making to the subscription.

In your request, include `next_billed_at` (RFC 3339 timestamp) with the new billing date and `proration_billing_mode`. For billing date changes, only `prorated_immediately`, `prorated_next_billing_period`, and `do_not_bill` are allowed. Optionally include `on_payment_failure` to control payment failure behavior (defaults to `prevent_change`).

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. With `prorated_next_billing_period`, `immediate_transaction` is `null` and proration is charged on the next renewal.

{% api-example method="PATCH" path="/subscriptions/{subscription_id}/preview" href="/api-reference/subscriptions/preview-subscription" %}

```json
{
  "next_billed_at": "2024-01-01T00:00:00Z",
  "proration_billing_mode": "prorated_next_billing_period"
}
```

```json
{
  "data": {
    "status": "active",
    "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp",
    "address_id": "add_01hj3289stgx73kjryne7pwzh7",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-12-20T07:33:50.521Z",
    "updated_at": "2023-12-20T11:36:26.56Z",
    "started_at": "2023-12-20T07:33:49.542313Z",
    "first_billed_at": "2023-12-20T07:33:49.542313Z",
    "next_billed_at": "2024-01-01T00:00:00Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-12-20T07:33:49.542313Z",
      "ends_at": "2024-01-01T00:00:00Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "40000",
            "discount": "0",
            "tax": "3549",
            "total": "43549"
          }
        }
      ],
      "totals": {
        "subtotal": "40000",
        "tax": "3549",
        "discount": "0",
        "total": "43549",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "43549",
        "grand_total": "43549",
        "earnings": null,
        "currency_code": "USD",
        "exchange_rate": "1"
      },
      "line_items": [
        {
          "item_id": null,
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "2662",
            "discount": "0",
            "total": "32662"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "type": "standard",
            "tax_category": "standard",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": {
              "features": {
                "crm": true,
                "data_retention": false,
                "reports": true
              },
              "suggested_addons": [
                "pro_01h1vjes1y163xfj1rh1tkfb65",
                "pro_01gsz97mq9pa4fkyy0wqenepkz"
              ],
              "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting."
            },
            "status": "active",
            "import_meta": null
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "3000",
            "discount": "0",
            "tax": "266",
            "total": "3266"
          },
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2023-12-20T07:33:49.542313Z",
              "ends_at": "2024-01-01T00:00:00Z"
            }
          }
        },
        {
          "item_id": null,
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "type": "standard",
            "tax_category": "standard",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "custom_data": null,
            "status": "active",
            "import_meta": null
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "discount": "0",
            "tax": "887",
            "total": "10887"
          },
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2023-12-20T07:33:49.542313Z",
              "ends_at": "2024-01-01T00:00:00Z"
            }
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2024-01-01T00:00:00Z",
        "ends_at": "2024-02-01T00:00:00Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "40000",
              "discount": "0",
              "tax": "3549",
              "total": "43549"
            }
          }
        ],
        "totals": {
          "subtotal": "40000",
          "tax": "3549",
          "discount": "0",
          "total": "43549",
          "fee": null,
          "credit": "27133",
          "credit_to_balance": "0",
          "balance": "16416",
          "grand_total": "16416",
          "earnings": null,
          "currency_code": "USD",
          "exchange_rate": "1"
        },
        "line_items": [
          {
            "item_id": null,
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 10,
            "totals": {
              "subtotal": "30000",
              "tax": "2662",
              "discount": "0",
              "total": "32662"
            },
            "product": {
              "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
              "name": "ChatApp Pro",
              "type": "standard",
              "tax_category": "standard",
              "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "custom_data": {
                "features": {
                  "crm": true,
                  "data_retention": false,
                  "reports": true
                },
                "suggested_addons": [
                  "pro_01h1vjes1y163xfj1rh1tkfb65",
                  "pro_01gsz97mq9pa4fkyy0wqenepkz"
                ],
                "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting."
              },
              "status": "active",
              "import_meta": null
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "3000",
              "discount": "0",
              "tax": "266",
              "total": "3266"
            },
            "proration": {
              "rate": "1",
              "billing_period": {
                "starts_at": "2024-01-01T00:00:00Z",
                "ends_at": "2024-02-01T00:00:00Z"
              }
            }
          },
          {
            "item_id": null,
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "10000",
              "tax": "887",
              "discount": "0",
              "total": "10887"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Voice rooms addon",
              "type": "standard",
              "tax_category": "standard",
              "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
              "custom_data": null,
              "status": "active",
              "import_meta": null
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "10000",
              "discount": "0",
              "tax": "887",
              "total": "10887"
            },
            "proration": {
              "rate": "1",
              "billing_period": {
                "starts_at": "2024-01-01T00:00:00Z",
                "ends_at": "2024-02-01T00:00:00Z"
              }
            }
          }
        ]
      },
      "adjustments": [
        {
          "transaction_id": "txn_01hj327s2cpxh4mprx55p5qwdz",
          "items": [
            {
              "item_id": "txnitm_01hj328ac2ak7h82bjfzdk992c",
              "type": "proration",
              "amount": "20350",
              "proration": {
                "rate": "0.62305",
                "billing_period": {
                  "starts_at": "2024-01-01T00:00:00Z",
                  "ends_at": "2024-01-20T07:33:49.542313Z"
                }
              },
              "totals": {
                "subtotal": "18691",
                "tax": "1659",
                "total": "20350"
              }
            },
            {
              "item_id": "txnitm_01hj328ac2ak7h82bjg443x4px",
              "type": "proration",
              "amount": "6783",
              "proration": {
                "rate": "0.62305",
                "billing_period": {
                  "starts_at": "2024-01-01T00:00:00Z",
                  "ends_at": "2024-01-20T07:33:49.542313Z"
                }
              },
              "totals": {
                "subtotal": "6230",
                "tax": "553",
                "total": "6783"
              }
            }
          ],
          "totals": {
            "subtotal": "24921",
            "tax": "2212",
            "total": "27133",
            "fee": "1378",
            "earnings": "23543",
            "currency_code": "USD"
          }
        }
      ]
    },
    "immediate_transaction": null,
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-12-20T07:33:50.521Z",
        "updated_at": "2023-12-20T11:36:26.498Z",
        "previously_billed_at": "2023-12-20T07:33:49.542313Z",
        "next_billed_at": "2024-01-01T00:00:00Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-12-20T07:33:50.521Z",
        "updated_at": "2023-12-20T11:36:26.499Z",
        "previously_billed_at": "2023-12-20T07:33:49.542313Z",
        "next_billed_at": "2024-01-01T00:00:00Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/cancel"
    },
    "discount": null,
    "update_summary": {
      "credit": {
        "amount": "27133",
        "currency_code": "USD"
      },
      "charge": {
        "amount": "0",
        "currency_code": "USD"
      },
      "result": {
        "action": "credit",
        "amount": "27133",
        "currency_code": "USD"
      }
    },
    "import_meta": null
  },
  "meta": {
    "request_id": "905e4427-a654-4591-8ace-432d5450dfe0"
  }
}
```

{% /api-example %}

### Update subscription {% step=true %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint to update the subscription.

In your request, include the same body as the preview request.

Paddle updates the subscription.

{% api-example method="PATCH" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/update-subscription" %}

```json
{
  "next_billed_at": "2024-01-01T00:00:00Z",
  "proration_billing_mode": "prorated_next_billing_period"
}
```

```json
{
  "data": {
    "id": "sub_01hj32a99syawqhdkkbpxacwgb",
    "status": "active",
    "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp",
    "address_id": "add_01hj3289stgx73kjryne7pwzh7",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-12-20T07:33:50.521Z",
    "updated_at": "2023-12-20T11:42:29.714Z",
    "started_at": "2023-12-20T07:33:49.542313Z",
    "first_billed_at": "2023-12-20T07:33:49.542313Z",
    "next_billed_at": "2024-01-01T00:00:00Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-12-20T07:33:49.542313Z",
      "ends_at": "2024-01-01T00:00:00Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-12-20T07:33:50.521Z",
        "updated_at": "2023-12-20T11:42:29.643Z",
        "previously_billed_at": "2023-12-20T07:33:49.542313Z",
        "next_billed_at": "2024-01-01T00:00:00Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-12-20T07:33:50.521Z",
        "updated_at": "2023-12-20T11:42:29.644Z",
        "previously_billed_at": "2023-12-20T07:33:49.542313Z",
        "next_billed_at": "2024-01-01T00:00:00Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/update-payment-method?token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWhqM2doa3JjOGVlem4yYzFnZndnNHlociIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6Im1hbmFnZW1lbnRfdXJsIiwic2NvcGUiOiJjdXN0b21lci5zdWJzY3JpcHRpb24tcGF5bWVudC51cGRhdGUgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQucmVhZCBjdXN0b21lci5zdWJzY3JpcHRpb24tY2FuY2VsLmNyZWF0ZSBjdXN0b21lci5zdWJzY3JpcHRpb24ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFoajMyODlzNDZhbXR6djh2cjU3eHRueHAiLCJleHAiOjE3MzQ2OTQ5NTAsImlhdCI6MTcwMzA3MjU1MH0.SMb_DeNfwZFzWg-uLhQClUjAVszdDWV7XyJATqpub8Sc6hcaOI1KJRwdhemNu2D5ZiKRRGU3vL7PRZG-pBkbAA",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/cancel?token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWhqM2doa3JjOGVlem4yYzFnZndnNHlociIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6Im1hbmFnZW1lbnRfdXJsIiwic2NvcGUiOiJjdXN0b21lci5zdWJzY3JpcHRpb24tcGF5bWVudC51cGRhdGUgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQucmVhZCBjdXN0b21lci5zdWJzY3JpcHRpb24tY2FuY2VsLmNyZWF0ZSBjdXN0b21lci5zdWJzY3JpcHRpb24ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFoajMyODlzNDZhbXR6djh2cjU3eHRueHAiLCJleHAiOjE3MzQ2OTQ5NTAsImlhdCI6MTcwMzA3MjU1MH0.SMb_DeNfwZFzWg-uLhQClUjAVszdDWV7XyJATqpub8Sc6hcaOI1KJRwdhemNu2D5ZiKRRGU3vL7PRZG-pBkbAA"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "87ac24c4-a4b4-42b2-a13a-903d0cf06b9d"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}