Billing cycles not updating when next billing date changes

GraphQL Admin API Troubleshooting
1

I am working on a subscription app and need to implement functionality where the customer or merchant can change a subscription’s next billing date, and have the new date reflected in all future billing cycles.

I was under the impression that subscriptionContractSetNextBillingDate is also supposed to recalculate future Billing Cycles for that subscription contract. For example, if I have a monthly contract billing on the 1st and I updated the next billing date to the 15th, all billing cycles should be updated to use the 15th going forward. Is this not the case? The dev assistant implied that it is, and I swear this is how it worked previously, but am no longer seeing this behavior - billing cycles do not change when next billing date changes.

2

Hey @jacksonmay , you’re right that this is how it should work per the documentation here, so long as the subscription contract is still valid/active:

Could you share a subscription id where you’re seeing this behaviour pop up? I can take a look at things on our end to investigate further. Hope to hear from you soon!

3

sure thing! here’s an example contract:

gid://shopify/SubscriptionContract/18083709207

and here’s what i’m seeing (desynced billingAttemptExpectedDate and nextBillingDate after firing a subscriptionContractSetNextBillingDate mutation):

{
          "node": {
            "cycleIndex": 1,
            "billingAttemptExpectedDate": "2025-11-01T17:00:00Z",
            "cycleStartAt": "2025-10-01T17:55:56Z",
            "cycleEndAt": "2025-11-01T17:00:00Z",
            "status": "UNBILLED",
            "skipped": false,
            "edited": false,
            "sourceContract": {
              "id": "gid://shopify/SubscriptionContract/18083709207",
              "status": "ACTIVE",
              "nextBillingDate": "2025-11-15T23:59:59Z"
            },
            "billingAttempts": {
              "edges": []
            }
          }
        },

appreciate the help!

4

Thanks @jacksonmay , appreciate you sending the response there too. I did a bit of digging and it looks like this contract is tied to a test shop? Just want to confirm that with you. Out of curiosity as well, do you happen to have an X-Request-ID from the API Response headers we send out with every API call? Just want to see if I can pull an example in the logs to share with the team so we can look into this further.

Hope to speak soon!

6

indeed it is on a test store! and sure thing, here’s a seperate request but same contract / result:

b2be7402-108d-4ce9-87c7-d6977e0c32c6-1759431540
7

Thanks @jacksonmay , I was able to pull some logs with that, I appreciate it! I’ll do some further digging into this on my end and loop back with you once I have more info/next steps :slight_smile:

9

hey Alan! were you able to find anything here?

10

Hey @jacksonmay - thanks for the ping! I was able to look into this more deeply and have some info to share. At the moment, nextBillingDateis intended a field to store information, it doesn’t actually update the billing date for the subscription. This functionality is still available through the API though, it just has to be enacted through the subscriptionBillingCycleScheduleEditmutation:

Hope this helps/makes sense, let me know if I can assist further!

1 Like
11

Hey @Alan_G thanks for looking into this! My understanding is that the subscriptionBillingCycleScheduleEditmutation will only update a single billing cycle - so future billing cycles will be unaffected. The desired effect is updating ALL future billing cycles to a new date. We could in theory use this mutation to update several future billing cycles however I believe this is limited to 12 months in the future.

Is there no way to have Shopify re-calculate expected billing dates on all future billing cycles? I’m aware of anchor days but I don’t believe that is their intended use case and would introduce undue complexity

As an alternative solution for now I’ve elected not to use the Billing Cycles API to determine when subscriptions should be billed and delegated that responsibility to our own internal next billing date but that’s not ideal

12

Hey @jacksonmay. You’re right that subscriptionBillingCycleScheduleEdit only updates individual cycles.

My understanding is that updating the billing policy with new anchors on the source subscription contract should recalculate all future billing cycles automatically, which sounds like it may work for what you need for your use case.

I can’t see why this wouldn’t be a feasible approach for changing the recurring billing day, but let me check internally to confirm that using billing policy anchors this way is the recommended solution before we definitively suggest it as the workaround. I’ll loop back with you once I have more info, thanks again for bearing with me on this :slight_smile:

13

I too am having this issue. Rescheduling a subscription is critical, was there an update on how to have billing cycles updated properly?

If we elect to trigger billing based on our own tracked next billing date how does that work if the billing cycles are off? Or would it just try and find best case cycle in the attempt?

14

Hey @jacksonmay and @Richard_Sands - sorry for the delay here, wanted to make sure I had a solid answer before looping back. After digging into this more deeply with the subscriptions team on our end, I can confirm that nextBillingDate on the contract is essentially a storage field for apps, it’s not actually tied to billing cycle recalculation. I know that’s not ideal though (and the mutation name doesn’t make that super obvious), so I’m flagging the docs for a clarification on this.

For recalculating all future billing cycles, the intended path is updating the billing policy anchors on the source contract via a draft/commit flow (i.e., subscriptionContractUpdate to change the anchor day, then commit). Per the billing cycles docs, when billing policies change on the source contract, future cycles should recalculate automatically.

That said, I totally get that this isn’t as straightforward as just calling subscriptionContractSetNextBillingDate and having everything sync up, that’s fair feedback for sure. Let me know if you run into any issues with the anchor approach or if I can clarify anything else here.