Membership Contracts

Update product variant in subscription contract

Replaces an existing product variant with a new variant in a subscription contract. This allows customers to swap products in their membership while maintaining their subscription.

Key Features:

Product Swapping: Replace any line item’s variant with a different variant
Quantity Preservation: Maintains the same quantity after variant swap
Price Updates: New variant pricing is applied automatically
Flexible Identification: Identify old variant by lineId OR variantId
Activity Logging: All variant changes are logged for audit trail

Identification Methods: You can identify the old variant using either:

oldLineId: The Shopify line item ID from the subscription contract
oldVariantId: The Shopify product variant ID At least one of these must be provided.

Common Use Cases:

Customer wants to change product flavor/color/size in their membership
Swap discontinued products with new alternatives
Change product preferences mid-subscription
Update seasonal product selections
Replace out-of-stock variants with alternatives

Important Notes:

Immediate Effect: Variant change applies to the next billing cycle
Validation: System validates new variant exists and is available
Same Product: Old and new variants can be from different products
Price Changes: Customer is charged the new variant’s price

Variant ID Format:

Accepts both numeric IDs and GraphQL IDs (gid://shopify/ProductVariant/…)
System automatically converts to correct format

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

PUT

api

external

subscription-contract-update-variant

Update product variant in subscription contract

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant

import requests

url = "https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant"

response = requests.put(url)

print(response.text)

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant';
const options = {method: 'PUT'};

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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant"

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

	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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant")

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

request = Net::HTTP::Put.new(url)

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

{
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "completedAt": {},
        "createdAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  },
  "billingPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123
      }
    ],
    "get__typename": "<string>",
    "intervalCount": 123,
    "maxCycles": 123,
    "minCycles": 123
  },
  "createdAt": {},
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "customer": {
    "displayName": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "get__typename": "<string>",
    "id": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {}
  },
  "deliveryMethod": {
    "additionalInformation": {
      "get__typename": "<string>",
      "instructions": "<string>"
    },
    "brandedPromise": {
      "get__typename": "<string>",
      "handle": "<string>",
      "name": "<string>"
    },
    "get__typename": "<string>",
    "id": "<string>",
    "maxDeliveryDateTime": {},
    "minDeliveryDateTime": {},
    "serviceCode": "<string>"
  },
  "deliveryPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123
      }
    ],
    "get__typename": "<string>",
    "intervalCount": 123
  },
  "deliveryPrice": {
    "amount": {},
    "get__typename": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "createdAt": {},
        "deliveredAt": {},
        "estimatedDeliveryAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "inTransitAt": {},
        "name": "<string>",
        "requiresShipping": true,
        "service": {
          "get__typename": "<string>",
          "handle": "<string>",
          "serviceName": "<string>"
        },
        "trackingInfo": [
          {
            "company": "<string>",
            "get__typename": "<string>",
            "number": "<string>",
            "url": {}
          }
        ]
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "get__typename": "<string>",
  "id": "<string>",
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>"
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "nextBillingDate": {},
  "note": "<string>",
  "originOrder": {
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "get__typename": "<string>"
        }
      ],
      "pageInfo": {
        "endCursor": "<string>",
        "get__typename": "<string>",
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "<string>"
      }
    },
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>"
  },
  "updatedAt": {}
}

Headers

X-API-Key

string

Query Parameters

contractId

integer<int64>

required

Subscription contract ID

api_key

string

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

oldLineId

string

Line item ID to replace (provide either oldLineId or oldVariantId)

oldVariantId

string

Old variant ID to replace (provide either oldLineId or oldVariantId)

newVariantId

string

required

New variant ID to use as replacement

skipBilling

boolean

default:false

Skip billing on plan change (no charge or refund)

Response

Variant successfully updated in subscription contract

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

Cancel pending downgrade for a subscription contract

Create and add custom discount to subscription

Update product variant in subscription contract

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant

import requests

url = "https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant"

response = requests.put(url)

print(response.text)

const options = {method: 'PUT'};

fetch('https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant';
const options = {method: 'PUT'};

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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant"

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

	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://membership-admin.appstle.com/api/external/v2/subscription-contract-update-variant")

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

request = Net::HTTP::Put.new(url)

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

{
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "completedAt": {},
        "createdAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  },
  "billingPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123
      }
    ],
    "get__typename": "<string>",
    "intervalCount": 123,
    "maxCycles": 123,
    "minCycles": 123
  },
  "createdAt": {},
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "customer": {
    "displayName": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "get__typename": "<string>",
    "id": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {}
  },
  "deliveryMethod": {
    "additionalInformation": {
      "get__typename": "<string>",
      "instructions": "<string>"
    },
    "brandedPromise": {
      "get__typename": "<string>",
      "handle": "<string>",
      "name": "<string>"
    },
    "get__typename": "<string>",
    "id": "<string>",
    "maxDeliveryDateTime": {},
    "minDeliveryDateTime": {},
    "serviceCode": "<string>"
  },
  "deliveryPolicy": {
    "anchors": [
      {
        "cutoffDay": 123,
        "day": 123,
        "get__typename": "<string>",
        "month": 123
      }
    ],
    "get__typename": "<string>",
    "intervalCount": 123
  },
  "deliveryPrice": {
    "amount": {},
    "get__typename": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "createdAt": {},
        "deliveredAt": {},
        "estimatedDeliveryAt": {},
        "get__typename": "<string>",
        "id": "<string>",
        "inTransitAt": {},
        "name": "<string>",
        "requiresShipping": true,
        "service": {
          "get__typename": "<string>",
          "handle": "<string>",
          "serviceName": "<string>"
        },
        "trackingInfo": [
          {
            "company": "<string>",
            "get__typename": "<string>",
            "number": "<string>",
            "url": {}
          }
        ]
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "get__typename": "<string>",
  "id": "<string>",
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>"
      }
    ],
    "pageInfo": {
      "endCursor": "<string>",
      "get__typename": "<string>",
      "hasNextPage": true,
      "hasPreviousPage": true,
      "startCursor": "<string>"
    }
  },
  "nextBillingDate": {},
  "note": "<string>",
  "originOrder": {
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "get__typename": "<string>"
        }
      ],
      "pageInfo": {
        "endCursor": "<string>",
        "get__typename": "<string>",
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "<string>"
      }
    },
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>"
  },
  "updatedAt": {}
}