We are investigating an intermittent date mismatch when creating monthly subscriptions through the Square Subscriptions API.
Our application logs show a Create Subscription request with start_date: "2026-10-20" and timezone: "Asia/Tokyo". For seven production subscriptions, both the creation response and a later Retrieve Subscription response returned start_date: "2026-10-19". Six other subscriptions created through the same integration returned the requested start date. The monthly billing anchor day matched the requested day. We have not established whether the cause is in our request handling or Square.
Could you help us determine:
Under what conditions can the returned start_date differ from the date supplied to Create Subscription?
Which request fields and API logs should we compare to establish what Square received and how the date was calculated?
Could this difference change the first charge date or billing period, even when the monthly billing anchor day is correct?
What is the safest way to correct affected subscriptions without risking a duplicate charge?
We can provide subscription IDs and relevant request/response details through a private support channel if needed. We are omitting customer and subscription identifiers from this public post.
Thanks for the detailed description of the issue you are experiencing. The most likely cause is a client-side date serialization issue, not Square shifting the date.
start_date is a date-only string (YYYY-MM-DD). If your code passes it through a Date object (or equivalent) before serialization, the runtime can silently shift the calendar date depending on when the request runs relative to UTC midnight. For Asia/Tokyo (UTC+9), constructing new Date("2026-10-20") parses it as UTC midnight, which is still October 19 in any timezone behind UTC. If the SDK or your serializer then calls .toLocaleDateString() or equivalent in a server timezone west of UTC, the string becomes "2026-10-19". The intermittent pattern, with 7 of 13 affected, fits a timing window where some requests land before and some after the UTC date boundary.
To confirm:
Log the serialized HTTP request body (not the variable before SDK handoff) and verify the literal "start_date" value Square received. The Square-Trace-Id response header identifies the request on Square’s side.
Check subscription.timezone in both the Create and Retrieve responses. If it’s not Asia/Tokyo, the location’s default timezone was applied instead.
If the raw outbound body contains "start_date":"2026-10-20" and the response contains "2026-10-19" with timezone: "Asia/Tokyo", that’s a Square-side issue. Preserve the app id and subscription IDs, and timestamps and share them in this thread.
On billing impact:start_date determines when the subscription becomes ACTIVE and the first invoice is generated. If the stored date is one day early, the first billing cycle starts one day early. The monthly_billing_anchor_date controls which day of the month subsequent invoices fall on, so later cycles are unaffected, but the first period is one day longer than intended.
To correct affected subscriptions: Use UpdateSubscription to set the correct start_date on any subscription still in PENDING status. For subscriptions already ACTIVE, updating start_date has no effect as the first invoice is already generated. In that case, if the invoice hasn’t been paid, cancel it via the Invoices API and let the next billing cycle (anchored correctly) take over. Do not cancel and recreate the subscription without cancelling the open invoice first, as that risks a duplicate charge during the dunning window.
Thank you for your guidance. I’d like to clarify one point about correcting the start date.
You suggested using UpdateSubscription to change start_date while the subscription is PENDING. However, the Subscription API reference labels start_date as “Read only”: Subscription Object - Square API Reference
Does UpdateSubscription allow start_date to be changed for a PENDING subscription despite that label? We use Square API version 2026-08-19. If it is supported, could you show the request body and any conditions or limitations?
Thanks for catching that and apologies for the incorrect guidance.
You’re correct: start_date is read-only after the subscription is created, even when its status is PENDING. UpdateSubscription doesn’t support changing it. Before taking any action, let’s confirm the raw request/response for start_date.
Thank you for the correction. We checked the records available from the affected production requests and the PHP request path.
For seven subscriptions, our encrypted application ledger contains the CreateSubscription request fields before HTTP serialization and the Square creation response. In one representative case, the saved request fields have start_date = 2026-10-20 and timezone = Asia/Tokyo; the saved creation response has start_date = 2026-10-19 and timezone = Asia/Tokyo. A later RetrieveSubscription response still has start_date = 2026-10-19. The other six affected records show the same one-day pattern; six comparison records matched the requested date.
The integration is PHP, not a JavaScript Date/SDK path. It builds start_date as a Y-m-d string and passes wp_json_encode($body) as the body of wp_remote_request() to POST /v2/subscriptions (Square API version 2026-08-19). However, we did not retain the final serialized HTTP body or the response Square-Trace-Id for those historical requests. The saved request fields alone cannot prove the exact bytes received by Square, so we are not concluding where the date changed.
Could Square check the received start_date against the creation response in its server-side logs for the affected subscription IDs? We can provide the IDs and creation timestamps through a private support channel; please tell us the appropriate secure channel. We are omitting customer and subscription identifiers from this public thread. We have made no subscription changes based on the earlier UpdateSubscription suggestion.
Thanks for digging into this further and providing clarification.
Please share the affected subscription IDs in this thread, along with one or two unaffected subscription IDs created through the same request path for comparison along with the creation timestamp. Subscription IDs and application IDs are safe to share publicly, but don’t post access tokens, card details, or customer information.
Because Square API Logs are retained for 28 days, please also check whether these calls still appear in your Developer Console. If they do, compare the Request and Response tabs and share the literal start_dateand timezone values shown there.