Subscription Products
Update line item pricing policy with cycle-based discounts
Sets up advanced pricing rules for a subscription line item that change based on the number of successful orders (cycles). This powerful feature enables loyalty discounts, promotional pricing tiers, and subscribe-and-save models.
What are Pricing Policies? Pricing policies define how a product’s price changes over the subscription lifetime:
- Base Price: Starting price for the product
- Cycle Discounts: Price changes after specific numbers of orders
- Automatic Application: System applies correct price based on order history
Supported Discount Types:
- PERCENTAGE: Percentage off base price (e.g., 10% off)
- FIXED: Fixed amount off base price (e.g., $5 off)
- PRICE: Override with new fixed price (e.g., $19.99) Note: SHIPPING and FREE_PRODUCT types are not supported by this endpoint
Cycle Counting:
- Cycles start at 1 (first order is cycle 1)
- Only successful billing attempts count
- Failed payments don’t increment the cycle
- Current cycle = 1 + count of successful past orders
Common Use Cases:
- Subscribe & Save: 10% off starting from 3rd order
- Loyalty Tiers: 5% off after 3 orders, 10% after 6 orders
- Introductory Pricing: First 2 orders at 9.99,then14.99
- Promotional Periods: Special price for orders 3-5
Important Limitations:
- The store’s Appstle plan must include contract price changes. API access alone isn’t enough, and scoped partner tokens need it too. Stores that choose a paid plan today get it, and the Free plan doesn’t include it. A store that chose its plan earlier, or is on a custom plan, may not have it: support@appstle.com can check. Without it, the call returns
400witherrorKeypermissionDeniedand the messageUserGeneratedError:Upgrade your plan to modify contract price. - Maximum 2 cycle discounts per line item
- Cycles must have different afterCycle values
- Changes apply to future orders only
- Existing orders keep their original pricing
Prepaid Subscription Handling: For prepaid subscriptions (e.g., pay monthly for weekly delivery):
- Base price is per delivery
- Current price = base price × delivery frequency
- Discounts apply to base price, then multiply
Side Effects:
- Sends price update email to customer
- Recalculates Build-a-Box discounts
- Updates product discount synchronization
- Triggers shipping price recalculation
- Creates detailed activity log
Authentication: Requires valid X-API-Key header
PUT
/
api
/
external
/
v2
/
subscription-contracts-update-line-item-pricing-policy
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-pricing-policy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '[]'{
"id": "gid://shopify/SubscriptionContract/123456789",
"lines": {
"edges": [
{
"node": {
"currentPrice": {
"amount": "24.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/111111",
"pricingPolicy": {
"basePrice": {
"amount": "24.99",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 10
},
"afterCycle": 3,
"computedPrice": {
"amount": "22.49",
"currencyCode": "USD"
}
},
{
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 15
},
"afterCycle": 6,
"computedPrice": {
"amount": "21.24",
"currencyCode": "USD"
}
}
]
},
"quantity": 1,
"variantId": "gid://shopify/ProductVariant/42549172011164"
}
}
]
},
"status": "ACTIVE"
}Query Parameters
Body
application/json
List of cycle-based pricing rules. Maximum 2 cycles, must have unique afterCycle values
The body is of type string.
Response
Pricing policy successfully updated
⌘I
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-pricing-policy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '[]'{
"id": "gid://shopify/SubscriptionContract/123456789",
"lines": {
"edges": [
{
"node": {
"currentPrice": {
"amount": "24.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionLine/111111",
"pricingPolicy": {
"basePrice": {
"amount": "24.99",
"currencyCode": "USD"
},
"cycleDiscounts": [
{
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 10
},
"afterCycle": 3,
"computedPrice": {
"amount": "22.49",
"currencyCode": "USD"
}
},
{
"adjustmentType": "PERCENTAGE",
"adjustmentValue": {
"percentage": 15
},
"afterCycle": 6,
"computedPrice": {
"amount": "21.24",
"currencyCode": "USD"
}
}
]
},
"quantity": 1,
"variantId": "gid://shopify/ProductVariant/42549172011164"
}
}
]
},
"status": "ACTIVE"
}