Skip to content
External APIs
/
/
Add one-time product to s...

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

Add one-time product to subscription order

Request

Adds a one-time product (add-on) to a specific subscription order. The product will be included only in the specified billing attempt and will not recur in future orders. This endpoint is idempotent - attempting to add the same product to the same billing attempt will return success without creating duplicates.

Important Behaviors:

  • If the specified billingAttemptId is not valid or not QUEUED, the system will automatically add the product to the next upcoming order
  • The system prevents duplicate products (same variantId) in the same billing attempt
  • Products are automatically removed after the associated order is processed
  • Activity logs are created for audit trails

Validation Rules:

  • Contract must belong to the authenticated shop
  • Contract must not be frozen (minimum cycles restriction)
  • At least one QUEUED billing attempt must exist
  • Variant must be a valid Shopify product variant

Use Cases:

  • Allow customers to add special items to their next delivery
  • Enable upselling opportunities in customer portals
  • Programmatically add promotional or seasonal items
  • Implement "try before you subscribe" features

Authentication: Requires valid X-API-Key header that identifies the shop

Query
contractIdinteger(int64)>= 1required

The unique identifier of the subscription contract

Example: contractId=98765
billingAttemptIdinteger(int64)>= 1required

The billing attempt ID to add the product to. If invalid or not QUEUED, the system will automatically use the next upcoming order.

Example: billingAttemptId=54321
variantIdinteger(int64)>= 1required

The Shopify product variant ID to add as a one-time purchase

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

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

Example: variantHandle=premium-coffee-blend-500g
quantityinteger[ 1 .. 999 ]

The quantity of the product to add. Defaults to 1 if not specified.

Default 1
Example: quantity=2
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 PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id?contractId=98765&billingAttemptId=54321&variantId=42549172011164&variantHandle=premium-coffee-blend-500g&quantity=2&api_key=sk_live_1234567890abcdef' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully added one-time product or product already exists. Returns all one-time products for the contract.

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-store.myshopify.com",
    "subscriptionContractId": 98765,
    "billingAttemptId": 54321,
    "variantId": 42549172011164,
    "variantHandle": "premium-coffee-blend-500g",
    "quantity": 2,
    "price": 19.99
  },
  {
    "id": 12350,
    "shop": "example-store.myshopify.com",
    "subscriptionContractId": 98765,
    "billingAttemptId": 54321,
    "variantId": 42549172011167,
    "variantHandle": "coffee-sampler-pack",
    "quantity": 1,
    "price": 29.99
  }
]

Remove one-time product from subscription order

Request

Removes a previously added one-time product from a specific subscription order. This permanently deletes the one-time product from the specified billing attempt. The operation is idempotent - attempting to delete a non-existent product will succeed without error.

Important Notes:

  • Only removes the product from the specified billing attempt
  • Cannot remove products from billing attempts that are already processed
  • Activity logs are created for audit trails
  • Returns the updated list of all one-time products for the contract

Use Cases:

  • Allow customers to remove unwanted add-ons before order processing
  • Clean up cart-like functionality in customer portals
  • Programmatically manage one-time product selections
  • Implement "undo" functionality for product additions

Business Rules:

  • Contract must belong to the authenticated shop
  • The specific combination of contractId + billingAttemptId + variantId identifies the product to remove
  • No error is thrown if the product doesn't exist (idempotent operation)

Authentication: Requires valid X-API-Key header that identifies the shop

Query
contractIdinteger(int64)>= 1required

The unique identifier of the subscription contract

Example: contractId=98765
billingAttemptIdinteger(int64)>= 1required

The billing attempt ID that contains the product to remove

Example: billingAttemptId=54321
variantIdinteger(int64)>= 1required

The Shopify product variant ID to remove from the one-time purchases

Example: variantId=42549172011164
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 DELETE \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id?contractId=98765&billingAttemptId=54321&variantId=42549172011164&api_key=sk_live_1234567890abcdef' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully removed the one-time product or product didn't exist. Returns all remaining one-time products for the contract.

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-store.myshopify.com",
    "subscriptionContractId": 98765,
    "billingAttemptId": 54321,
    "variantId": 42549172011164,
    "variantHandle": "premium-coffee-blend-500g",
    "quantity": 2,
    "price": 19.99
  }
]

Get one-time products for next upcoming order

Request

Retrieves one-time products that will be included in the next scheduled order for a subscription contract. This endpoint specifically returns products associated with the earliest queued billing attempt, making it ideal for showing customers what additional items will be in their next delivery.

Key Differences from /subscription-contract-one-offs-by-contractId:

  • Returns ONLY products for the next upcoming order (not all future orders)
  • Finds the earliest QUEUED billing attempt by date
  • Returns empty array if no queued billing attempts exist
  • Useful for "Your Next Order" previews in customer portals

Use Cases:

  • Display a preview of the next order including one-time add-ons
  • Calculate the total cost of the upcoming delivery
  • Show customers their next delivery date with associated one-time items
  • Allow last-minute modifications before order processing

Business Logic:

  1. Searches for billing attempts with status = QUEUED
  2. Selects the one with the earliest billing date
  3. Returns all one-time products for that specific billing attempt
  4. Returns empty array if no queued orders exist (e.g., subscription paused/cancelled)

Authentication: Requires valid X-API-Key header that identifies the shop

Query
contractIdinteger(int64)>= 1required

The unique identifier of the subscription contract to retrieve upcoming 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/upcoming-subscription-contract-one-offs-by-contractId?contractId=98765&api_key=sk_live_1234567890abcdef' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully retrieved next order 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"
  }
]

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

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