Skip to content
🔧 Admin APIs
/
/
Get one-time add-ons for...

External (0.0.1)

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

Shipping & Delivery Profiles

APIs for managing Shopify delivery profiles, shipping rates, zones, and free shipping configuration for subscription memberships

Operations

Customer Discount History

APIs for retrieving historical discount code usage and redemption information for membership contracts

Operations

Cancellation Flow Configuration

APIs for managing membership cancellation flow settings including retention offers, survey questions, and cancel confirmation screens

Operations

Billing & Orders

APIs for managing membership billing attempts, recurring orders, payment retries, order history, and order skipping

Operations

One-Time Add-Ons

APIs for managing one-time product additions to upcoming subscription orders, including adding, retrieving, and removing one-off items

Operations

Add one-time product to upcoming order

Request

Adds a one-time product (one-off) to a specific upcoming billing attempt for a membership contract. The product will be included only in the specified order and will not become part of the recurring subscription.

Key Features:

  • One-Time Addition: Product added to single order only
  • Billing Cycle Targeting: Specify exact order to add item to
  • No Subscription Impact: Doesn't change recurring items
  • Instant Upsell: Add products between regular billing cycles
  • Customer Flexibility: Allow members to add extras to next order
  • Activity Logging: Tracks who added the item (merchant vs API)

Required Parameters:

  • Contract ID: Target subscription contract
  • Billing Attempt ID: Specific upcoming order to add item to
  • Variant ID: Shopify product variant to add
  • Variant Handle: Product handle for identification

How It Works:

  1. Validates contract exists and belongs to shop
  2. Checks if contract is not frozen (minimum cycles)
  3. Verifies billing attempt is upcoming (not already processed)
  4. Adds variant to the specified billing attempt
  5. Returns updated list of all one-offs for the contract
  6. Logs activity for audit trail

Use Cases:

  • Customer wants to add a bonus product to next delivery
  • Merchant offers limited-time add-on to existing members
  • Trial/sample products added to specific orders
  • Holiday specials or seasonal items
  • Promotional gifts or rewards
  • One-time upsells in customer portal

Business Rules:

  • Item added only to specified billing attempt
  • Cannot add to past or completed orders
  • Contract must not be frozen/minimum cycle locked
  • Duplicate items increment quantity

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Query
api_keystring

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

contractIdinteger(int64)required

Subscription contract ID

Example: contractId=123456
billingAttemptIdinteger(int64)required

Billing attempt ID to add the item to

Example: billingAttemptId=789012
variantIdinteger(int64)required

Product variant ID to add

Example: variantId=456789
variantHandlestringrequired

Product handle for identification

Example: variantHandle=coffee-beans-1lb
Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id?api_key=string&contractId=123456&billingAttemptId=789012&variantId=456789&variantHandle=coffee-beans-1lb' \
  -H 'X-API-Key: string'

Responses

One-off product successfully added, returns updated list of all one-offs

Bodyapplication/jsonArray [
idinteger(int64)
shopstringrequired
billingAttemptIdinteger(int64)
subscriptionContractIdinteger(int64)
variantIdinteger(int64)
variantHandlestring
]
Response
application/json
[
  {
    "id": 0,
    "shop": "string",
    "billingAttemptId": 0,
    "subscriptionContractId": 0,
    "variantId": 0,
    "variantHandle": "string"
  }
]

Remove one-time product from upcoming order

Request

Removes a previously added one-time product (one-off) from a specific upcoming billing attempt. This allows customers or merchants to cancel add-on items before the order is processed.

Key Features:

  • Flexible Cancellation: Remove add-ons before order processes
  • Targeted Removal: Remove specific variant from specific order
  • No Subscription Impact: Doesn't affect recurring items
  • Customer Control: Let members manage their add-ons
  • Activity Logging: Tracks removal for audit trail

Required Parameters:

  • Contract ID: Target subscription contract
  • Billing Attempt ID: Order to remove item from
  • Variant ID: Product variant to remove

How It Works:

  1. Validates contract exists and belongs to shop
  2. Finds one-off matching contract, billing attempt, and variant
  3. Deletes the one-off record
  4. Returns updated list of remaining one-offs
  5. Logs removal activity for audit trail

