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 price
Update multiple properties of a subscription line item
Update selling plan for a subscription line item
Update product line item quantity in subscription
Update line item pricing policy with cycle-based discounts
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
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": [ … ] } }
Request
Removes multiple product line items from an existing subscription contract in a single request. Products are removed sequentially, allowing partial success if errors occur.
Key Features:
- Sequential processing - items removed one by one
- Partial success allowed - previous removals persist if later ones fail
- Validates each removal against current subscription state
- Smart discount cleanup for line-specific discounts
- Comprehensive validation for each product removal
- Triggers all side effects after each successful removal
Processing Order Matters: Items are removed in the order provided:
- First item validated and removed
- Second item validated against updated state
- Continue until all processed or error occurs
- Returns final subscription state
Validation Per Item:
- Line item must exist in subscription
- At least one recurring product must remain
- Build-a-Box min/max quantities maintained
- Minimum cycle commitments honored
- One-time and free products don't count toward minimum
Discount Handling: When removeDiscount=true:
- Removes discounts applied ONLY to the removed line
- Preserves discounts that apply to multiple lines
- Each removal evaluates discounts independently
- Build-a-Box discounts auto-adjust based on quantity
Side Effects Per Removal: Each successful removal triggers:
- Activity log entry created
- Customer email sent (except one-time products)
- Shipping price recalculation
- Build-a-Box discount resync
- Product discount adjustments
Partial Success Scenarios: If removing 3 items and the 2nd fails:
- 1st item: Successfully removed
- 2nd item: Fails, error returned
- 3rd item: Not attempted
- Result: Subscription with 1st item removed
Performance Considerations:
- Each removal is a separate Shopify API transaction
- Multiple emails may be sent to customer
- Consider using single remove for 1-2 items
- Large batches may timeout
- Recommended max: 5-10 items per request
Build-a-Box Handling: For Build-a-Box subscriptions:
- Validates total quantity after EACH removal
- May fail mid-batch if minimum breached
- Discounts recalculate after each item
- Consider removal order carefully
Important Notes:
- NOT atomic - no rollback on partial failure
- Order of line IDs affects success probability
- Customer receives email per removed item
- All validations apply as if removing individually
- Response shows final state after all attempts
Authentication: Requires valid X-API-Key header
Query
Bodyapplication/jsonrequiredArray [Subscription contract ID to remove products from
Example: contractId=123456789
When true, removes discounts that apply only to each removed line item. When false, attempts to retain all discounts. Discounts that apply to multiple lines are always retained regardless of this setting.
Default false
string
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-items
- 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-remove-line-items?contractId=123456789&removeDiscount=false&api_key=string' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: string' \
-d '[
"string"
]'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": [ … ] }, "discounts": { "edges": [ … ] } }