> ## 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. # Create a new subscription group (selling plan group) > 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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json post /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: post: tags: - Subscription Plans summary: Create a new subscription group (selling plan group) description: >- 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 operationId: createSubscriptionGroupV2External parameters: - deprecated: true description: API Key (Deprecated - Use X-API-Key header instead) in: query name: api_key required: false schema: type: string - description: API Key for authentication example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string - description: >- Add all products from the store or collection to this subscription group. When true without collectionId: adds all active products in the store. When true with collectionId: adds all products from the specified collection. This operation runs asynchronously and may take time for large catalogs. example: false in: query name: isAddAllProduct required: false schema: default: false type: boolean - description: >- Shopify collection ID to limit product addition when isAddAllProduct is true. Format: numeric ID without gid prefix (e.g., '123456789' not 'gid://shopify/Collection/123456789') example: 123456789 in: query name: collectionId required: false schema: default: '' type: string requestBody: content: application/json: examples: Complex Discount with Free Product: description: Complex Discount with Free Product value: groupName: Loyalty Rewards Subscription productIds: '[{"id":987654321}]' subscriptionPlans: - afterCycle1: 0 appstleCycles: - afterCycle: 6 discountType: FREE_PRODUCT freeVariantId: 42549172011164 preventDuplicationFreeProduct: true - afterCycle: 12 discountType: SHIPPING repeatingCycle: true repeatingNumberOfCycle: 3 value: 100 discountEnabled: true discountOffer: 10 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Earn rewards with every order frequencyInterval: MONTH frequencyName: Monthly with Rewards planType: PAY_AS_YOU_GO Free Trial Subscription: description: Free Trial Subscription value: groupName: Try Before You Subscribe productIds: '[{"id":987654321}]' subscriptionPlans: - discountOffer: 100 discountOffer2: 15 freeTrialCount: 14 freeTrialEnabled: true freeTrialInterval: DAY frequencyCount: 1 frequencyDescription: Try free for 14 days, then save 15% frequencyInterval: MONTH frequencyName: Monthly with 14-Day Trial inventoryPolicyReserve: ON_FULFILLMENT minCycles: 3 planType: PAY_AS_YOU_GO Member-Only Subscription: description: Member-Only Subscription value: groupName: VIP Member Subscriptions productIds: '[{"id":987654321}]' subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 25 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Exclusive pricing for VIP members frequencyInterval: MONTH frequencyName: VIP Monthly Plan memberExclusiveTags: blocked,suspended memberInclusiveTags: vip,gold-member,platinum-member memberOnly: true planType: PAY_AS_YOU_GO Multi-tier Discount Plan: description: Multi-tier Discount Plan value: groupName: Premium Subscription Plans productIds: '[{"id":987654321},{"id":987654322}]' subscriptionPlans: - afterCycle1: 0 afterCycle2: 4 discountEnabled: true discountEnabled2: true discountOffer: 5 discountOffer2: 10 discountType: PERCENTAGE discountType2: PERCENTAGE frequencyCount: 1 frequencyDescription: Save more with weekly deliveries frequencyInterval: WEEK frequencyName: Weekly Delivery maxCycles: 52 minCycles: 4 planType: PAY_AS_YOU_GO upcomingOrderEmailBuffer: 3 - afterCycle1: 0 afterCycle2: 6 appstleCycles: - afterCycle: 12 discountType: PERCENTAGE repeatingCycle: true value: 20 discountEnabled: true discountEnabled2: true discountOffer: 10 discountOffer2: 15 discountType: PERCENTAGE discountType2: PERCENTAGE frequencyCount: 1 frequencyDescription: Convenient monthly shipments frequencyInterval: MONTH frequencyName: Monthly Delivery planType: PAY_AS_YOU_GO variantIds: '[{"id":123456789}]' Prepaid Quarterly Plan: description: Prepaid Quarterly Plan value: groupName: Prepaid Quarterly Plans productIds: '[{"id":987654321}]' subscriptionPlans: - discountEnabled: true discountOffer: 20 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Pay for 3 months upfront and save 20% frequencyInterval: MONTH frequencyName: 3-Month Prepaid maxCycles: 12 payAsYouGoPrepaidBillingFrequencyCount: 3 planType: PAY_AS_YOU_GO_PREPAID Simple Monthly Subscription: description: Simple Monthly Subscription value: groupName: Monthly Coffee Subscription productIds: '[{"id":987654321}]' subscriptionPlans: - afterCycle1: 0 discountEnabled: true discountOffer: 10 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Fresh coffee delivered every month frequencyInterval: MONTH frequencyName: Delivered Monthly minCycles: 3 planType: PAY_AS_YOU_GO Specific Day Delivery: description: Specific Day Delivery value: groupName: 15th of Month Delivery productIds: '[{"id":987654321}]' subscriptionPlans: - afterCycle1: 0 cutOff: 5 discountEnabled: true discountOffer: 10 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Delivered on the 15th of every month frequencyInterval: MONTH frequencyName: Monthly on the 15th frequencyType: ON_SPECIFIC_DAY planType: PAY_AS_YOU_GO specificDayEnabled: true specificDayValue: 15 schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: >- Complete subscription group configuration including name, plans, and product assignments required: true responses: '201': content: application/json: examples: Success Response: description: Success Response value: groupName: Monthly Coffee Subscription id: 123456789 productCount: 5 productIds: >- [{"id":987654321,"title":"Premium Coffee Blend","status":"ACTIVE"}] productVariantCount: 15 subscriptionPlans: - afterCycle1: 0 afterCycle2: 3 billingFrequencyCount: 1 billingFrequencyInterval: MONTH discountEnabled: true discountEnabled2: true discountOffer: 10 discountOffer2: 15 discountType: PERCENTAGE discountType2: PERCENTAGE frequencyCount: 1 frequencyDescription: Get fresh coffee delivered to your door every month frequencyInterval: MONTH frequencyName: Delivered Monthly frequencySequence: 0 id: gid://shopify/SellingPlan/111111 maxCycles: null minCycles: 3 planType: PAY_AS_YOU_GO variantIds: '[]' schema: $ref: '#/components/schemas/SubscriptionGroupV2DTO' description: Subscription group successfully created '400': content: application/json: examples: ID Already Exists: description: ID Already Exists value: detail: A new subscriptionGroup cannot already have an ID errorKey: idexists status: 400 title: Bad Request type: https://example.com/errors/bad-request Invalid Frequency Configuration: description: Invalid Frequency Configuration value: detail: Frequency count must be greater than 0 status: 400 title: Bad Request type: https://example.com/errors/bad-request Missing Required Fields: description: Missing Required Fields value: detail: Group name is required status: 400 title: Bad Request type: https://example.com/errors/bad-request description: Invalid request parameters or validation error '401': content: application/json: example: detail: Invalid or missing API key status: 401 title: Unauthorized type: https://example.com/errors/unauthorized description: Authentication required - missing or invalid API key '403': content: application/json: example: detail: You do not have permission to create subscription groups status: 403 title: Forbidden type: https://example.com/errors/forbidden description: Insufficient permissions to create subscription groups '422': content: application/json: examples: Duplicate Plan Name: description: Duplicate Plan Name value: detail: A selling plan group with this name already exists status: 422 title: Unprocessable Entity type: https://example.com/errors/unprocessable-entity Shopify API Error: description: Shopify API Error value: detail: 'Shopify API error: Product not found' 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 ````