Updating RELATIVE subscription order-template pricing without changing an active subscription or billing date

Questions
1

We operate a live SaaS application using Square Subscriptions API version 2026-09-16.

We have an existing ACTIVE subscription with:

  • Billing cadence: ANNUAL
  • Pricing type: RELATIVE
  • One active subscription phase
  • Attached order template in DRAFT status, version 2
  • Current template total: 4,800 cents ($48.00)
  • Required future recurring total: 51,840 cents ($518.40)
  • Next annual billing date: September 26, 2027

The current annual period has already been paid, including a separate balance-adjustment invoice. We do not want an immediate charge.

Questions:

  1. Can UpdateOrder safely change the line-item base_price_money on a DRAFT order template already attached to an ACTIVE subscription?
  2. If successful, will future recurring invoices use the updated amount without changing the subscription ID, billing cadence, next billing date, or stored payment method?
  3. If editing the attached template is unsupported, is a scheduled SwapPlan to a new ANNUAL RELATIVE plan variation with a corrected order template the recommended approach?
  4. Can that change be scheduled to preserve the existing September 26, 2027 renewal without generating an immediate charge or duplicate invoice?
  5. What is the recommended method to verify the next recurring amount before the renewal date?

We need a supported, production-safe approach without cancelling or recreating the customer’s subscription.

3

1-2. Yes. Call UpdateOrder on the DRAFT template with its current version and change the line item’s base_price_money. Future billing cycles then use the updated template. The subscription ID, cadence, next billing date and card on file don’t change. An invoice that has already been generated keeps its original amount, so make the change before the September 26, 2027 cycle is created.

3-4. You only need SwapPlan if you want a different plan variation. It is scheduled for the end of the current billing cycle, so it would take effect at the September 26, 2027 renewal and would not charge anything now. If you go this way, pass phases[].ordinal and order_template_id for the new DRAFT template.

5. Call RetrieveOrder on the template and check total_money (51,840). Call RetrieveSubscription with include=actions to confirm the next billing date and that no unexpected actions are pending. There isn’t a documented endpoint that previews the next invoice.

If needed you can test the full flow in Sandbox first.