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.

Full behavior, validation rules, and side effects

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:

1. Subscribe & Save: 10% off starting from 3rd order
2. Loyalty Tiers: 5% off after 3 orders, 10% after 6 orders
3. Introductory Pricing: First 2 orders at $9.99, then$14.99
4. 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/v2/subscription-contracts-update-line-item-pricing-policy

cURL

Subscribe & Save (10% off after 3 orders)

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 '
[
  {
    "afterCycle": 3,
    "discountType": "PERCENTAGE",
    "value": 10
  }
]
'

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "24.99",
            "currencyCode": "USD"
          },
          "pricingPolicy": {
            "basePrice": {
              "amount": "24.99",
              "currencyCode": "USD"
            },
            "cycleDiscounts": [
              {
                "afterCycle": 3,
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 10
                },
                "computedPrice": {
                  "amount": "22.49",
                  "currencyCode": "USD"
                }
              },
              {
                "afterCycle": 6,
                "adjustmentType": "PERCENTAGE",
                "adjustmentValue": {
                  "percentage": 15
                },
                "computedPrice": {
                  "amount": "21.24",
                  "currencyCode": "USD"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

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

200

application/json

Pricing policy successfully updated

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