Remove product from subscription

Removes a specific product line item from an existing subscription contract. Can optionally retain prorated discounts associated with the removed product.

Full behavior, validation rules, and side effects

Key Features:

• Validates minimum subscription requirements before removal
• Handles discount cleanup for line-specific discounts
• Enforces minimum cycle commitments on products
• Supports Build-a-Box quantity validation
• Automatic retry on concurrent modification conflicts
• Email notifications for subscription changes

Validation Rules:

• At least one recurring subscription product must remain after removal
• One-time products and free products don’t count toward the minimum
• Products with minimum cycle commitments cannot be removed until fulfilled
• Build-a-Box subscriptions validate against minimum/maximum quantity rules

Discount Handling: When removeDiscount=true (default):

• Discounts applied only to the removed line item are deleted
• Discounts applied to multiple line items are retained
• System automatically identifies which discounts to remove

Retry Mechanism: The endpoint automatically retries in these scenarios:

• Concurrent modification detected (another process updated the subscription)
• Invalid discount code errors (removes problematic discount and retries)
• This ensures reliable operation in high-traffic environments

Post-Removal Actions:

• Activity log created for audit trail
• Email notification sent to customer
• Shipping price recalculated asynchronously
• Build-a-Box discounts resynced if applicable
• Product-specific discounts resynced

Authentication: Requires valid X-API-Key header

PUT /api/external/v2/subscription-contracts-remove-line-item

Remove product from subscription

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-item \
  --header 'X-API-Key: <x-api-key>'

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "sellingPlanId": "gid://shopify/SellingPlan/123456",
          "sellingPlanName": "Deliver every month"
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/999999",
          "title": "10% OFF SUBSCRIPTION",
          "targetType": "ALL_LINES",
          "value": {
            "percentage": 10
          }
        }
      }
    ]
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · string · required

Subscription contract ID to remove product from. Provide the numeric ID without the gid:// prefix

Pattern: ^[0-9]+$

api_key · string

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

lineId · string · required

Line item ID of the product to remove. Must be the full GraphQL ID including the gid:// prefix

removeDiscount · boolean · default: true

Controls whether to remove discounts that apply only to this line item. When true (default), line-specific discounts are removed. When false, attempts to retain discounts where possible. Note: Discounts that apply to multiple lines are always retained regardless of this setting

Response

200

application/json

Product successfully removed from subscription

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