Update multiple properties of a subscription line item

Comprehensive endpoint for updating a subscription line item’s quantity, price, product variant, and/or selling plan in a single API call. Changes are applied intelligently - only modified values trigger updates.

Full behavior, validation rules, and side effects

Key Features:

• Update any combination of: quantity, price, variant, or selling plan
• Intelligent change detection - only updates what’s different
• Automatic handling of prepaid subscription pricing
• Preserves existing discount cycles when updating price
• Partial success allowed - some updates may fail while others succeed
• Each change creates separate activity log entries

Prepaid Subscription Handling: For prepaid subscriptions (billing interval > delivery interval):

• When isPricePerUnit=true: Price is multiplied by interval ratio
• Example: Monthly billing, weekly delivery = price × 4
• When isPricePerUnit=false: Price is used as total billing amount

Update Process:

1. Validates line item exists in the subscription
2. Calculates interval multiplier for prepaid logic
3. Updates in order: selling plan → price → quantity → variant
4. Each update uses separate Shopify GraphQL mutation
5. Failures are logged but don’t block other updates

Selling Plan Updates:

• Can update by ID or name (name takes precedence)
• Only updates if different from current plan
• Useful for changing delivery frequency options

Price Updates:

• Preserves existing discount cycles (up to 2 cycles)
• Recalculates cycle discounts based on new base price
• Triggers shipping price recalculation
• Sends price update email to customer

Quantity Updates:

• Validates against min/max quantity rules
• Updates Build-a-Box totals if applicable
• May trigger discount recalculations

Variant Updates:

• Changes the product itself (different SKU)
• Validates new variant exists and is available
• May affect pricing and discounts

Important Notes:

• All parameters except contractId and lineId are optional
• Provide only the values you want to change
• Price is always in shop’s base currency
• Changes apply to future orders only

Authentication: Requires valid X-API-Key header

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

Update multiple properties of a subscription line item

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-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",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "WEEK",
    "intervalCount": 1
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 3,
          "variantId": "gid://shopify/ProductVariant/98765432101",
          "title": "Premium Coffee - Medium Roast",
          "currentPrice": {
            "amount": "119.97",
            "currencyCode": "USD"
          },
          "pricingPolicy": {
            "basePrice": {
              "amount": "9.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "afterCycle": 3,
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                },
                "computedPrice": {
                  "amount": "107.97",
                  "currencyCode": "USD"
                }
              }
            ]
          },
          "sellingPlanId": "gid://shopify/SellingPlan/777777",
          "sellingPlanName": "Deliver every week"
        }
      }
    ]
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · integer<int64> · required

Subscription contract ID

Required range: x >= 1

api_key · string

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

quantity · integer

New quantity for the line item. Leave unchanged if not updating quantity.

Required range: 1 <= x <= 9999

variantId · string

New product variant ID in Shopify GID format (e.g., gid://shopify/ProductVariant/42549172011164). This updates the associated product. Leave this parameter blank if you are not switching products.

lineId · string · required

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

price · number<double>

New price for the line item in shop currency. Behavior depends on isPricePerUnit flag.

Required range: 0.01 <= x <= 999999.99

isPricePerUnit · boolean · default: false

Determines how price is interpreted for prepaid subscriptions:

• true: Price is per unit (per delivery), will be multiplied by interval ratio
• false: Price is total billing amount (for all deliveries in billing period)

Example: Monthly billing, weekly delivery, price=$10

• isPricePerUnit=true: Customer pays $40/month ($10 × 4 weeks)
• isPricePerUnit=false: Customer pays $10/month total

sellingPlanName · string

Name of the selling plan to apply. Takes precedence over current selling plan. Used to change delivery frequencies.

Maximum string length: 255

Response

200

application/json

Line item successfully updated

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