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.

Full behavior, validation rules, and side effects

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

POST /api/external/v2/subscription-groups

cURL

Simple Monthly Subscription

curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-groups \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "groupName": "Monthly Coffee Subscription",
  "subscriptionPlans": [
    {
      "frequencyName": "Delivered Monthly",
      "frequencyDescription": "Fresh coffee delivered every month",
      "frequencyCount": 1,
      "frequencyInterval": "MONTH",
      "planType": "PAY_AS_YOU_GO",
      "discountEnabled": true,
      "discountType": "PERCENTAGE",
      "discountOffer": 10,
      "afterCycle1": 0,
      "minCycles": 3
    }
  ],
  "productIds": "[{\"id\":987654321}]"
}
'

201

Example

{
  "id": 123,
  "productCount": 123,
  "productVariantCount": 123,
  "subscriptionPlans": [
    {
      "frequencyCount": 123,
      "billingFrequencyCount": 123,
      "payAsYouGoPrepaidBillingFrequencyCount": 123,
      "frequencyName": "<string>",
      "frequencyDescription": "<string>",
      "discountOffer": 123,
      "discountOffer2": 123,
      "afterCycle1": 123,
      "afterCycle2": 123,
      "discountEnabled": true,
      "discountEnabled2": true,
      "discountEnabledMasked": true,
      "discountEnabled2Masked": true,
      "id": "<string>",
      "specificDayValue": 123,
      "specificMonthValue": 123,
      "specificDayEnabled": true,
      "maxCycles": 123,
      "minCycles": 123,
      "cutOff": 123,
      "prepaidFlag": "<string>",
      "idNew": "<string>",
      "freeTrialEnabled": true,
      "freeTrialCount": 123,
      "memberOnly": true,
      "nonMemberOnly": true,
      "memberInclusiveTags": "<string>",
      "memberExclusiveTags": "<string>",
      "formFieldJson": "<string>",
      "upcomingOrderEmailBuffer": 123,
      "frequencySequence": 123,
      "groupName": "<string>",
      "groupId": 123,
      "repeatingCycle": true,
      "repeatingNumberOfCycle": 123,
      "keepOriginalNextBillingDateAfterTrial": true,
      "defaultSelectedPlan": true,
      "frequencyNameTranslations": {},
      "appstleCycles": [
        {
          "afterCycle": 3,
          "discountType": "PERCENTAGE",
          "value": 10,
          "freeVariantId": 42549172011164,
          "freeProductHandle": "free-gift-product",
          "repeatingCycle": true,
          "repeatingNumberOfCycle": 6,
          "preventDuplicationFreeProduct": true
        }
      ]
    }
  ],
  "groupName": "<string>",
  "productIds": "<string>",
  "productId": "<string>",
  "variantIds": "<string>",
  "accessoryProductIds": "<string>",
  "updateProducts": {
    "productIds": [
      123
    ],
    "variantIds": [
      123
    ],
    "allProduct": true,
    "collectionId": "<string>",
    "deleteAllProduct": true,
    "productDetails": "<string>",
    "variantDetails": "<string>"
  },
  "deleteProducts": {
    "productIds": [
      123
    ],
    "variantIds": [
      123
    ],
    "allProduct": true,
    "collectionId": "<string>",
    "deleteAllProduct": true,
    "productDetails": "<string>",
    "variantDetails": "<string>"
  },
  "translations": "<string>"
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

api_key · string

API Key (Deprecated - Use X-API-Key header instead)

isAddAllProduct · boolean · default: false

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.

collectionId · string · default: ""

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')

Body

application/json

Complete subscription group configuration including name, plans, and product assignments

id · integer<int64>

productCount · integer<int64>

productVariantCount · integer<int64>

subscriptionPlans · object[]

Show child attributes

groupName · string

productIds · string

productId · string

variantIds · string

accessoryProductIds · string

updateProducts · object

Show child attributes

deleteProducts · object

Show child attributes

translations · string

Response

201

application/json

Subscription group created successfully

id · integer<int64>

productCount · integer<int64>

productVariantCount · integer<int64>

subscriptionPlans · object[]

Show child attributes

groupName · string

productIds · string

productId · string

variantIds · string

accessoryProductIds · string

updateProducts · object

Show child attributes

deleteProducts · object

Show child attributes

translations · string