> ## 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. # Add products or variants to an existing subscription group > 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 ## OpenAPI ````yaml /subscription/admin-api-swagger.json put /api/external/v2/subscription-groups/{id}/add-products 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/{id}/add-products: put: tags: - Subscription Plans summary: Add products or variants to an existing subscription group description: >- 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 operationId: addProductsOrVariants parameters: - description: Subscription group ID (numeric ID) example: 123456789 in: path name: id required: true schema: format: int64 type: integer - 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: >- Comma-separated list of Shopify product IDs to add. Adding a product makes all its variants eligible for subscription. Use numeric IDs only (e.g., '987654321,987654322,987654323') example: 987654321,987654322,987654323 in: query name: productIds required: false schema: pattern: ^\d+(,\d+)*$ type: string - description: >- Comma-separated list of Shopify variant IDs to add. Use this to enable subscription for specific variants only. Use numeric IDs only (e.g., '123456789,123456790,123456791') example: 123456789,123456790 in: query name: variantIds required: false schema: pattern: ^\d+(,\d+)*$ type: string - description: >- Header to indicate if response should return only added products ID information. Set to 'true' for minimal response, any other value or omitted for full response. example: false in: header name: x-return-short-response required: false schema: default: false type: boolean responses: '200': content: application/json: examples: Success Response (Standard): description: Success Response (Standard) value: groupName: Monthly Coffee Subscription id: 123456789 productCount: 10 productIds: >- [{"id":987654321,"title":"Premium Coffee Blend"},{"id":987654322,"title":"Organic Dark Roast"},{"id":987654323,"title":"Colombian Single Origin"}] productVariantCount: 35 subscriptionPlans: - discountEnabled: true discountOffer: 10 discountType: PERCENTAGE frequencyCount: 1 frequencyDescription: Get fresh coffee delivered to your door every month frequencyInterval: MONTH frequencyName: Delivered Monthly id: gid://shopify/SellingPlan/111111 planType: PAY_AS_YOU_GO variantIds: >- [{"id":123456789,"title":"250g Bag"},{"id":123456790,"title":"500g Bag"}] Success Response (with x-return-short-response header): description: Success Response (with x-return-short-response header) value: addedProductIds: - 987654321 - 987654322 addedVariantIds: - 123456789 schema: oneOf: - $ref: '#/components/schemas/SubscriptionGroupV2DTO' - $ref: '#/components/schemas/AddedProductsResponseDTO' description: Products/variants successfully added to subscription group '400': content: application/json: examples: Invalid Product Format: description: Invalid Product Format value: detail: Invalid product ID format. Use numeric IDs only. status: 400 title: Bad Request type: https://example.com/errors/bad-request Invalid Subscription Group ID: description: Invalid Subscription Group ID value: detail: Invalid id errorKey: idnull status: 400 title: Bad Request type: https://example.com/errors/bad-request No Products or Variants Provided: description: No Products or Variants Provided 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 description: Invalid request parameters '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: '*/*': schema: type: object description: Insufficient permissions to modify 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: examples: Product Not Found: description: Product Not Found value: detail: Product with ID 987654321 not found in Shopify status: 422 title: Unprocessable Entity type: https://example.com/errors/unprocessable-entity Variant Not Found: description: Variant Not Found value: detail: Product variant with ID 123456789 not found status: 422 title: Unprocessable Entity type: https://example.com/errors/unprocessable-entity description: Shopify API error 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 AddedProductsResponseDTO: properties: addedProductIds: items: format: int64 type: integer type: array addedVariantIds: items: format: int64 type: integer type: array 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 ````