Skip to content
/Product Catalog

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

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

Get all product swaps for a shop

Request

Retrieves all configured product swap automations for the authenticated shop. Product swaps allow automatic replacement of products in subscription orders based on billing cycles or recurring schedules.

What are Product Swaps? Product swaps enable merchants to automatically replace products in subscription orders at specific billing cycles. This is useful for seasonal products, progression paths (e.g., beginner → intermediate → advanced), or variety subscriptions.

Key Features:

  • View all configured swap automations
  • See source and destination product mappings
  • Check which billing cycles trigger swaps
  • Identify recurring vs one-time swaps
  • Review discount carry-forward settings

Swap Configuration Types:

  • One-Time Swap: Occurs at a specific billing cycle
  • Recurring Swap: Occurs at every order
  • Conditional Swap: Based on billing cycle number

Use Cases:

  • Seasonal product rotations (summer → fall → winter products)
  • Subscription progression (trial → full product)
  • Variety boxes with automatic product rotation
  • Product lifecycle management in subscriptions
  • A/B testing different products in subscriptions

Authentication: Requires valid X-API-Key header

Query
ruleNamestring
sourceVariantsstring
destinationVariantsstring
Headers
X-API-Keystring
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/product-swaps?ruleName=string&sourceVariants=string&destinationVariants=string' \
  -H 'X-API-Key: string'

Responses

Successfully retrieved product swaps

Bodyapplication/json
idinteger(int64)
shopstringrequired
sourceVariantsstring
destinationVariantsstring
updatedFirstOrderboolean
checkForEveryRecurringOrderboolean
namestring
changeNextOrderDateByinteger(int32)
forBillingCycleinteger(int32)
carryDiscountForwardboolean
ruleSequenceinteger(int32)
stopSwapEmailsboolean
discountCarryForwardstring
Enum"NONE""EXISTING_PLAN""PRODUCT_PLAN""PRODUCT_THEN_EXISTING"
Response
application/json
[
  {
    "id": 10782,
    "shop": "example-shop.myshopify.com",
    "sourceVariants": "[{\"id\":12345,\"displayName\":\"Summer Blend Coffee\",\"imageSrc\":\"https://cdn.shopify.com/image1.jpg\",\"quantity\":2}]",
    "destinationVariants": "[{\"id\":67890,\"displayName\":\"Fall Blend Coffee\",\"imageSrc\":\"https://cdn.shopify.com/image2.jpg\",\"quantity\":2}]",
    "updatedFirstOrder": false,
    "checkForEveryRecurringOrder": false,
    "name": "Seasonal Coffee Rotation",
    "forBillingCycle": 4,
    "carryDiscountForward": true,
    "stopSwapEmails": false,
    "discountCarryForward": "PERCENTAGE",
    "active": true,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": 10783,
    "shop": "example-shop.myshopify.com",
    "sourceVariants": "[{\"id\":22222,\"displayName\":\"Beginner Kit\",\"imageSrc\":\"https://cdn.shopify.com/kit1.jpg\",\"quantity\":1}]",
    "destinationVariants": "[{\"id\":33333,\"displayName\":\"Advanced Kit\",\"imageSrc\":\"https://cdn.shopify.com/kit2.jpg\",\"quantity\":1}]",
    "updatedFirstOrder": false,
    "checkForEveryRecurringOrder": true,
    "name": "Monthly Variety Swap",
    "forBillingCycle": null,
    "carryDiscountForward": false,
    "stopSwapEmails": true,
    "discountCarryForward": "NONE",
    "active": true
  }
]

Get product swap variant groups for a contract

Request

Retrieves product swap variant groups for the next 10 billing cycles of a specific subscription contract. This endpoint calculates and returns which products will be swapped to in future billing cycles based on configured swap automations.

Response Structure: Returns a 2D array (List<List>):

  • Outer array: Represents the next 10 billing cycles
  • Inner arrays: Contains the variant(s) that will be swapped to for that specific cycle
  • Index 0: Variants for the next (upcoming) billing cycle
  • Index 1: Variants for the cycle after that
  • And so on for the next 10 cycles

Variant Details: Each variant object includes:

  • variantId: Shopify variant ID
  • quantity: Number of units to swap
  • title: Variant title (e.g., "Medium Roast - 12oz")
  • image: Product/variant image URL
  • productTitle: Full product name
  • productId: Shopify product GID
  • variantTitle: Full display name combining product and variant titles
  • swapId: ID of the swap automation rule that triggered this swap

How It Works:

  1. Takes the current products in the subscription
  2. Applies configured swap automations for the next 10 cycles
  3. Calculates which products will be swapped based on:
    • Billing cycle number
    • Swap rule configurations (forBillingCycle, checkForEveryRecurringOrder)
    • Rule sequence/priority
  4. Returns the projected product lineup for each cycle

