[Bug]: `prorated_next_billing_period` still throws `subscription_update_transaction_balance_less_than_charge_limit` in production

[yujiniii]

What happened?

Description

When previewing a subscription upgrade in the production environment, prorated_immediately returns a minimum charge limit error because the prorated amount is below the USD 0.70 minimum.

However, retrying the same preview request with prorated_next_billing_period also returns the exact same error.

This appears inconsistent with the documented troubleshooting guidance, which recommends retrying with *_next_billing_period when an immediate prorated charge is below the minimum charge limit.

Subscription details

• Current plan: USD 1.00 every 3 days
• Target plan: USD 3.00 every 3 days
• Calculated prorated amount: USD 0.10
• Minimum payment amount: USD 0.70
• Environment: Production

Example using the Node SDK:

await paddle.subscriptions.previewUpdate(subscriptionId, {
  items: [
    {
      priceId: targetPriceId,
      quantity: 1,
    },
  ],
  prorationBillingMode: 'prorated_next_billing_period',
});

Actual behavior

prorationBillingMode = prorated_immediately

{
  "error": {
    "type": "request_error",
    "code": "subscription_update_transaction_balance_less_than_charge_limit",
    "detail": "Unable to charge for Subscription update: Transaction balance is less than what we can charge. Transaction balance: 10, Minimum payment amount: 70, Currency code: USD",
    "documentation_url": "https://developer.paddle.com/v1/errors/subscriptions/subscription_update_transaction_balance_less_than_charge_limit"
  },
  "meta": {
    "request_id": "ae23fbac-cdc0-4cec-91f1-510e44c59086"
  }
}

prorationBillingMode = prorated_next_billing_period

{
  "error": {
    "type": "request_error",
    "code": "subscription_update_transaction_balance_less_than_charge_limit",
    "detail": "Unable to charge for Subscription update: Transaction balance is less than what we can charge. Transaction balance: 10, Minimum payment amount: 70, Currency code: USD",
    "documentation_url": "https://developer.paddle.com/v1/errors/subscriptions/subscription_update_transaction_balance_less_than_charge_limit"
  },
  "meta": {
    "request_id": "d3e9387e-3913-4fb1-bff8-3f8b53f1b5cc"
  }
}

Both modes validate the transaction balance as USD 0.10 and return the same error.

Documentation inconsistency

The error documentation recommends retrying with *_next_billing_period when a request using *_immediately fails because the transaction balance is below the minimum charge amount.

However, the documented workaround produces the same error in this case.

The documentation does not clarify whether the preview endpoint intentionally validates the deferred prorated amount independently from the recurring renewal charge that it will be combined with at renewal.

full_* is not an equivalent workaround because it changes the amount charged by disabling proration. We need a way to defer the original prorated amount without discarding it or charging the full amount.

Questions

1. Is it expected that prorated_next_billing_period still rejects the update when the deferred prorated amount is below the minimum charge limit?
2. Should the deferred USD 0.10 proration be evaluated independently, or together with the USD 3.00 recurring renewal charge?
3. Is this behavior limited to the preview endpoint, or would the actual subscription update request fail in the same way?
4. If this is an intended limitation, could the troubleshooting documentation be updated to clarify when *_next_billing_period can be used as a workaround?
5. What is the recommended way to apply the upgrade immediately while preserving the prorated charge?

Environment

• Paddle environment: Production
• Endpoint: POST /subscriptions/{subscription_id}/preview
• SDK: Paddle Node SDK
• Currency: USD
• Current billing interval: Every 3 days
• Target billing interval: Every 3 days

Steps to reproduce

1. Create a subscription for a USD 1.00 / 3-day recurring price.
2. Preview an update to a USD 3.00 / 3-day recurring price using prorated_immediately.
3. Confirm that the request fails because the prorated charge is USD 0.10.
4. Retry the same preview request using prorated_next_billing_period.
5. The request still fails with the same minimum charge limit error.

What did you expect to happen?

With prorated_next_billing_period, I would expect the USD 0.10 prorated amount to be deferred and included in the next renewal transaction.

The next renewal transaction should contain approximately:

Recurring renewal charge: USD 3.00
Deferred prorated charge: USD 0.10
Total renewal transaction: USD 3.10

Since the combined renewal amount is above the USD 0.70 minimum payment amount, I would not expect the preview request to fail based only on the deferred USD 0.10 prorated amount.

Logs