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.

Full behavior, validation rules, and side effects

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>"
]'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/333333",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172076700",
          "title": "Essential Product - Monthly",
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/444444",
          "title": "10% OFF ALL ITEMS",
          "targetType": "ALL_LINES"
        }
      }
    ]
  }
}

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)

get__typename

string

id

string

createdAt

object

updatedAt

object

nextBillingDate

object

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

deliveryPrice

object

Show child attributes

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

billingPolicy

object

Show child attributes

deliveryPolicy

object

Show child attributes

lines

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

originOrder

object

Show child attributes

customer

object

Show child attributes

discounts

object

Show child attributes

note

string

customAttributes

object[]

Show child attributes

billingAttempts

object

Show child attributes

Update product line item price

Remove product from subscription

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>"
]'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/333333",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172076700",
          "title": "Essential Product - Monthly",
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/444444",
          "title": "10% OFF ALL ITEMS",
          "targetType": "ALL_LINES"
        }
      }
    ]
  }
}