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

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"
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to remove products from

api_key

string

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

removeDiscount

boolean

default:false

When true, removes discounts that apply only to each removed line item. When false, attempts to retain all discounts. Discounts that apply to multiple lines are always retained regardless of this setting.

Body

application/json

Response

Products successfully removed from subscription (full or partial success)

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

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"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Remove multiple products from subscription

Headers

Query Parameters

Body

Response