Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications.
External APIs
/- Update line item pricing policy with cycle-based discounts
Update multiple properties of a subscription line item
Update selling plan for a subscription line item
Update product line item quantity in subscription
Update product line item price
Remove multiple products from subscription
Remove product from subscription
Add multiple products to subscription
Add product to subscription
Add product with custom price to subscription
Update line item pricing...
External APIs (0.0.1)
Download OpenAPI description
Languages
Servers
https://subscription-admin.appstle.com
Request
Updates the quantity of a specific product line item within a subscription contract. This comprehensive operation handles quantity validation, discount recalculation, and special Build-a-Box constraints.
Key Features:
- Updates quantity for future orders only
- Validates minimum/maximum quantities for line items
- Special handling for Build-a-Box subscriptions
- Automatic discount recalculation
- Shipping price updates
- Activity log tracking with old/new values
Build-a-Box (BAB) Validation: For Build-a-Box subscriptions:
- Enforces total minimum/maximum item counts
- Only counts recurring products (excludes one-time and free items)
- Validates across all BAB items in the subscription
- Can be bypassed with 'allowToAddProductQuantityMinMaxReached' permission
Line Item Validation: Individual products may have:
- Minimum quantity requirements (min_quantity attribute)
- Maximum quantity limits (max_quantity attribute)
- These are enforced separately from BAB constraints
Post-Update Actions:
- Activity Logging: Records quantity change with old/new values
- BAB Discount Sync: Recalculates Build-a-Box volume discounts
- Product Discount Sync: Updates product-specific discounts
- Shipping Price Update: Recalculates shipping based on new quantity
Discount Recalculation:
- Build-a-Box discounts adjust based on total quantity tiers
- May remove old discount codes and apply new ones
- Handles 'subscription contract has changed' retry scenarios
Important Notes:
- Line ID must be the full GraphQL ID format
- Quantity must be positive (minimum 1)
- Changes apply to all future orders
- Past or in-progress orders are not affected
Authentication: Requires valid X-API-Key header
Query
Subscription contract ID to update. Provide the numeric ID without the gid:// prefix
Example: contractId=123456789
New quantity for the line item. Must be a positive integer
Example: quantity=3
Line item ID to update. Must be the full GraphQL ID including the gid:// prefix
Example: lineId=gid://shopify/SubscriptionLine/111111
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-quantity
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-quantity?contractId=123456789&quantity=3&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F111111&api_key=string' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-04-01T12:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com" }, "lines": { "edges": [ … ] }, "discounts": { "edges": [ … ] } }
Request
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
Query
Bodyapplication/jsonLine item ID to update. Must be full GraphQL ID format
Example: lineId=gid://shopify/SubscriptionLine/111111
Base price for the product (before any discounts). This is the starting price
Example: basePrice=24.99
List of cycle-based pricing rules. Maximum 2 cycles, must have unique afterCycle values
string
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-pricing-policy
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-pricing-policy?contractId=123456789&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F111111&basePrice=24.99&api_key=string' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: string' \
-d '[
{
"afterCycle": 3,
"discountType": "PERCENTAGE",
"value": 10
}
]'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "lines": { "edges": [ … ] } }
Request
Updates the base price of a specific product line item within a subscription contract. This endpoint intelligently handles pricing updates while preserving existing discount structures.
Key Features:
- Updates base price while maintaining discount cycles
- Automatically calculates prepaid subscription prices
- Preserves existing percentage/fixed discounts
- Validates actual price changes before updating
- Triggers shipping and discount recalculations
- Sends price update notifications to customers
Base Price vs Current Price:
- Base Price: The unit price before any multipliers
- Current Price: Base price × fulfillment multiplier
- For monthly billing/weekly delivery: Current = Base × 4
- For pay-per-delivery: Current = Base × 1
Discount Preservation: By default, this endpoint preserves existing discount cycles:
- Percentage discounts adjust to new base price
- Fixed discounts remain at same dollar amount
- Discount schedule (after X cycles) unchanged
Prepaid Subscription Handling: For prepaid subscriptions (billing interval > delivery interval):
- Automatically calculates fulfillment multiplier
- Updates current price accordingly
- Ensures correct billing amounts
Post-Update Actions:
- Build-a-Box discount recalculation
- Product discount synchronization
- Shipping price updates
- Customer email notifications
- Activity log creation
Important Notes:
- Price changes apply to future orders only
- Cannot set price below $0.01
- Maximum 2 discount cycles preserved
- No update if price unchanged
Authentication: Requires valid X-API-Key header
Query
Subscription contract ID. Provide the numeric ID without the gid:// prefix
Example: contractId=123456789
New base price for the line item (unit price before multipliers)
Example: basePrice=24.99
Line item ID to update. Must be the full GraphQL ID including the gid:// prefix
Example: lineId=gid://shopify/SubscriptionLine/4245-cfgfg-xcfdg
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-price
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-price?contractId=123456789&basePrice=24.99&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F4245-cfgfg-xcfdg&api_key=string' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-04-01T12:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com" }, "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "deliveryPolicy": { "interval": "WEEK", "intervalCount": 1 }, "lines": { "edges": [ … ] } }