Subscription Products
Remove multiple products from subscription
Removes multiple product line items from an existing subscription contract in a single request. Products are removed sequentially, allowing partial success if errors occur.
Key Features:
- Sequential processing - items removed one by one
- Partial success allowed - previous removals persist if later ones fail
- Validates each removal against current subscription state
- Smart discount cleanup for line-specific discounts
- Comprehensive validation for each product removal
- Triggers all side effects after each successful removal
Processing Order Matters: Items are removed in the order provided:
- First item validated and removed
- Second item validated against updated state
- Continue until all processed or error occurs
- Returns final subscription state
Validation Per Item:
- Line item must exist in subscription
- At least one recurring product must remain
- Build-a-Box min/max quantities maintained
- Minimum cycle commitments honored
- One-time and free products don’t count toward minimum
Discount Handling:
When removeDiscount=true:
- Removes discounts applied ONLY to the removed line
- Preserves discounts that apply to multiple lines
- Each removal evaluates discounts independently
- Build-a-Box discounts auto-adjust based on quantity
Side Effects Per Removal: Each successful removal triggers:
- Activity log entry created
- Customer email sent
- Shipping price recalculation
- Build-a-Box discount resync
- Product discount adjustments
Partial Success Scenarios: If removing 3 items and the 2nd fails:
- 1st item: Successfully removed
- 2nd item: Fails, error returned
- 3rd item: Not attempted
- Result: Subscription with 1st item removed
Performance Considerations:
- Each removal is a separate Shopify API transaction
- Multiple emails may be sent to customer
- Consider using single remove for 1-2 items
- Large batches may timeout
- Recommended max: 5-10 items per request
Build-a-Box Handling: For Build-a-Box subscriptions:
- Validates total quantity after EACH removal
- May fail mid-batch if minimum breached
- Discounts recalculate after each item
- Consider removal order carefully
Important Notes:
- NOT atomic - no rollback on partial failure
- Order of line IDs affects success probability
- Customer receives email per removed item
- All validations apply as if removing individually
- Response shows final state after all attempts
Authentication: Requires valid X-API-Key header
PUT
/
api
/
external
/
v2
/
subscription-contracts-remove-line-items
Remove multiple products from subscription
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '[
"<string>"
]'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items"
payload = ["<string>"]
headers = {
"X-API-Key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify(['<string>'])
};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items', 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-remove-line-items';
const options = {
method: 'PUT',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify(['<string>'])
};
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-remove-line-items",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items"
payload := strings.NewReader("[\n \"<string>\"\n]")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-API-Key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
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-remove-line-items")
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>'
request["Content-Type"] = 'application/json'
request.body = "[\n \"<string>\"\n]"
response = http.request(request)
puts response.read_body{
"customer": {
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"discounts": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionManualDiscount/444444",
"targetType": "ALL_LINES",
"title": "10% OFF ALL ITEMS"
}
}
]
},
"id": "gid://shopify/SubscriptionContract/123456789",
"lines": {
"edges": [
{
"node": {
"currentPrice": {
"amount": "19.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/333333",
"quantity": 1,
"title": "Essential Product - Monthly",
"variantId": "gid://shopify/ProductVariant/42549172076700"
}
}
]
},
"nextBillingDate": "2024-04-01T00:00:00Z",
"status": "ACTIVE"
}Query Parameters
Body
application/json
Response
Products successfully removed from subscription (full or partial success)
⌘I
Remove multiple products from subscription
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '[
"<string>"
]'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items"
payload = ["<string>"]
headers = {
"X-API-Key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify(['<string>'])
};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items', 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-remove-line-items';
const options = {
method: 'PUT',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify(['<string>'])
};
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-remove-line-items",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items"
payload := strings.NewReader("[\n \"<string>\"\n]")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-API-Key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
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-remove-line-items")
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>'
request["Content-Type"] = 'application/json'
request.body = "[\n \"<string>\"\n]"
response = http.request(request)
puts response.read_body{
"customer": {
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"discounts": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionManualDiscount/444444",
"targetType": "ALL_LINES",
"title": "10% OFF ALL ITEMS"
}
}
]
},
"id": "gid://shopify/SubscriptionContract/123456789",
"lines": {
"edges": [
{
"node": {
"currentPrice": {
"amount": "19.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/333333",
"quantity": 1,
"title": "Essential Product - Monthly",
"variantId": "gid://shopify/ProductVariant/42549172076700"
}
}
]
},
"nextBillingDate": "2024-04-01T00:00:00Z",
"status": "ACTIVE"
}