Update maximum cycles for a subscription contract
Sets the maximum number of orders a subscription contract can place. Once the contract has placed that many orders, no more orders are scheduled or charged.
What counts toward the maximum
The first order (the order placed at checkout) and every successful billing order after it. A contract that has placed 5 orders can’t be given a maximum below 5: the call returns 400.
What happens when the maximum is reached
- The contract isn’t cancelled. It is paused after its last order if the store’s Auto-pause subscriptions after maximum orders reached setting is on (Shop Settings, under Additional Order Settings). If the setting is off, the contract stays
ACTIVEwith no upcoming orders. - A paused contract can be resumed with
PUT /api/external/v2/subscription-contracts-update-status, but while the maximum is reached, resuming schedules no new orders. Raise the maximum to let the contract place more.
Changing the maximum
maxCyclesis required and must be a whole number of at least 1. This endpoint can’t remove a maximum: an emptymaxCyclesreturns400.- The contract’s upcoming orders are rebuilt to match the new maximum. This runs in the background, so upcoming orders fetched straight after the call can still show the old schedule.
- A gift subscription’s maximum can’t be changed, because it ends after its prepaid deliveries: the call returns
400with theerrorKeygiftMaxCyclesChangeBlocked. - If Shopify rejects the change, the call returns
400with atitlethat starts withUserGeneratedError:, followed by Shopify’s message. - The change is recorded in the contract’s activity log.
Authentication: Requires a valid X-API-Key header with a Read & Write key. A Read only key returns 403.
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cyclesimport requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles"
response = requests.put(url)
print(response.text)const options = {method: 'PUT'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles', 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-max-cycles';
const options = {method: 'PUT'};
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-max-cycles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
]);
$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-max-cycles"
req, _ := http.NewRequest("PUT", url, nil)
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-max-cycles")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingPolicy": {
"__typename": "SubscriptionBillingPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1,
"maxCycles": 5,
"minCycles": null
},
"createdAt": "2026-11-09T14:07:10Z",
"customer": {
"__typename": "Customer",
"displayName": "Jane Cooper",
"email": "jane.cooper@example.com",
"id": "gid://shopify/Customer/7890123456789"
},
"deliveryPolicy": {
"__typename": "SubscriptionDeliveryPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1
},
"id": "gid://shopify/SubscriptionContract/123456789012",
"lines": {
"__typename": "SubscriptionLineConnection",
"nodes": [
{
"__typename": "SubscriptionLine",
"currentPrice": {
"__typename": "MoneyV2",
"amount": "19.8",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"quantity": 1,
"sellingPlanName": "Monthly Subscription",
"title": "Ethiopia Coffee",
"variantId": "gid://shopify/ProductVariant/45678901234567"
}
]
},
"nextBillingDate": "2026-12-09T14:00:00Z",
"status": "PAUSED",
"updatedAt": "2026-11-10T10:07:55Z"
}Query Parameters
Response
The contract after the change, with the new maximum in billingPolicy.maxCycles. The example is shortened: the response also has revisionId, deliveryPrice, lastPaymentStatus, customerPaymentMethod, deliveryMethod, originOrder, discounts, note, customAttributes and billingAttempts, and more fields on each line and on the customer.
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cyclesimport requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles"
response = requests.put(url)
print(response.text)const options = {method: 'PUT'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles', 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-max-cycles';
const options = {method: 'PUT'};
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-max-cycles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
]);
$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-max-cycles"
req, _ := http.NewRequest("PUT", url, nil)
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-max-cycles")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
response = http.request(request)
puts response.read_body{
"__typename": "SubscriptionContract",
"billingPolicy": {
"__typename": "SubscriptionBillingPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1,
"maxCycles": 5,
"minCycles": null
},
"createdAt": "2026-11-09T14:07:10Z",
"customer": {
"__typename": "Customer",
"displayName": "Jane Cooper",
"email": "jane.cooper@example.com",
"id": "gid://shopify/Customer/7890123456789"
},
"deliveryPolicy": {
"__typename": "SubscriptionDeliveryPolicy",
"anchors": [],
"interval": "MONTH",
"intervalCount": 1
},
"id": "gid://shopify/SubscriptionContract/123456789012",
"lines": {
"__typename": "SubscriptionLineConnection",
"nodes": [
{
"__typename": "SubscriptionLine",
"currentPrice": {
"__typename": "MoneyV2",
"amount": "19.8",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"quantity": 1,
"sellingPlanName": "Monthly Subscription",
"title": "Ethiopia Coffee",
"variantId": "gid://shopify/ProductVariant/45678901234567"
}
]
},
"nextBillingDate": "2026-12-09T14:00:00Z",
"status": "PAUSED",
"updatedAt": "2026-11-10T10:07:55Z"
}