Subscription Plans

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

POST

api

external

subscription-groups

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": "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"
    }
  ]
}
'

{
  "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": "[]"
}

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

accessoryProductIds

string

deleteProducts

object

Show child attributes

groupName

string

integer<int64>

productCount

integer<int64>

productId

string

productIds

string

productVariantCount

integer<int64>

subscriptionPlans

object[]

Show child attributes

translations

string

updateProducts

object

Show child attributes

variantIds

string

Response

Subscription group successfully created

accessoryProductIds

string

deleteProducts

object

Show child attributes

groupName

string

integer<int64>

productCount

integer<int64>

productId

string

productIds

string

productVariantCount

integer<int64>

subscriptionPlans

object[]

Show child attributes

translations

string

updateProducts

object

Show child attributes

variantIds

string

Update subscription group details and product assignments

Get all selling plans across all subscription groups

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": "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"
    }
  ]
}
'

{
  "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": "[]"
}