Subscription Products

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.

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:

Validates subscription contract and line item exist
Creates a draft of the subscription contract
Updates the line item’s selling plan in the draft
Commits the draft to apply changes
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:

Check product’s selling plan groups in Shopify admin
Use Shopify’s GraphQL API to query selling plans
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

subscription-contracts-update-line-item-selling-plan

Update selling plan for a subscription line item

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "27.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/987654321",
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                },
                "afterCycle": 0
              }
            ]
          },
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/56789",
          "sellingPlanName": "Deliver every month",
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE"
}

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

Selling plan updated successfully

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

Update product line item quantity in subscription

Get all one-time products for a subscription contract

Update selling plan for a subscription line item

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

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "customer": {
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "27.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/987654321",
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                },
                "afterCycle": 0
              }
            ]
          },
          "quantity": 2,
          "sellingPlanId": "gid://shopify/SellingPlan/56789",
          "sellingPlanName": "Deliver every month",
          "title": "Premium Coffee - Dark Roast",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE"
}