Update next billing date for a subscription contract
Reschedules the next billing date for an active or paused subscription contract. This endpoint allows you to change when the next order will be created and processed.
Key Features:
- Updates the next billing date to the specified date
- Optionally reschedules all future orders based on the new date
- Syncs the updated date to Shopify
- Sends the store’s Next Order Date Updated email to the customer, unless a store setting stops it (see Important Notes)
The rescheduleFutureOrder Parameter:
- true (default): Updates the next billing date AND recalculates all future queued orders based on the new date. Use this to shift the entire billing schedule.
- false: Moves only the next order. The later queued orders keep their dates. Use it only to move the next order to a date before the order that follows it. If the new date is past later orders, those orders don’t move: Appstle still bills each of them on its own date, and the moved order stays queued for the new date. After the first of them bills, the contract’s next billing date goes back to the next order still queued. Until then, GET /api/external/v2/subscription-billing-attempts/top-orders lists only orders on or after the next billing date, so those orders don’t appear there. To move the next order past the one after it, send true or leave the parameter out.
Important Notes:
- The new date must be in the future. A date more than 10 minutes in the past returns 400 with a title starting The billing date you are trying to set, and a date less than 10 minutes in the past returns 400 with
UserGeneratedError:Next billing date is invalid - Date is validated against the shop’s timezone
- If anchor days are configured, future orders may align to those anchors
- The contract can also be PAUSED: the call saves the date and the contract stays paused. To resume on that date, send status=ACTIVE with PUT /api/external/v2/subscription-contracts-update-status, and the upcoming orders then follow the date. If the date arrives while the contract is still paused, Appstle moves it on to the next scheduled order
- Contracts on plans with fixed billing dates cannot be rescheduled. The call returns 400 with errorKey fixedBillingScheduleRescheduleBlocked and
UserGeneratedError:Fixed billing schedule subscriptions cannot be rescheduled. The next order date follows the plan's fixed billing dates. - A successful call sends the customer the store’s Next Order Date Updated email (subject “Your next order date has been updated!” by default). No request parameter skips it, whether rescheduleFutureOrder is true or false. Two store settings stop it: the email is turned off under More → Notification Settings, or the contract is paused and Disable notifications for paused or canceled subscriptions is on under Shop Settings
- The store’s Appstle plan must include next billing date changes. API access alone isn’t enough, and scoped partner tokens need it too. Stores that choose a paid plan today get it, and the Free plan doesn’t include it. A store that chose its plan earlier, or is on a custom plan, may not have it: support@appstle.com can check. Without it, the call returns
400witherrorKeypermissionDeniedand the messageUserGeneratedError:Upgrade your plan to modify next billing date.
Process Flow:
- Validates the contract exists and belongs to the shop
- Validates the new date is not in the past
- Updates the billing attempt to the new date
- Syncs the updated nextBillingDate to Shopify
- If rescheduleFutureOrder=true, regenerates the queue from the new date
- Sends the Next Order Date Updated email to the customer, unless a store setting stops it
- Records activity log entry
Date Format:
- Must be ISO 8601 format with timezone
- Examples:
2024-03-15T12:00:00Z,2024-03-15T12:00:00+05:30 - URL encode the date when passing as query parameter
Timezone Handling:
- The provided date is used as-is for the billing attempt
- Validation (past date check) uses the shop’s configured timezone
- All dates in the response are in UTC (Z suffix)
Date Restrictions (Customer Portal Only): When called from customer portal context:
- Minimum days from today (skipDaysFromCurrentDate setting)
- Maximum days from today (billingDateRestrictToDays setting)
- External API calls bypass these restrictions
Authentication: Requires valid X-API-Key header
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.put(url, headers=headers)
print(response.text)const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date"
req, _ := http.NewRequest("PUT", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingPolicy": {
"interval": "MONTH",
"intervalCount": 1
},
"customer": {
"displayName": "John Doe",
"email": "customer@example.com"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2024-03-15T12:00:00Z",
"status": "ACTIVE",
"updatedAt": "2024-02-15T10:30:00Z"
}Query Parameters
If true (or value not provided), next billing date will be changed and also schedule for future upcoming orders will be changed based on new updated billing date. If false, then only next billing date will be changed, but the schedule for future upcoming orders will not change.
New billing date in ISO 8601 format with timezone. The date must be in the future and may be subject to merchant-configured restrictions. Common formats:
- UTC: 2024-03-15T12:00:00Z
- With offset: 2024-03-15T12:00:00+05:30
- With timezone: 2024-03-15T12:00:00[America/New_York]
The system will convert the date to the shop's timezone for validation.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2}|\[.+\])$Response
Billing date successfully updated. The response contains the updated subscription contract from Shopify with the new nextBillingDate.
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.put(url, headers=headers)
print(response.text)const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date"
req, _ := http.NewRequest("PUT", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingPolicy": {
"interval": "MONTH",
"intervalCount": 1
},
"customer": {
"displayName": "John Doe",
"email": "customer@example.com"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2024-03-15T12:00:00Z",
"status": "ACTIVE",
"updatedAt": "2024-02-15T10:30:00Z"
}