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 product line item quantity in subscription
Update multiple properties of a subscription line item
Update selling plan for a subscription line item
Update line item pricing policy with cycle-based discounts
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 product line item...
External APIs (0.0.1)
Download OpenAPI description
Languages
Servers
https://subscription-admin.appstle.com
Request
Updates the selling plan associated with a specific product line item in a subscription contract. Selling plans define the delivery schedule, pricing rules, and billing policies for subscription products.
What are Selling Plans? Selling plans are Shopify's way of defining subscription rules for products:
- Delivery Schedule: How often the product is delivered (e.g., 'every 2 weeks', 'monthly')
- Pricing Policy: Discounts and pricing tiers (e.g., '10% off', 'first order free')
- Billing Policy: When and how often customer is charged
- Plan Name: Customer-facing description like 'Deliver every month'
Key Features:
- Update by selling plan ID or name (name takes precedence if both provided)
- Validates line item exists before attempting update
- Only creates activity log if plan actually changes
- Uses Shopify's draft system for safe updates
- Preserves existing line item attributes and customizations
Common Use Cases:
- Change delivery frequency: Weekly → Monthly
- Switch pricing tiers: Regular → VIP pricing
- Update from old plan to new plan with better terms
- Migrate products to new selling plan groups
- Apply seasonal or promotional plans
Update Process:
- Validates subscription contract and line item exist
- Creates a draft of the subscription contract
- Updates the line item's selling plan in the draft
- Commits the draft to apply changes
- Records activity log if plan changed
Impact of Selling Plan Changes:
- Delivery Schedule: Next and future orders follow new schedule
- Pricing: New plan's pricing applies from next billing
- Discounts: Plan-specific discounts are recalculated
- Billing: Billing frequency may change with the plan
Finding Selling Plans: To find available selling plans:
- Check product's selling plan groups in Shopify admin
- Use Shopify's GraphQL API to query selling plans
- Plans must be active and associated with the product
Important Notes:
- Both sellingPlanId and sellingPlanName are optional, but at least one required
- If both provided, both are updated (name doesn't override ID)
- Plan must be valid for the product variant
- Changes apply to future orders only
- No customer notification sent (consider sending separately)
Authentication: Requires valid X-API-Key header
Query
The unique identifier of the subscription contract
Example: contractId=123456789
The unique identifier of the line item in the subscription contract. Must be in full GraphQL ID format
Example: lineId=gid://shopify/SubscriptionLine/987654321
The unique identifier of the new selling plan. Provide the numeric ID without gid:// prefix. Required if sellingPlanName is not provided. The plan must be:
- Active in your Shopify store
- Associated with the product variant
- Part of an active selling plan group
Example: sellingPlanId=56789
The customer-facing name of the new selling plan. Required if sellingPlanId is not provided. This is the name shown to customers like 'Deliver every 2 weeks' or 'Monthly subscription'. Must match exactly as configured in Shopify
Example: sellingPlanName=Deliver every month
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-selling-plan
- 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-selling-plan?contractId=123456789&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F987654321&sellingPlanId=56789&sellingPlanName=Deliver+every+month' \
-H 'X-API-Key: sk_live_1234567890abcdef'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-04-01T00:00:00Z", "customer": { "id": "gid://shopify/Customer/987654321", "email": "customer@example.com" }, "lines": { "edges": [ … ] }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 } }
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": [ … ] } }