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:

1. First item validated and removed
2. Second item validated against updated state
3. Continue until all processed or error occurs
4. 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

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

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]"
  },
  "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

200

application/json

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