Checkout-created STATIC subscription retains $1 order template after plan swap and continues billing $1 — what is the supported way to implement subscription discounts?

Questions
, ,
1

We are trying to determine the supported way to implement an introductory subscription discount using Square, and we have encountered production behavior that doesn’t seem to match the current documentation or previous forum guidance.

Our intended subscription

We want:

  • First month: $1
  • Following months: $149/month indefinitely

Originally, we implemented this as a SUBSCRIPTION_PLAN_VARIATION with two STATIC phases:

  • Phase 0: MONTHLY, periods: 1, STATIC $1
  • Phase 1: MONTHLY, indefinite, STATIC $149

The subscription was purchased through a Checkout API Payment Link using quick_pay, where quick_pay.price_money was $1, matching the initial phase.

The current Checkout API documentation says Checkout supports only one paid phase, or one free phase followed by one paid phase. Therefore, we understand that our original $1 paid phase -> $149 paid phase configuration is not currently documented as supported through Checkout, but it still created the payment link.

However, we are trying to understand the subscription objects that Checkout created and determine the supported solution.

What actually happened in production

The first invoice was correctly generated for $1.

On the second billing period, however, Square generated another $1 invoice instead of $149.

We inspected the Catalog variation and confirmed that the phases were correct:

Phase 0
STATIC $1
periods = 1

Phase 1
STATIC $149
indefinite

The resulting Subscription also contained the correct plan_variation_id and the correct plan_phase_uid values for both phases.

There was no price_override_money on the Subscription.

However, we discovered that the Subscription contained a top-level:

order_template_id

Retrieving that DRAFT Order showed:

base_price_money = $1
total_money = $1

The generated order for the second billing period was also $1, and consequently the second invoice was generated at $1.

This appears to indicate that the $1 Checkout/QuickPay order template continued to influence recurring billing even though the Catalog variation’s second STATIC phase was $149.

We then tried SwapPlan

As a remediation, we created/used a clean single-phase variation under the same parent plan:

Monthly
STATIC $149
indefinite

We used SwapPlan to move affected subscriptions to this variation.

The swap completed successfully.

After the swap, retrieving the Subscription shows:

plan_variation_id = <the $149 STATIC variation>

phases:
  ordinal = 0
  plan_phase_uid = <the $149 phase UID>

There is no longer a phase-level order_template_id.

However, the Subscription still contains its original top-level order_template_id.

Retrieving that order still shows:

$1

Most importantly, the subscription subsequently continued billing $1.

This surprised us because previous Square forum guidance indicates that when a subscription is swapped to a STATIC-priced variation, the STATIC price of the new variation should be charged starting with the next billing period.

Could someone from the Square Subscriptions/Checkout team clarify the intended behavior here?

  1. Why does Checkout create a top-level order_template_id on this subscription when its SubscriptionPlanVariation uses STATIC pricing?
  2. Is this top-level order template expected to control recurring billing for a Checkout-created subscription even when the associated plan variation uses STATIC pricing?
  3. Why does the top-level $1 order template remain after SwapPlan successfully changes the subscription to a single-phase $149 STATIC variation?

What is Square’s recommended implementation for introductory discounts?

Our actual business requirement is simple:

First billing period: $1
Following billing periods: $149/month

We would like to understand the currently recommended Square architecture for this.

Thank you in advanced,

Best