Skip to content
External APIs
/
/
Create a new subscription...

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

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"
}

Remove products or variants from a subscription group

Request

Removes specified products and/or variants from an existing subscription group (selling plan group). This endpoint allows selective removal of products without affecting the group's configuration or other product assignments.

Key Features:

  • Remove multiple products and variants in a single request
  • Remove all products from a specific collection
  • Silently ignores products/variants not currently in the group
  • Preserves subscription group configuration and settings
  • Updates synchronously and returns the modified group

Collection Removal:

  • When collectionId is provided, fetches and removes all products from that collection
  • Collection processing is limited to 5000 products maximum
  • Collection removal is additive to any explicitly specified productIds/variantIds

Important Notes:

  • Removing products does NOT affect existing active subscriptions
  • Can remove all products, leaving an empty subscription group
  • Products/variants not in the group are silently ignored
  • Use numeric IDs without gid:// prefix for products and variants

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)required

Subscription group ID (numeric ID)

Example: 123456789
Query
productIdsstring^\d+(,\d+)*$

Comma-separated list of product IDs to remove. Use numeric IDs without gid:// prefix.

Example: productIds=987654321,987654322
variantIdsstring^\d+(,\d+)*$

Comma-separated list of variant IDs to remove. Use numeric IDs without gid:// prefix.

Example: variantIds=123456789,123456790
collectionIdinteger(int64)

Shopify collection ID. When provided, removes all products from this collection (up to 5000 products). This is in addition to any explicitly specified productIds/variantIds.

Example: collectionId=287654321
deleteAllProductsAndVariantsboolean

Set to true to delete all products and their variants. Defaults to false.

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 PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-groups/123456789/remove-products?productIds=987654321%2C987654322&variantIds=123456789%2C123456790&collectionId=287654321&deleteAllProductsAndVariants=true&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Products/variants successfully removed from subscription group

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": 123456789,
  "groupName": "Monthly Coffee Subscription",
  "productCount": 5,
  "productVariantCount": 15,
  "productIds": "[{\"id\":987654322,\"title\":\"Organic Dark Roast\"},{\"id\":987654323,\"title\":\"Colombian Single Origin\"}]",
  "variantIds": "[{\"id\":123456790,\"title\":\"500g Bag\"}]",
  "subscriptionPlans": [
    { … }
  ]
}

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