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:

1. Activity Logging: Records quantity change with old/new values
2. BAB Discount Sync: Recalculates Build-a-Box volume discounts
3. Product Discount Sync: Updates product-specific discounts
4. 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

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

200

Success Response

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

200

application/json

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