Use Cases:

  • Customer changes mind about add-on product
  • Remove out-of-stock items from upcoming orders
  • Cancel promotional items no longer available
  • Customer wants to reduce order total
  • Merchant corrects mistakenly added items
  • Manage add-ons in customer portal

Business Rules:

  • Can only remove from upcoming (unprocessed) orders
  • Must match exact contract, billing attempt, and variant
  • Returns remaining one-offs after deletion
  • Cannot remove from past/completed orders

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Query
api_keystring

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

contractIdinteger(int64)required

Subscription contract ID

Example: contractId=123456
billingAttemptIdinteger(int64)required

Billing attempt ID to remove the item from

Example: billingAttemptId=789012
variantIdinteger(int64)required

Product variant ID to remove

Example: variantId=456789
Headers
X-API-Keystring
curl -i -X DELETE \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id?api_key=string&contractId=123456&billingAttemptId=789012&variantId=456789' \
  -H 'X-API-Key: string'

Responses

One-off product successfully removed, returns updated list of remaining one-offs

Bodyapplication/jsonArray [
idinteger(int64)
shopstringrequired
billingAttemptIdinteger(int64)
subscriptionContractIdinteger(int64)
variantIdinteger(int64)
variantHandlestring
]
Response
application/json
[
  {
    "id": 0,
    "shop": "string",
    "billingAttemptId": 0,
    "subscriptionContractId": 0,
    "variantId": 0,
    "variantHandle": "string"
  }
]

Get one-time add-ons for a membership contract

Request

Retrieves all one-time product additions scheduled for upcoming orders of a specific membership contract. One-offs are products added to a single billing cycle without affecting the recurring subscription items.

Key Information Returned:

  • One-Off Items: List of products added to upcoming orders
  • Product Details: Variant ID, handle, title, price, image
  • Billing Association: Which billing attempt the item is added to
  • Quantity: Number of units for the one-time add-on
  • Status: Active, pending, or fulfilled one-offs
  • Created Date: When the one-off was added

One-Off Item Data:

  • Contract ID: Parent subscription contract
  • Billing Attempt ID: Specific order the item will be added to
  • Variant Info: Product variant being added
  • Pricing: One-time price for the add-on
  • Fulfillment Status: Whether item has been shipped

Use Cases:

  • Display scheduled one-time add-ons in customer portal
  • Show customers which extra items are in next order
  • Sync one-off data with external order management systems
  • Generate custom order previews for customers
  • Build upsell dashboards showing add-on purchases
  • Track one-time product revenue per contract

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Query
api_keystring

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

contractIdinteger(int64)required

Subscription contract ID

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

Responses

One-off items successfully retrieved

Bodyapplication/jsonArray [
idinteger(int64)
shopstringrequired
billingAttemptIdinteger(int64)
subscriptionContractIdinteger(int64)
variantIdinteger(int64)
variantHandlestring
]
Response
application/json
[
  {
    "id": 0,
    "shop": "string",
    "billingAttemptId": 0,
    "subscriptionContractId": 0,
    "variantId": 0,
    "variantHandle": "string"
  }
]

Membership Plans

APIs for managing membership/subscription plan groups, including creating plans, configuring discounts, billing intervals, and assigning products to plans

Operations

Product Bundles

APIs for managing subscription product bundles, bundle configurations, item grouping, and bundle-specific discount codes

Operations

Custom CSS Styling

APIs for retrieving custom CSS styles applied to subscription widgets and customer portal for theme customization

Operations

Customer Portal Configuration

APIs for managing customer portal settings including UI customization, text labels, feature toggles, and branding options for the member self-service portal

Operations

Membership Contracts

APIs for managing membership/subscription contracts including creation, updates, status changes, line items, discounts, and billing operations

Operations

Bundle Settings

APIs for managing subscription bundle configuration settings including bundle behavior, pricing rules, and display options

Operations

Customer Payment Methods

APIs for managing customer payment methods, payment tokens, and payment method retrieval for subscriptions

Operations

Product Swap Rules

APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups

Operations

Subscription Contract Management

Operations

Subscription Billing

Operations

Billing Attempts

Operations