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 selling plan for a subscription line item
Update multiple properties of a subscription line item
Update product line item quantity in subscription
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 selling plan for a...
External APIs (0.0.1)
Download OpenAPI description
Languages
Servers
https://subscription-admin.appstle.com
Request
Comprehensive endpoint for updating a subscription line item's quantity, price, product variant, and/or selling plan in a single API call. Changes are applied intelligently - only modified values trigger updates.
Key Features:
- Update any combination of: quantity, price, variant, or selling plan
- Intelligent change detection - only updates what's different
- Automatic handling of prepaid subscription pricing
- Preserves existing discount cycles when updating price
- Partial success allowed - some updates may fail while others succeed
- Each change creates separate activity log entries
Prepaid Subscription Handling: For prepaid subscriptions (billing interval > delivery interval):
- When
isPricePerUnit=true: Price is multiplied by interval ratio - Example: Monthly billing, weekly delivery = price × 4
- When
isPricePerUnit=false: Price is used as total billing amount
Update Process:
- Validates line item exists in the subscription
- Calculates interval multiplier for prepaid logic
- Updates in order: selling plan → price → quantity → variant
- Each update uses separate Shopify GraphQL mutation
- Failures are logged but don't block other updates
Selling Plan Updates:
- Can update by ID or name (name takes precedence)
- Only updates if different from current plan
- Useful for changing delivery frequency options
Price Updates:
- Preserves existing discount cycles (up to 2 cycles)
- Recalculates cycle discounts based on new base price
- Triggers shipping price recalculation
- Sends price update email to customer
Quantity Updates:
- Validates against min/max quantity rules
- Updates Build-a-Box totals if applicable
- May trigger discount recalculations
Variant Updates:
- Changes the product itself (different SKU)
- Validates new variant exists and is available
- May affect pricing and discounts
Important Notes:
- All parameters except contractId and lineId are optional
- Provide only the values you want to change
- Price is always in shop's base currency
- Changes apply to future orders only
Authentication: Requires valid X-API-Key header
Query
New quantity for the line item. Leave unchanged if not updating quantity.
Example: quantity=3
New product variant ID in Shopify GID format (e.g., gid://shopify/ProductVariant/42549172011164). This updates the associated product. Leave this parameter blank if you are not switching products.
Example: variantId=gid://shopify/ProductVariant/42549172011164
Line item ID to update. Must be the full GraphQL ID including gid:// prefix
Example: lineId=gid://shopify/SubscriptionLine/111111
New price for the line item in shop currency. Behavior depends on isPricePerUnit flag.
Example: price=29.99
Determines how price is interpreted for prepaid subscriptions:
- true: Price is per unit (per delivery), will be multiplied by interval ratio
- false: Price is total billing amount (for all deliveries in billing period)
Example: Monthly billing, weekly delivery, price=$10
- isPricePerUnit=true: Customer pays $40/month ($10 × 4 weeks)
- isPricePerUnit=false: Customer pays $10/month total
Default false
Name of the selling plan to apply. Takes precedence over current selling plan. Used to change delivery frequencies.
Example: sellingPlanName=Deliver every 2 weeks
- https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item
- 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?contractId=123456789&quantity=3&variantId=gid%3A%2F%2Fshopify%2FProductVariant%2F42549172011164&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F111111&price=29.99&isPricePerUnit=false&sellingPlanName=Deliver+every+2+weeks&api_key=string' \
-H 'X-API-Key: string'Response
application/json
{ "id": "gid://shopify/SubscriptionContract/123456789", "status": "ACTIVE", "nextBillingDate": "2024-03-01T00:00:00Z", "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "deliveryPolicy": { "interval": "WEEK", "intervalCount": 1 }, "lines": { "edges": [ … ] } }
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": [ … ] } }