Square Subscriptions API — Updating Recurring Prices Mid-Cycle Without Changing Billing Dates

Questions
, ,
1

Hello,

I’m developing a subscription-based platform that uses Square for recurring billing, saved payment methods, and one-time payments.

Our customers can choose monthly, quarterly, semiannual, or annual subscriptions. We also offer optional recurring add-ons that customers can purchase during an active subscription period.

I’d like to confirm whether the following approach is supported and recommended by Square.

Example scenario:

  1. A customer has an active annual subscription costing $240, with six months remaining before renewal.

  2. They purchase an additional service costing $5 per month ($60 annually).

  3. Our platform calculates the prorated amount of $30 for the remaining six months and collects it immediately as a separate one-time payment through Square’s Payments API.

  4. We then use Square’s Subscriptions API to update the existing subscription’s price_override_money from $240 to $300.

  5. We want the updated $300 recurring amount to take effect at the next scheduled renewal, without changing the customer’s billing date or creating another subscription.

My questions are:

  1. Can price_override_money be updated on an existing, active Square subscription that has already processed recurring payments?

  2. Does updating this amount affect only future billing cycles, or could it trigger an immediate charge?

  3. Will the subscription retain its original billing date, subscription ID, saved card, and billing frequency?

  4. What happens if the price is updated shortly before renewal or after Square has already generated the next invoice?

  5. Is collecting a prorated one-time payment separately, then modifying the existing recurring subscription amount, the recommended method for handling mid-cycle add-ons?

  6. Does this approach work consistently for monthly, quarterly, semiannual, and annual subscriptions?

  7. Are there any known limitations, API requirements, or webhook considerations we should account for?

What we’ve tested:

In Square Sandbox, we successfully updated a subscription’s price using the existing subscription ID. The customer, payment method, plan, and scheduled billing date remained unchanged.

However, the subscription had not yet completed its first recurring billing cycle, so we haven’t verified how this behaves on an actively renewing subscription.

Our goal is to maintain one subscription per customer, collect prorated add-on fees immediately, and automatically adjust future recurring charges without interrupting the existing billing schedule.

I’d appreciate confirmation that this is a supported approach or recommendations for a better implementation.

Thank you!

3

Yes, this approach is supported. A few details:

  • You can change price_override_money with UpdateSubscription whether or not the subscription has already billed. Pass the current version. The subscription ID, customer, card, plan, cadence and billing anchor date all stay the same.
  • UpdateSubscription doesn’t charge anything right away. The new amount is used on the next invoice Square generates. If that invoice already exists, it keeps the old amount. To change it, check invoice_ids on the subscription and handle that invoice through the Invoices API. Updating the subscription won’t regenerate it.
  • price_override_money only works on plan variations with STATIC pricing. With RELATIVE (itemized) pricing, it has no effect. Update the subscription’s order template instead (CreateSubscription reference).
  • Square doesn’t prorate price changes, so charging the $30 separately through the Payments API is your responsibility, and that’s fine. It works the same way for monthly, quarterly, semiannual and annual cadences.
  • Listen for subscription.updated to confirm the change, and for invoice.* events to see each renewal’s amount.

If you plan to add more custom billing logic (add-ons, proration, mid-cycle changes), consider billing a card on file through the Payments API on your own schedule. It’s more flexible than the Subscriptions API.