Subscription Management
Update subscription contract status
Updates the status of a subscription contract to ACTIVE, PAUSED, or CANCELLED. This endpoint manages the lifecycle of subscriptions with automatic state tracking and notifications.
Status Transitions:
- ACTIVE: Resumes a paused subscription, enabling future billing and deliveries
- PAUSED: Temporarily suspends all billing and deliveries until manually resumed
- CANCELLED: Cancels the subscription and stops future billing and deliveries
Key Features:
- Sending the status the contract already has returns 204 and changes nothing, except ACTIVE on an active prepaid contract that is due to cancel at the end of its term. That call clears the pending cancellation (pendingCancellationCycle and pendingCancellationDate go back to null), so the contract is not cancelled when the term ends, but it does not restore the orders after the term that the cancellation removed. Check the upcoming orders afterwards
- Tracks status change timestamps for audit trails
- Sends automated email notifications to customers
- Creates detailed activity logs for each status change
- Handles concurrent modifications with automatic retry
- Adjusts the next billing date on resume when it has passed (see Resuming a paused subscription)
Status Change Side Effects:
- Activating: Marks the activation timestamp and schedules the upcoming orders again. The next billing date is kept or moved forward as described under Resuming a paused subscription
- Pausing: Stops all scheduled orders, marks pause timestamp
- Cancelling: Stops future billing and deliveries, marks cancellation timestamp
Resuming a paused subscription (status=ACTIVE):
- If the contract’s next billing date is still in the future, the call keeps it and schedules the upcoming orders from it
- If that date has passed, the call moves it forward to the first date after now on the contract’s billing schedule, so the next order can be up to one billing interval away. In this case the status can still read paused for a moment after the 204 before it changes to active
- When the next billing date arrives while the contract is paused, nothing is charged and Appstle moves the date on to the next scheduled order, so a date set when you pause is replaced if it arrives before you resume
- To resume with a specific first order date, set the next billing date while the contract is still PAUSED (PUT /api/external/v2/subscription-contracts-update-billing-date), then send ACTIVE as soon as that call returns 200. Contracts on plans with fixed billing dates cannot be rescheduled: that call returns 400 with errorKey fixedBillingScheduleRescheduleBlocked
Error Recovery: The system automatically handles:
- Invalid discount codes by removing them and retrying
- Concurrent modifications by retrying the operation
- This ensures reliable status updates in production environments
Important Notes:
- Send the status in uppercase: ACTIVE, PAUSED or CANCELLED. A lowercase value such as paused on an active contract returns 400 (see the Invalid Status Value example)
- PAUSED and ACTIVE on a cancelled contract move it out of cancelled, in Appstle and in Shopify, and ACTIVE also schedules its upcoming orders again, so read the status first
- CANCELLED cancels at once and does not apply the plan’s minimum number of billing cycles. To have the minimum enforced, use the cancel call (DELETE) instead
- A contract ID that is not one of your store’s contracts returns 400 with Contract does not exist
- Paused subscriptions retain all settings and can be resumed
- The customer gets the store’s pause, resume or cancellation email, unless the store has turned that email off. The call has no option to skip the email for one change. Sending the status the contract already has sends no email
Authentication: Requires valid X-API-Key header
PUT
/
api
/
external
/
v2
/
subscription-contracts-update-status
Update subscription contract status
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status"
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-status', 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-status';
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-status",
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-status"
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-status")
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_bodyQuery Parameters
Response
Status updated, or nothing to change because the contract already has that status. No content returned.
⌘I
Update subscription contract status
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status"
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-status', 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-status';
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-status",
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-status"
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-status")
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