Use Cases:

  • Preview upcoming product swaps in customer portals
  • Show customers their subscription product timeline
  • Build interactive swap calendars
  • Display "what you'll receive" for future orders
  • Debug and verify swap automation configurations

Important Notes:

  • Returns 10 cycles even if no swaps are configured (returns current products)
  • Multiple variants in an inner array means multiple products will be in that order
  • Empty inner arrays indicate no products for that cycle (rare edge case)
  • The swapId can be used to trace which automation rule triggered the swap

Authentication: Requires valid X-API-Key header

Path
contractIdinteger(int64)required
Query
api_keystring

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

Headers
X-API-Keystring
Bodyapplication/jsonrequired

VariantQuantityInfo payload

variantQuantityListArray of objects(VariantQuantity)
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/product-swaps-by-variant-groups/{contractId}?api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "variantQuantityList": [
      {
        "variantId": 12345,
        "quantity": 2,
        "swapId": 1001
      },
      {
        "variantId": 67890,
        "quantity": 2,
        "swapId": 1002
      }
    ]
  }'

Responses

Product swap variant groups returned successfully - Returns swappable variants for the next 10 billing cycles. Each element in the outer array represents the variants that will be swapped to for a specific billing cycle.

Bodyapplication/json
Response
application/json
[
  [
    { … },
    { … }
  ],
  [
    { … }
  ]
]

Get all one-time products for a subscription contract

Request

Retrieves all one-time products (add-ons) associated with a specific subscription contract across all billing attempts. One-time products are additional items that customers can add to their subscription orders on a non-recurring basis. Each one-time product is tied to a specific billing attempt and will only be included in that particular order.

Key Features:

  • Returns ALL one-time products across all queued billing attempts
  • Each product includes the billing attempt ID to identify which order it belongs to
  • Includes product details: variant ID, quantity, title, image, and price
  • Products are automatically removed after the associated billing attempt is processed

Use Cases:

  • Display all one-time products added to a subscription across all upcoming orders
  • Allow customers to review their one-time add-ons in customer portal
  • Enable merchants to see all one-time products for a contract
  • Integrate with external systems to manage subscription add-ons

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

The unique identifier of the subscription contract to retrieve one-time products for

Example: contractId=98765
api_keystringDeprecated

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

Example: api_key=sk_live_1234567890abcdef
Headers
X-API-Keystringrequired

API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.

Example: sk_live_1234567890abcdef
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId?contractId=98765&api_key=sk_live_1234567890abcdef' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully retrieved one-time products

Bodyapplication/jsonArray [
idinteger(int64)read-only

Unique identifier of the one-time product record

Example: 12345
shopstring^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$required

The Shopify store domain that owns this subscription

Example: "example-store.myshopify.com"
billingAttemptIdinteger(int64)>= 1

The billing attempt ID this one-time product is associated with. This determines which upcoming order will include this product.

Example: 54321
subscriptionContractIdinteger(int64)>= 1

The subscription contract ID this one-time product belongs to

Example: 98765
variantIdinteger(int64)>= 1

The Shopify product variant ID for this one-time product

Example: 42549172011164
variantHandlestring^[a-z0-9]+(?:-[a-z0-9]+)*$

The handle/slug of the product variant for URL-friendly identification

Example: "premium-coffee-blend-500g"
quantityinteger(int32)[ 1 .. 999 ]

The quantity of this product to include in the order

Example: 2
pricenumber(double)[ 0 .. 999999.99 ]

The price per unit of this product in the shop's base currency. This may include any applicable discounts.

Example: 19.99
]
Response
application/json
[
  {
    "id": 12345,
    "shop": "example-shop.myshopify.com",
    "contractId": 67890,
    "billingAttemptId": 11111,
    "variantId": 22222,
    "quantity": 2,
    "productTitle": "Coffee Filters - Pack of 100",
    "variantTitle": "Standard Size",
    "image": "https://cdn.shopify.com/s/files/1/0000/0000/products/filter.jpg",
    "price": "9.99",
    "currencyCode": "USD",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": 12346,
    "shop": "example-shop.myshopify.com",
    "contractId": 67890,
    "billingAttemptId": 11112,
    "variantId": 33333,
    "quantity": 1,
    "productTitle": "Coffee Scoop",
    "variantTitle": "Stainless Steel",
    "image": "https://cdn.shopify.com/s/files/1/0000/0000/products/scoop.jpg",
    "price": "14.99",
    "currencyCode": "USD",
    "createdAt": "2024-01-16T14:20:00Z",
    "updatedAt": "2024-01-16T14:20:00Z"
  }
]

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