Skip to content
/Subscription Plans

External APIs (0.0.1)

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.

Download OpenAPI description
external-api-swagger.json
external-api-swagger.yaml
Languages
Servers
https://subscription-admin.appstle.com

Subscription Management

Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions.

Operations

Subscription Payments

APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information.

Operations

Subscription Contracts

APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses.

Operations

Subscription Products

APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products.

Operations

Billing & Payments

APIs for handling billing operations, payment processing, and financial transactions related to subscriptions.

Operations

Subscription Discounts

APIs for managing discounts and promotional codes applied to subscriptions.

Operations

Subscription One-Time Products

APIs for managing one-time add-on products that can be purchased alongside recurring subscription items.

Operations

Subscription Plans

APIs for managing subscription plans, pricing tiers, and plan configurations.

Operations

Get all subscription groups

Request

Retrieves a list of all subscription groups (selling plan groups) configured in the store. This endpoint provides a complete overview of all subscription offerings available.

Response includes:

  • All subscription groups with their configurations
  • Complete selling plan details for each group
  • Product and variant assignments (as JSON strings)
  • Discount configurations and tiers
  • Member restrictions and settings

Use Cases:

  • Display all subscription options in a custom interface
  • Audit subscription configurations
  • Export subscription data for analysis
  • Synchronize with external systems

Performance Notes:

  • Returns all groups in a single response (no pagination)
  • Response size grows with number of groups and plans
  • Product/variant lists are JSON-encoded strings within the response

Authentication: Requires valid X-API-Key header

Query
api_keystringDeprecated

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

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-groups?api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully retrieved subscription groups

Bodyapplication/jsonArray [
idinteger(int64)
productCountinteger(int64)
productVariantCountinteger(int64)
frequencyCountinteger(int32)
frequencyIntervalstring
Enum"DAY""WEEK""MONTH""YEAR"
frequencyNamestring
groupNamestring
productIdsstring
discountOffernumber(double)
discountTypestring
Enum"PERCENTAGE""FIXED""PRICE"
discountEnabledboolean
]
Response
application/json
[
  {
    "id": 0,
    "productCount": 0,
    "productVariantCount": 0,
    "frequencyCount": 0,
    "frequencyInterval": "DAY",
    "frequencyName": "string",
    "groupName": "string",
    "productIds": "string",
    "discountOffer": 0.1,
    "discountType": "PERCENTAGE",
    "discountEnabled": true
  }
]

Update subscription group details and product assignments

Request

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

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
Bodyapplication/jsonrequired

Complete subscription group update request including group details, selling plans, and optional product management

idinteger(int64)
productCountinteger(int64)
productVariantCountinteger(int64)
subscriptionPlansArray of objects(FrequencyInfoDTO)
groupNamestring
productIdsstring
productIdstring
variantIdsstring
accessoryProductIdsstring
updateProductsobject(ProductVariantDTO)
deleteProductsobject(ProductVariantDTO)
translationsstring
curl -i -X PUT \
  https://subscription-admin.appstle.com/api/external/v2/subscription-groups \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_1234567890abcdef' \
  -d '{
    "id": 123456789,
    "groupName": "Premium Coffee Club - Updated",
    "subscriptionPlans": [
      {
        "idNew": "gid://shopify/SellingPlan/111111",
        "frequencyName": "Monthly Delivery",
        "frequencyDescription": "Updated description with better savings",
        "frequencyCount": 1,
        "frequencyInterval": "MONTH",
        "planType": "PAY_AS_YOU_GO",
        "discountEnabled": true,
        "discountType": "PERCENTAGE",
        "discountOffer": 15,
        "afterCycle1": 0,
        "minCycles": 3
      }
    ]
  }'

Responses

Subscription group updated successfully

Bodyapplication/json
idinteger(int64)
productCountinteger(int64)
productVariantCountinteger(int64)
subscriptionPlansArray of objects(FrequencyInfoDTO)
groupNamestring
productIdsstring
productIdstring
variantIdsstring
accessoryProductIdsstring
updateProductsobject(ProductVariantDTO)
deleteProductsobject(ProductVariantDTO)
translationsstring
Response
application/json
{
  "id": 0,
  "productCount": 0,
  "productVariantCount": 0,
  "subscriptionPlans": [
    { … }
  ],
  "groupName": "string",
  "productIds": "string",
  "productId": "string",
  "variantIds": "string",
  "accessoryProductIds": "string",
  "updateProducts": {
    "productIds": [ … ],
    "variantIds": [ … ],
    "allProduct": true,
    "collectionId": "string",
    "deleteAllProduct": true,
    "productDetails": "string",
    "variantDetails": "string"
  },
  "deleteProducts": {
    "productIds": [ … ],
    "variantIds": [ … ],
    "allProduct": true,
    "collectionId": "string",
    "deleteAllProduct": true,
    "productDetails": "string",
    "variantDetails": "string"
  },
  "translations": "string"
}

Create a new subscription group (selling plan group)

Request

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

Query
isAddAllProductboolean

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.

Default false
collectionIdstring

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

Default ""
Example: collectionId=123456789
api_keystringDeprecated

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

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
Bodyapplication/jsonrequired

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

idinteger(int64)
productCountinteger(int64)
productVariantCountinteger(int64)
subscriptionPlansArray of objects(FrequencyInfoDTO)
groupNamestring
productIdsstring
productIdstring
variantIdsstring
accessoryProductIdsstring
updateProductsobject(ProductVariantDTO)
deleteProductsobject(ProductVariantDTO)
translationsstring
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-groups?isAddAllProduct=false&collectionId=123456789&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_live_1234567890abcdef' \
  -d '{
    "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}]"
  }'

Responses

Subscription group created successfully

Bodyapplication/json
idinteger(int64)
productCountinteger(int64)
productVariantCountinteger(int64)
subscriptionPlansArray of objects(FrequencyInfoDTO)
groupNamestring
productIdsstring
productIdstring
variantIdsstring
accessoryProductIdsstring
updateProductsobject(ProductVariantDTO)
deleteProductsobject(ProductVariantDTO)
translationsstring
Response
application/json
{
  "id": 0,
  "productCount": 0,
  "productVariantCount": 0,
  "subscriptionPlans": [
    { … }
  ],
  "groupName": "string",
  "productIds": "string",
  "productId": "string",
  "variantIds": "string",
  "accessoryProductIds": "string",
  "updateProducts": {
    "productIds": [ … ],
    "variantIds": [ … ],
    "allProduct": true,
    "collectionId": "string",
    "deleteAllProduct": true,
    "productDetails": "string",
    "variantDetails": "string"
  },
  "deleteProducts": {
    "productIds": [ … ],
    "variantIds": [ … ],
    "allProduct": true,
    "collectionId": "string",
    "deleteAllProduct": true,
    "productDetails": "string",
    "variantDetails": "string"
  },
  "translations": "string"
}

Build-a-Box & Bundles

APIs for managing customizable product boxes and bundles where customers can select multiple items.

Operations

Product Catalog

APIs for managing the product catalog including product information, variants, and inventory.

Operations

Operations & Settings

APIs for managing operational settings, configurations, and administrative functions.

Operations

Customer Portal

APIs powering the customer-facing portal where subscribers can manage their own subscriptions.

Operations

Customers

APIs for managing customer information, profiles, and account details.

Operations