# Subscription Plans APIs for managing subscription plans, pricing tiers, and plan configurations. ## Get all subscription groups - [GET /api/external/v2/subscription-groups](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/getallsubscriptiongroupsv2external.md): Retrieves a list of all subscription groups (selling plan groups) configured in the store. This endpoint provides a complete overview of all subscription offerings available. Response includes: - All subscription groups with their configurations - Complete selling plan details for each group - Product and variant assignments (as JSON strings) - Discount configurations and tiers - Member restrictions and settings Use Cases: - Display all subscription options in a custom interface - Audit subscription configurations - Export subscription data for analysis - Synchronize with external systems Performance Notes: - Returns all groups in a single response (no pagination) - Response size grows with number of groups and plans - Product/variant lists are JSON-encoded strings within the response Authentication: Requires valid X-API-Key header ## Update subscription group details and product assignments - [PUT /api/external/v2/subscription-groups](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/updatesubscriptiongroupdetailsv2.md): Updates an existing subscription group (selling plan group) including its name, selling plans configuration, and optionally manages product/variant assignments. This endpoint provides comprehensive update capabilities for both the subscription group structure and its product associations. Key Capabilities: - Update subscription group name - Modify existing selling plan configurations (discounts, frequencies, trials, etc.) - Add or remove products/variants through updateProducts and deleteProducts fields - Cannot add or remove selling plans - only modify existing ones - Automatically handles complex discount transitions for free trials and prepaid plans - Updates delivery profile associations if changed - Triggers asynchronous operations for metafield updates and free product checks Important Notes: - The 'id' field is required and must match an existing subscription group - For each selling plan in subscriptionPlans array, provide 'idNew' with the existing selling plan ID - Plan modifications maintain the same selling plan ID in Shopify - Product/variant updates are processed after group details are updated - Large product updates (allProduct=true) run asynchronously Selling Plan Updates: - Can change discount amounts, types, and cycles - Can modify billing/delivery frequencies - Can add/remove free trials - Can change member restrictions and tags - Can update specific day delivery settings - Can modify min/max cycles Authentication: Requires valid X-API-Key header ## Create a new subscription group (selling plan group) - [POST /api/external/v2/subscription-groups](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/createsubscriptiongroupv2external.md): Creates a new subscription group with one or more selling plans in Shopify. A subscription group is a container for selling plans that can be applied to products and variants. Each group can contain multiple plans with different frequencies, discounts, and delivery schedules. Key Features: - Create multiple subscription plans within a single group - Configure complex discount tiers (up to 2 levels + custom cycles) - Set up free trials with automatic discount transitions - Define prepaid plans (PAY_AS_YOU_GO_PREPAID) with custom billing cycles - Configure member-only plans with tag-based access control - Set specific delivery dates (e.g., 15th of every month) - Add all products from store or specific collection automatically Discount Configuration: - First discount tier: Applied from a specific cycle (afterCycle1) - Second discount tier: Applied from another cycle (afterCycle2) - Additional cycles: Configure via appstleCycles for complex scenarios - Free trials: Automatically configure 100% discount for trial period Product Assignment: - Assign specific products via productIds field in request body - Assign specific variants via variantIds field in request body - Use isAddAllProduct=true to add all store products - Use collectionId with isAddAllProduct=true to add all products from a collection Authentication: Requires valid X-API-Key header ## Remove products or variants from a subscription group - [PUT /api/external/v2/subscription-groups/{id}/remove-products](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/deleteproductsorvariantsv2.md): Removes specified products and/or variants from an existing subscription group (selling plan group). This endpoint allows selective removal of products without affecting the group's configuration or other product assignments. Key Features: - Remove multiple products and variants in a single request - Remove all products from a specific collection - Silently ignores products/variants not currently in the group - Preserves subscription group configuration and settings - Updates synchronously and returns the modified group Collection Removal: - When collectionId is provided, fetches and removes all products from that collection - Collection processing is limited to 5000 products maximum - Collection removal is additive to any explicitly specified productIds/variantIds Important Notes: - Removing products does NOT affect existing active subscriptions - Can remove all products, leaving an empty subscription group - Products/variants not in the group are silently ignored - Use numeric IDs without gid:// prefix for products and variants Authentication: Requires valid X-API-Key header ## Add products or variants to an existing subscription group - [PUT /api/external/v2/subscription-groups/{id}/add-products](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/addproductsorvariants.md): Adds one or more products and/or product variants to an existing subscription group (selling plan group). This endpoint provides a simple way to expand the product catalog eligible for subscription without modifying the group's configuration or existing product assignments. Key Features: - Add multiple products and variants in a single request - Preserves existing product and variant assignments - Maintains the order of products as provided - Updates delivery profiles automatically if needed - Synchronously updates Shopify and returns the updated group - Optional response enhancement with added products information Important Notes: - Product IDs should be numeric Shopify product IDs without the gid:// prefix - Variant IDs should be numeric Shopify variant IDs without the gid:// prefix - Adding products also makes all their variants eligible for subscription - Adding specific variants limits subscription eligibility to those variants only - Duplicate products/variants are handled gracefully by Shopify - URL length limits apply to the comma-separated lists (use bulk endpoint for large additions) - Include 'x-return-short-response: true' header to get only added products/variants information in response Use Cases: - Launch new products with subscription options - Add seasonal items to existing subscription groups - Enable subscription for specific product variants - Expand subscription eligibility without changing plan configurations - Track which products were added in the current request Authentication: Requires valid X-API-Key header ## Remove products or variants from ALL subscription groups - [PUT /api/external/v2/subscription-groups/remove-products](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/deleteproductsorvariantsinallsubscriptiongroupplan.md): Removes specified products and/or variants from ALL subscription groups in the store. This is a powerful bulk operation that affects every subscription group simultaneously. ⚠️ WARNING: This operation: - Affects ALL subscription groups in your store - Cannot be easily undone - Processes synchronously (may timeout for stores with many groups) - Does NOT affect existing active subscriptions Use Cases: - Discontinuing products from all subscription offerings - Removing seasonal items from all groups - Cleaning up deleted products from subscription groups - Compliance-driven product removals Important Considerations: - Each group is updated individually - If any group update fails, previous groups remain updated - Large operations may take significant time - Consider using individual group removal for better control Authentication: Requires valid X-API-Key header ## Bulk add products or variants to an existing subscription group - [POST /api/external/v2/subscription-groups/{id}/bulk-add-products](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/bulkaddproductsorvariants.md): Adds multiple products and/or product variants to an existing subscription group (selling plan group) using a JSON request body. This endpoint is ideal for adding large numbers of products/variants that would exceed URL length limits in the query parameter version. Advantages over query parameter endpoint: - No URL length restrictions - Cleaner syntax for large lists - Better for programmatic integrations - Supports the same functionality with improved scalability Behavior: - Identical to the query parameter endpoint in functionality - Adds products/variants to existing assignments - Preserves product order - Updates synchronously and returns the updated group Authentication: Requires valid X-API-Key header ## Get subscription group by ID - [GET /api/external/v2/subscription-groups/{id}](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/getsubscriptiongroupv2external.md): Retrieves detailed information about a specific subscription group (selling plan group) by its ID. This endpoint provides complete configuration details for a single subscription group. Response includes: - Group name and configuration - All selling plans with complete details - Product and variant assignments - Discount tiers and configurations - Free trial settings - Member restrictions - Delivery and billing frequencies Use Cases: - Display detailed subscription options for editing - Verify configuration before updates - Debug subscription issues - Integration with external systems Authentication: Requires valid X-API-Key header ## Get all selling plans across all subscription groups - [GET /api/external/v2/subscription-groups/all-selling-plans](https://developers.subscription.appstle.com/external-api-swagger/subscription-plans/getallsellingplansv2external.md): Retrieves a flattened list of all selling plans from all subscription groups in the store. This endpoint provides a consolidated view of every subscription plan available, regardless of which group it belongs to. Response includes: - All selling plans with their configurations - Group information for each plan (groupId and groupName) - Complete discount and pricing details - Delivery and billing frequencies - Member restrictions and settings - Free trial configurations Use Cases: - Build a unified subscription selector - Compare all available subscription options - Analyze pricing across all plans - Find specific plan configurations - Generate reports on subscription offerings Differences from /subscription-groups endpoint: - Returns plans as a flat list, not grouped - Each plan includes its parent group information - Easier to search/filter across all plans - Does not include product/variant assignments Authentication: Requires valid X-API-Key header