Skip to content
External APIs
/
/
Get a specific product sw...

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

Get a specific product swap by ID

Request

Retrieves detailed information about a specific product swap automation configuration. This endpoint returns complete details about the source products, destination products, swap triggers, and all associated settings.

Response Details:

  • Complete swap configuration
  • Source product variants with images and quantities
  • Destination product variants with images and quantities
  • Billing cycle triggers and conditions
  • Discount carry-forward settings
  • Email notification preferences
  • Swap status and history

Source and Destination Variants: Both source and destination variants are returned as JSON strings containing:

  • Variant ID
  • Display name/title
  • Product image URL
  • Quantity to swap
  • Product metadata

Swap Timing:

  • forBillingCycle: If set, swap occurs at this specific cycle number
  • checkForEveryRecurringOrder: If true, swap happens on every order
  • updatedFirstOrder: If true, can affect the initial subscription order

Discount Handling:

  • NONE: No discount carried forward
  • PERCENTAGE: Percentage discount is maintained
  • FIXED_AMOUNT: Fixed amount discount is maintained
  • PRICE: Specific price point is maintained

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)required
Headers
X-API-Keystring
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/product-swaps/{id}' \
  -H 'X-API-Key: string'

Responses

Product swap returned successfully

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": 0,
  "shop": "string",
  "sourceVariants": "string",
  "destinationVariants": "string",
  "updatedFirstOrder": true,
  "checkForEveryRecurringOrder": true,
  "name": "string",
  "changeNextOrderDateBy": 0,
  "forBillingCycle": 0,
  "carryDiscountForward": true,
  "ruleSequence": 0,
  "stopSwapEmails": true,
  "discountCarryForward": "NONE"
}

Delete a product swap automation

Request

Permanently deletes a product swap automation configuration. Once deleted, the swap will no longer be applied to any subscription orders. Existing subscriptions that have already had products swapped are not affected.

Deletion Behavior:

  • Permanently removes the swap automation
  • Does not reverse past swaps that have already occurred
  • Future orders will not have this swap applied
  • Cannot be undone - swap configuration must be recreated if needed

Impact on Subscriptions:

  • Active Subscriptions: Will continue with current products (no automatic reversion)
  • Future Orders: Swap will not be applied
  • Past Orders: Already swapped products remain unchanged
  • Queued Swaps: Pending swaps for this automation are cancelled

When to Delete:

  • Discontinuing a seasonal product rotation
  • Removing outdated swap rules
  • Cleaning up test or experimental swaps
  • Product lines being discontinued
  • Correcting misconfigured swaps

Important Notes:

  • This operation is permanent and cannot be undone
  • Consider deactivating instead of deleting if you might reuse the configuration
  • Activity logs for past swaps are retained
  • Customers are not automatically notified of swap deletion

Best Practices:

  • Review affected subscriptions before deletion
  • Consider communicating changes to affected customers
  • Export swap configuration if you might need it later
  • Use deactivation for temporary pauses instead of deletion

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)required
Headers
X-API-Keystring
curl -i -X DELETE \
  'https://subscription-admin.appstle.com/api/external/v2/product-swaps/{id}' \
  -H 'X-API-Key: string'

Responses

Product swap successfully deleted - No content returned

Response
No content

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