> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # Update subscription group details and product assignments > 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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups openapi: 3.0.1 info: description: >- 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. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/subscription-groups: put: tags: - Subscription Plans summary: Update subscription group details and product assignments description: >- 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 operationId: updateSubscriptionGroupDetailsV2 parameters: - description: API Key for authentication example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string requestBody: content: application/json: examples: Add All Products from Collection: description: Add All Products from Collection value: groupName: Coffee Collection Subscription id: 123456789 subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 15 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: All coffee products eligible frequencyInterval: MONTH frequencyName: Monthly Coffee Box idNew: gid://shopify/SellingPlan/111111 planType: PAY_AS_YOU_GO updateProducts: allProduct: true collectionId: '987654321' Add Free Trial to Existing Plan: description: Add Free Trial to Existing Plan value: groupName: Try Before You Subscribe id: 123456789 subscriptionPlans: - discountOffer: 100 discountOffer2: 10 freeTrialCount: 7 freeTrialEnabled: true freeTrialInterval: DAY frequencyCount: 1 frequencyDescription: Try free for 7 days frequencyInterval: MONTH frequencyName: Monthly with Trial idNew: gid://shopify/SellingPlan/111111 minCycles: 3 planType: PAY_AS_YOU_GO Convert to Prepaid Plan: description: Convert to Prepaid Plan value: groupName: Quarterly Prepaid Savings id: 123456789 subscriptionPlans: - discountEnabled: true discountOffer: 25 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Pay upfront for 3 months and save 25% frequencyInterval: MONTH frequencyName: 3-Month Prepaid Plan idNew: gid://shopify/SellingPlan/111111 maxCycles: 12 payAsYouGoPrepaidBillingFrequencyCount: 3 planType: PAY_AS_YOU_GO_PREPAID Update Group Name and Discount: description: Update Group Name and Discount value: groupName: Premium Coffee Club - Updated id: 123456789 subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 15 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Updated description with better savings frequencyInterval: MONTH frequencyName: Monthly Delivery idNew: gid://shopify/SellingPlan/111111 minCycles: 3 planType: PAY_AS_YOU_GO Update Member-Only Settings: description: Update Member-Only Settings value: groupName: VIP Member Exclusive id: 123456789 subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 30 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Exclusive access for VIP members frequencyInterval: MONTH frequencyName: VIP Monthly Plan idNew: gid://shopify/SellingPlan/111111 memberExclusiveTags: blocked,trial memberInclusiveTags: vip,platinum,gold,silver memberOnly: true planType: PAY_AS_YOU_GO Update Multiple Plans with Product Changes: description: Update Multiple Plans with Product Changes value: deleteProducts: productIds: - 987654321 variantIds: - 123456789 groupName: Flexible Subscription Options id: 123456789 subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 20 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Maximum savings for frequent deliveries frequencyInterval: WEEK frequencyName: Weekly - Best Value idNew: gid://shopify/SellingPlan/111111 planType: PAY_AS_YOU_GO - afterCycle1: 0 discountEnabled: true discountOffer: 15 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Our most popular option frequencyInterval: MONTH frequencyName: Monthly - Popular idNew: gid://shopify/SellingPlan/222222 planType: PAY_AS_YOU_GO updateProducts: productDetails: '[{"id":987654323},{"id":987654324}]' variantDetails: '[{"id":123456790}]' Update with Complex Discount Cycles: description: Update with Complex Discount Cycles value: groupName: Loyalty Rewards Program id: 123456789 subscriptionPlans: - afterCycle1: 0 afterCycle2: 3 appstleCycles: - afterCycle: 6 discountType: PERCENTAGE value: 20 - afterCycle: 12 discountType: FREE_PRODUCT freeVariantId: 42549172011164 repeatingCycle: true repeatingNumberOfCycle: 6 discountEnabled: true discountEnabled2: true discountOffer: 10 discountOffer2: 15 discountType: PERCENTAGE discountType2: PERCENTAGE frequencyCount: 1 frequencyDescription: Increasing rewards for loyal customers frequencyInterval: MONTH frequencyName: Monthly Loyalty Plan idNew: gid://shopify/SellingPlan/111111 minCycles: 6 planType: PAY_AS_YOU_GO schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: >- Complete subscription group update request including group details, selling plans, and optional product management required: true responses: '200': content: application/json: examples: Success Response: description: Success Response value: groupName: Updated Monthly Coffee Subscription id: 123456789 productCount: 8 productIds: >- [{"id":987654321,"title":"Premium Coffee Blend","status":"ACTIVE"}] productVariantCount: 24 subscriptionPlans: - afterCycle1: 0 afterCycle2: 6 billingFrequencyCount: 1 billingFrequencyInterval: MONTH discountEnabled: true discountEnabled2: true discountOffer: 15 discountOffer2: 20 discountType: PERCENTAGE discountType2: PERCENTAGE frequencyCount: 1 frequencyDescription: Fresh coffee delivered monthly with new pricing frequencyInterval: MONTH frequencyName: Updated Monthly Delivery id: gid://shopify/SellingPlan/111111 idNew: gid://shopify/SellingPlan/111111 maxCycles: 24 minCycles: 3 planType: PAY_AS_YOU_GO variantIds: '[{"id":123456789,"title":"250g Bag","status":"ACTIVE"}]' schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: Subscription group successfully updated '400': content: application/json: examples: Duplicate Group Name: description: Duplicate Group Name value: detail: >- UserGeneratedError: A selling plan group with this name already exists status: 400 title: Bad Request type: https://example.com/errors/bad-request Invalid Product Update: description: Invalid Product Update value: detail: >- At least one of the Product Id(s) or Variant Id(s) is required status: 400 title: Bad Request type: https://example.com/errors/bad-request Invalid Selling Plan: description: Invalid Selling Plan value: detail: 'UserGeneratedError: Selling plan not found' status: 400 title: Bad Request type: https://example.com/errors/bad-request Missing ID: description: Missing ID value: detail: Invalid id errorKey: idnull status: 400 title: Bad Request type: https://example.com/errors/bad-request description: Invalid request parameters or validation error '401': content: '*/*': schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: Authentication required - missing or invalid API key '403': content: '*/*': schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: Insufficient permissions to update subscription groups '404': content: application/json: example: detail: Subscription group with ID 999999 not found status: 404 title: Not Found type: https://example.com/errors/not-found description: Subscription group not found '422': content: application/json: example: detail: >- UserGeneratedError: Cannot update selling plan with active subscriptions status: 422 title: Unprocessable Entity type: https://example.com/errors/unprocessable-entity description: Shopify API error or business rule violation components: schemas: SubscriptionGroupV2DTO: properties: accessoryProductIds: type: string deleteProducts: $ref: '#/components/schemas/ProductVariantDTO' groupName: type: string id: format: int64 type: integer productCount: format: int64 type: integer productId: type: string productIds: type: string productVariantCount: format: int64 type: integer subscriptionPlans: items: $ref: '#/components/schemas/FrequencyInfoDTO' type: array translations: type: string updateProducts: $ref: '#/components/schemas/ProductVariantDTO' variantIds: type: string type: object ProductVariantDTO: properties: allProduct: type: boolean collectionId: type: string deleteAllProduct: type: boolean productDetails: type: string productIds: items: format: int64 type: integer type: array variantDetails: type: string variantIds: items: format: int64 type: integer type: array type: object FrequencyInfoDTO: properties: afterCycle1: format: int32 type: integer afterCycle2: format: int32 type: integer appstleCycles: items: $ref: '#/components/schemas/AppstleCycle' type: array billingFrequencyCount: format: int32 type: integer billingFrequencyInterval: enum: - DAY - WEEK - MONTH - YEAR type: string cutOff: format: int32 type: integer defaultSelectedPlan: type: boolean deliveryPolicyPreAnchorBehavior: enum: - ASAP - NEXT - $UNKNOWN type: string discountEnabled: type: boolean discountEnabled2: type: boolean discountEnabled2Masked: type: boolean discountEnabledMasked: type: boolean discountOffer: format: double type: number discountOffer2: format: double type: number discountType: enum: - PERCENTAGE - FIXED - PRICE type: string discountType2: enum: - PERCENTAGE - FIXED - PRICE type: string fixedBillingDates: items: $ref: '#/components/schemas/FixedBillingDate' type: array formFieldJson: type: string freeTrialCount: format: int32 type: integer freeTrialEnabled: type: boolean freeTrialInterval: enum: - DAY - WEEK - MONTH - YEAR type: string frequencyCount: format: int32 type: integer frequencyDescription: type: string frequencyInterval: enum: - DAY - WEEK - MONTH - YEAR type: string frequencyName: type: string frequencyNameTranslations: additionalProperties: additionalProperties: type: string type: object type: object frequencySequence: format: int32 type: integer frequencyType: enum: - ON_PURCHASE_DAY - ON_SPECIFIC_DAY - ON_FIXED_DATES type: string groupId: format: int64 type: integer groupName: type: string id: type: string idNew: type: string inventoryPolicyReserve: enum: - ON_FULFILLMENT - ON_SALE - $UNKNOWN type: string keepOriginalNextBillingDateAfterTrial: type: boolean maxCycles: format: int32 type: integer memberExclusiveTags: type: string memberInclusiveTags: type: string memberOnly: type: boolean minCycles: format: int32 type: integer nonMemberOnly: type: boolean payAsYouGoPrepaidBillingFrequencyCount: format: int32 type: integer planType: enum: - PAY_AS_YOU_GO - PREPAID - ADVANCED_PREPAID - PAY_AS_YOU_GO_PREPAID type: string prepaidFlag: type: string repeatingCycle: type: boolean repeatingNumberOfCycle: format: int32 type: integer specificDayEnabled: type: boolean specificDayValue: format: int32 type: integer specificMonthValue: format: int32 type: integer upcomingOrderEmailBuffer: format: int32 type: integer type: object AppstleCycle: description: Custom pricing cycle configuration for subscription line items properties: afterCycle: description: The billing cycle number after which this pricing applies example: 3 format: int32 minimum: 1 type: integer discountType: description: Type of discount to apply in pricing cycles enum: - PERCENTAGE - FIXED - PRICE - SHIPPING - FREE_PRODUCT - PERCENTAGE - FIXED - PRICE - SHIPPING - FREE_PRODUCT example: PERCENTAGE type: string freeProductHandle: description: >- Product handle of a free product to add when discountType is FREE_PRODUCT example: free-gift-product type: string freeProductTitle: description: Display title of the free product when discountType is FREE_PRODUCT example: Ceramic Mug type: string freeVariantId: description: >- Variant ID of a free product to add when discountType is FREE_PRODUCT example: 42549172011164 format: int64 type: integer preventDuplicationFreeProduct: description: Prevent adding duplicate free products if already in cart example: true type: boolean repeatingCycle: description: Whether this pricing should repeat for subsequent cycles example: true type: boolean repeatingNumberOfCycle: description: >- Number of cycles to repeat this pricing for when repeatingCycle is true example: 6 format: int32 minimum: 1 type: integer value: description: >- Discount value. For PERCENTAGE: 0-100 (e.g., 10 for 10% off). For FIXED: amount to subtract from price. For PRICE: new fixed price. For SHIPPING: shipping discount amount. For FREE_PRODUCT: not used (set freeVariantId or freeProductHandle instead) example: 10 format: double type: number type: object FixedBillingDate: properties: day: format: int32 type: integer month: format: int32 type: integer type: object ````