Subscription Management

Update maximum cycles for a subscription contract

Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders.

What are Maximum Cycles? Maximum cycles define subscription duration limits where:

Subscription automatically cancels after the specified number of orders
No further orders are generated once maximum is reached
Useful for fixed-term offers, trials, or seasonal subscriptions
Customer is notified before final order (if configured)

Key Features:

Cannot set below current cycle count (prevents immediate cancellation)
Setting to null creates an indefinite subscription
Automatically reschedules order queue based on new limit
Preserves all other subscription settings
Validates against current subscription progress

Current Cycle Calculation:

Current cycle = Successful billing attempts + 1
Failed payments don’t count toward maximum
First order is cycle 1, second is cycle 2, etc.
System prevents setting max below current position

Common Use Cases:

Trial Subscriptions: ‘3-box trial’ that auto-ends
Seasonal Programs: ‘6-month summer subscription’
Limited Series: ‘12-issue magazine subscription’
Promotional Offers: ‘First 5 boxes at special price’
Gift Subscriptions: Fixed duration gifts that don’t renew

What Happens at Maximum: When a subscription reaches its maximum cycles:

Final order is processed normally
Subscription status changes to CANCELLED
No future orders are scheduled
Customer receives cancellation notification
Cannot be reactivated (new subscription required)

Interaction with Min Cycles:

Can have both min and max (e.g., 3 min, 12 max)
Min cycles enforces commitment period
Max cycles enforces termination
Common pattern: Commitment with defined end

Queue Management: After updating max cycles:

System recalculates future order schedule
Removes orders beyond the new maximum
Adjusts upcoming order notifications
Updates subscription end date projections

Important Notes:

Validation prevents accidental immediate cancellation
Changes apply to future billing cycles only
Activity log tracks old and new values
Consider customer communication for changes
Setting null removes any duration limit

Authentication: Requires valid X-API-Key header

PUT

api

external

subscription-contracts-update-max-cycles

Update maximum cycles for a subscription contract

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles

import 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

{
  "billingPolicy": {
    "anchors": [
      {
        "day": 15,
        "type": "MONTHDAY"
      }
    ],
    "interval": "MONTH",
    "intervalCount": 1,
    "maxCycles": 12,
    "minCycles": 3
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "customer": {
    "displayName": "John Doe",
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lastBillingAttemptDate": "2024-03-01T00:00:00Z",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "39.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "title": "12-Month Subscription Box",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "orders": {
    "edges": [
      {
        "node": {
          "createdAt": "2024-03-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901234"
        }
      },
      {
        "node": {
          "createdAt": "2024-02-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901233"
        }
      },
      {
        "node": {
          "createdAt": "2024-01-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901232"
        }
      }
    ]
  },
  "status": "ACTIVE"
}

Headers

X-API-Key

string

Query Parameters

contractId

integer<int64>

required

Contract ID

api_key

string

API Key (Deprecated - Use Header X-API-Key instead)

maxCycles

integer | null

required

Maximum Cycles. The total number of orders after which the subscription will automatically terminate. Must be greater than or equal to the current cycle count and any configured minimum cycles. Common values:

3: Three-order trial
6: Six-month seasonal subscription
12: Annual subscription
24: Two-year commitment
null: Ongoing subscription with no end date

Required range: 1 <= x <= 9999

Response

Maximum cycles updated successfully

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

Update delivery price for a subscription contract

Update minimum cycles for a subscription contract

Update maximum cycles for a subscription contract

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles

import 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

{
  "billingPolicy": {
    "anchors": [
      {
        "day": 15,
        "type": "MONTHDAY"
      }
    ],
    "interval": "MONTH",
    "intervalCount": 1,
    "maxCycles": 12,
    "minCycles": 3
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "customer": {
    "displayName": "John Doe",
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lastBillingAttemptDate": "2024-03-01T00:00:00Z",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "39.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "title": "12-Month Subscription Box",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "orders": {
    "edges": [
      {
        "node": {
          "createdAt": "2024-03-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901234"
        }
      },
      {
        "node": {
          "createdAt": "2024-02-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901233"
        }
      },
      {
        "node": {
          "createdAt": "2024-01-01T00:00:00Z",
          "financialStatus": "PAID",
          "fulfillmentStatus": "FULFILLED",
          "id": "gid://shopify/Order/5678901232"
        }
      }
    ]
  },
  "status": "ACTIVE"
}