Subscriptions API: seven-day pause accepted in Sandbox, billing date guarantees?

Questions
1

Hello Square Developer Support,

We need to move the next payment date for a monthly subscription, either permanently or for one month only, without charging on both the old and new dates. We have only tested synthetic subscriptions in Sandbox, not changed live customer billing.

Tested on 7 September 2026 using API Explorer, Square-Version 2026-08-19, Europe/London timezone, ongoing MONTHLY STATIC pricing with a GBP 100-pence price override, no proration requested and no card supplied. Before the following requests, the clean test subscriptions were ACTIVE, monthly_billing_anchor_date 12 and charged_through_date 2026-09-12.

Permanent-date candidate

POST /v2/subscriptions/{synthetic_subscription_id}/pause:

{
  "pause_effective_date": "2026-09-12",
  "resume_effective_date": "2026-09-19",
  "resume_change_timing": "IMMEDIATE"
}

Sandbox returned HTTP 200. An independent GET with include=actions persisted all three actions:

  • PAUSE on 2026-09-12
  • RESUME on 2026-09-19
  • CHANGE_BILLING_ANCHOR_DATE on 2026-09-19, anchor 19 (automatically added, not present in the pause write response)

One-off-date candidate, on a separate synthetic subscription

After the same pause request, we submitted POST /v2/subscriptions/{synthetic_subscription_id}/billing-anchor with monthly_billing_anchor_date 12 and effective_date 2026-10-12. It returned HTTP 200. An independent GET persisted the three actions above plus CHANGE_BILLING_ANCHOR_DATE on 2026-10-12, anchor 12.

The subscriptions still show their original anchor and charged-through date before these future actions. We have verified scheduled actions only, not the future invoice or card-charge sequence.

The pause endpoint documentation says resume_effective_date must be at least one billing cycle after pause_effective_date, but Sandbox accepted this seven-day pause:

Could Square please confirm:

  1. Is this short pause/resume sequence officially supported in production for this monthly setup, despite that documentation restriction? If not, what supported sequence should we use?
  2. Does the pause suppress the invoice and automatic charge otherwise due on 12 September, with exactly one full GBP 1 charge on 19 September and no additional or prorated charge? Are there timing cutoffs or already-generated invoice exceptions we must check?
  3. For the permanent candidate, will billing then continue on 19 October, with no 12 October charge?
  4. For the one-off candidate, is queuing the 12 October anchor restoration while the pause/resume actions are pending supported, giving charges on 19 September and then 12 October only? What action-ordering guarantees or restrictions apply?

As a comparison, changing only the anchor to 19 in Sandbox returned a scheduled 19 September action while the original charged-through date stayed 12 September. We therefore do not assume that an anchor change alone suppresses the old charge.

Please also let us know whether Sandbox has a supported way to advance billing time and verify these invoice sequences, or whether we must observe the real dates. We can provide synthetic test references through a private support channel if needed. No credentials or customer details are included here.

Thank you.

5

@james-hill - Thanks for your patience while I investigate your questions.

Sandbox may accept requests that production will reject or that will behave unpredictably. You should not rely on this seven-day gap in production.

Pausing a subscription should suppress invoice generation. Square bills in advance at the beginning of each billing cycle, so if the pause is effective on 12 September (the billing anchor), the September invoice should not be created. However, any invoice already generated before the pause takes effect will not be reversed.

Billing should continue on 19 October. We cannot guarantee action-ordering behavior when multiple pending actions (pause, resume, and multiple anchor changes) are queued simultaneously.

For this scenario, we would generally recommend that you cancel the subscription → create a one-off payment/invoice → recreate the subscription on the restored recurring date.

There is no Sandbox billing-clock-advance mechanism. You must wait for real dates to pass, or test invoice flows separately using the Invoices API.

7

Thanks @jseok. We have now tested a billing-anchor change on our own live £1 monthly test subscription, without using the short pause/resume sequence.

It paid on 7 September and was charged through 7 October. On 16 September we requested billing day 17, effective 17 September. Today, 18 September, the API shows anchor 17 and the anchor action has gone, but there is no new invoice or payment. Only the original paid invoice remains.

A separate safety PAUSE is still scheduled for 7 October, with no resume, so the dashboard says “Next billing paused”. We are not treating this as a successful payment-date test.

Should the anchor change have generated a payment on 17 September, or does the existing charged-through date prevent that? Does the future 7 October pause affect this September result?

What supported sequence should we use to bring the next full payment forward without duplicate or partial charges? If replacement is required, how do we safely end the old subscription before the new one bills? I can provide the test subscription ID privately. Please advise before changing or charging anything on the account.

8

Thanks @jseok. We have stopped pursuing earlier payments and are focusing only on postponements.

For an existing monthly subscription, what supported API sequence postpones the next full payment and permanently sets the new monthly billing day, without charging on both the old and new dates?

If a billing-anchor change is scheduled to execute on the new billing day, does that suppress the renewal on the old date before the action executes? If the postponement is shorter than one billing cycle, is cancellation and replacement required even for this permanent-date case?

This is a general implementation question. Please do not make any account changes.

9

No September 17 invoice was created because the subscription was already invoiced through October 7. Moving the billing day does not charge again for that covered period.

To permanently move billing from the 7th to the 17th:

  1. Call ChangeBillingAnchorDate before the old renewal date.
  2. Set monthly_billing_anchor_date to 17.
  3. Leave out effective_date so the change applies immediately.
  4. Verify the subscription now shows day 17.
  5. Delete the pending October 7 PAUSE if you want billing to continue. Delete only the PAUSE; deleting a CHANGE_BILLING_ANCHOR_DATE action is not supported.

With the pause removed, the next renewal should be October 17 rather than October 7.

Make the change well before the old renewal date to ensure an invoice isn’t already created.