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, then$ 14.99
Promotional Periods: Special price for orders 3-5

Important Limitations:

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

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"
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

api_key

string

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

contractId

integer<int64>

required

Subscription contract ID

Required range: x >= 1

lineId

string

required

Line item ID to update. Must be full GraphQL ID format

basePrice

number<double>

required

Base price for the product (before any discounts). This is the starting price

Required range: 0.01 <= x <= 999999.99

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

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 price

Update product line item quantity in subscription

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"
}