Update selling plan for a subscription line item

Updates the selling plan associated with a specific product line item in a subscription contract. Selling plans define the delivery schedule, pricing rules, and billing policies for subscription products.

Full behavior, validation rules, and side effects

What are Selling Plans? Selling plans are Shopify’s way of defining subscription rules for products:

• Delivery Schedule: How often the product is delivered (e.g., ‘every 2 weeks’, ‘monthly’)
• Pricing Policy: Discounts and pricing tiers (e.g., ‘10% off’, ‘first order free’)
• Billing Policy: When and how often customer is charged
• Plan Name: Customer-facing description like ‘Deliver every month’

Key Features:

• Update by selling plan ID or name (name takes precedence if both provided)
• Validates line item exists before attempting update
• Only creates activity log if plan actually changes
• Uses Shopify’s draft system for safe updates
• Preserves existing line item attributes and customizations

Common Use Cases:

• Change delivery frequency: Weekly → Monthly
• Switch pricing tiers: Regular → VIP pricing
• Update from old plan to new plan with better terms
• Migrate products to new selling plan groups
• Apply seasonal or promotional plans

Update Process:

1. Validates subscription contract and line item exist
2. Creates a draft of the subscription contract
3. Updates the line item’s selling plan in the draft
4. Commits the draft to apply changes
5. Records activity log if plan changed

Impact of Selling Plan Changes:

• Delivery Schedule: Next and future orders follow new schedule
• Pricing: New plan’s pricing applies from next billing
• Discounts: Plan-specific discounts are recalculated
• Billing: Billing frequency may change with the plan

Finding Selling Plans: To find available selling plans:

1. Check product’s selling plan groups in Shopify admin
2. Use Shopify’s GraphQL API to query selling plans
3. Plans must be active and associated with the product

Important Notes:

• Both sellingPlanId and sellingPlanName are optional, but at least one required
• If both provided, both are updated (name doesn’t override ID)
• Plan must be valid for the product variant
• Changes apply to future orders only
• No customer notification sent (consider sending separately)

Authentication: Requires valid X-API-Key header

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

Update selling plan for a subscription line item

cURL

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

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/987654321",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "Premium Coffee - Dark Roast",
          "currentPrice": {
            "amount": "27.99",
            "currencyCode": "USD"
          },
          "sellingPlanId": "gid://shopify/SellingPlan/56789",
          "sellingPlanName": "Deliver every month",
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "afterCycle": 0,
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                }
              }
            ]
          }
        }
      }
    ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · integer<int64> · required

The unique identifier of the subscription contract

Required range: x >= 1

lineId · string · required

The unique identifier of the line item in the subscription contract. Must be in full GraphQL ID format

sellingPlanId · integer<int64>

The unique identifier of the new selling plan. Provide the numeric ID without gid:// prefix. Required if sellingPlanName is not provided. The plan must be:

• Active in your Shopify store
• Associated with the product variant
• Part of an active selling plan group

Required range: x >= 1

sellingPlanName · string

The customer-facing name of the new selling plan. Required if sellingPlanId is not provided. This is the name shown to customers like 'Deliver every 2 weeks' or 'Monthly subscription'. Must match exactly as configured in Shopify

Maximum string length: 255

Response

200

application/json

Selling plan 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