Subscription Products

Update product line item quantity in subscription

Updates the quantity of a specific product line item within a subscription contract. This comprehensive operation handles quantity validation, discount recalculation, and special Build-a-Box constraints.

Full behavior, validation rules, and side effects

Key Features:

Updates quantity for future orders only
Validates minimum/maximum quantities for line items
Special handling for Build-a-Box subscriptions
Automatic discount recalculation
Shipping price updates
Activity log tracking with old/new values

Build-a-Box (BAB) Validation: For Build-a-Box subscriptions:

Enforces total minimum/maximum item counts
Only counts recurring products (excludes one-time and free items)
Validates across all BAB items in the subscription
Can be bypassed with ‘allowToAddProductQuantityMinMaxReached’ permission

Line Item Validation: Individual products may have:

Minimum quantity requirements (min_quantity attribute)
Maximum quantity limits (max_quantity attribute)
These are enforced separately from BAB constraints

Post-Update Actions:

Activity Logging: Records quantity change with old/new values
BAB Discount Sync: Recalculates Build-a-Box volume discounts
Product Discount Sync: Updates product-specific discounts
Shipping Price Update: Recalculates shipping based on new quantity

Discount Recalculation:

Build-a-Box discounts adjust based on total quantity tiers
May remove old discount codes and apply new ones
Handles ‘subscription contract has changed’ retry scenarios

Important Notes:

Line ID must be the full GraphQL ID format
Quantity must be positive (minimum 1)
Changes apply to all future orders
Past or in-progress orders are not affected

Authentication: Requires valid X-API-Key header

PUT

/

api

/

external

/

v2

/

subscription-contracts-update-line-item-quantity

Update product line item quantity in subscription

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

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 3,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "Premium Coffee - Dark Roast",
          "currentPrice": {
            "amount": "44.97",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_min_quantity",
              "value": "1"
            },
            {
              "key": "_max_quantity",
              "value": "5"
            }
          ]
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/222222",
          "title": "BUILD_A_BOX_DISCOUNT_ABC123",
          "targetType": "ALL_LINES",
          "value": {
            "percentage": 15
          }
        }
      }
    ]
  }
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to update. Provide the numeric ID without the gid:// prefix

Required range: x >= 1

api_key

string

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

quantity

integer

required

New quantity for the line item. Must be a positive integer

Required range: 1 <= x <= 9999

lineId

string

required

Line item ID to update. Must be the full GraphQL ID including the gid:// prefix

Response

Product line item quantity updated successfully

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 selling plan for a subscription line item

Update line item pricing policy with cycle-based discounts

Update product line item quantity in subscription

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

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 3,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "Premium Coffee - Dark Roast",
          "currentPrice": {
            "amount": "44.97",
            "currencyCode": "USD"
          },
          "customAttributes": [
            {
              "key": "_min_quantity",
              "value": "1"
            },
            {
              "key": "_max_quantity",
              "value": "5"
            }
          ]
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/222222",
          "title": "BUILD_A_BOX_DISCOUNT_ABC123",
          "targetType": "ALL_LINES",
          "value": {
            "percentage": 15
          }
        }
      }
    ]
  }
}