Migration Subscription Contracts

Hello, we’re trying to migrate subscriptions contracts for our Client from one store to another.
So we’ve followed this guide

But the problem here is that we are not able to set flexible first billing cycle for each customer.
For example we have 1 year subscription. And some of customers already paid for it 11 months ago - so next billing should be in 1 month. For some of them in 2-3 months.

For all customers first cycle will be from Jan 2026 to Jan 2027

There is a nextBillingDate field in subscriptionContractAtomicCreate mutaiton, but it won’t change anything and it’s only for developers to use. But our Billing system relies on Cycles, not dates.
It would be cool to be able to create contracts with first cycle started in the past or may be to have first cycle with flexible dates, otherwise Cycles are not an stable option for subscriptions

1 Like

Hi @Artem_Fokin,

Since you’re wanting all of the yearly billing cycles to start from January 2026, but want to bill the customers with customized dates within the cycle, I would recommend creating the Subscription Contracts with the Anchor Date set to the first of January, then editing the individual billing cycles after the fact to change the billing date of each individual cycle with the subscriptionBillingCycleScheduleEdit mutation.

Here’s an example subscriptionContractAtomicCreate mutation setting the Anchor date to January 1st. This will create a Subscription Contract with cycles going from January 1st to December 31st, with the first cycle being billed on December 31st 2026, the end of the billing cycle.

mutation {
  subscriptionContractAtomicCreate(input: {
    customerId: "gid://shopify/Customer/123",
    nextBillingDate: "2026-01-01",  # Just metadata for your tracking
    currencyCode: USD,
    contract: {
      status: ACTIVE,
      billingPolicy: {
        interval: YEAR,
        intervalCount: 1,
        anchors: [{
          type: YEARDAY,
          day: 1,      
          month: 1    
        }]
      },
      deliveryPolicy: {
        interval: YEAR,
        intervalCount: 1,
        anchors: [{
          type: YEARDAY,
          day: 1,
          month: 1
        }]
      }
      # ... rest of contract
    }
  }) {
    contract { id }
  }
}

If you want to edit the billing date of a specific cycle, for example if the first cycle you want to bill the customer on February 1st instead, you can do so with the subscriptionBillingCycleScheduleEdit mutation, here’s an example editing the billing date of the first cycle for a customer that paid 11 months ago to February 1st 2026:

mutation {
  subscriptionBillingCycleScheduleEdit(
    billingCycleInput: {
      contractId: "gid://shopify/SubscriptionContract/123",
      selector: { index: 1 }  # First cycle (Jan 2026 - Jan 2027)
    },
    input: {
      billingDate: "2026-02-01",  # Bill in Feb 2025
      reason: DEV_INITIATED
    }
  ) {
    billingCycle {
      cycleIndex
      cycleStartAt        # Should be ~Jan 1st 2026
      cycleEndAt          # Should be ~Dec 31st 2026
      billingAttemptExpectedDate  # Should be Feb 1st 2026
    }
  }
}

This does only edit the billing date for the individual cycle, and all future cycles will default back to the end of the billing cycle, December 31st. If you’d rather have the individual customers maintain their own individual billing dates permanently, you should instead create the contracts with the anchors set to the correct billing date to begin with, rather than setting the anchor to January 1st.

Here’s some Shopify.dev documentation with more information on managing Billing Cycles and Selling Plan Anchor dates:

Hi @Artem_Fokin,

I just wanted to follow up here and see if this helped answer your questions on this topic? If so we can go ahead and mark the thread as solved, otherwise let us know any additional questions you have and we can help further

Hello, thanks for detailed response, anchor might work.
Now 4 Feb 2026, i’ve created contract with anchor to 10 Feb every year

so cycles created with correct dates:


 {

"cycleIndex": 2,

"billingAttemptExpectedDate": "2027-02-10T10:00:00Z",

"cycleStartAt": "2026-02-10T10:00:01Z",

"cycleEndAt": "2027-02-10T10:00:00Z"

},

{

"cycleIndex": 1,

"billingAttemptExpectedDate": "2026-02-10T10:00:00Z",

"cycleStartAt": "2026-02-04T10:31:07Z",

"cycleEndAt": "2026-02-10T10:00:00Z"

}

so first cycle started at the day of creation, and ended at anchor date, other’s cycles also use anchor date for start/end, so i suppose subscriptionBillingCycleBulkCharge mutation will work correctly