Skip to content
🔧 Admin APIs
/
/
Update maximum billing cy...

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

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

Update minimum billing cycles for subscription contract

Request

Sets the minimum number of billing cycles (payments) required before a customer can cancel their subscription. This is commonly used to enforce commitment periods or prevent early cancellations.

Key Features:

  • Commitment Enforcement: Require customers to stay subscribed for a minimum period
  • Cancellation Prevention: Blocks cancellation until minimum cycles are met
  • Contract Terms: Implements contractual minimum billing requirements
  • Flexible Duration: Set any number from 0 (no minimum) to higher values

Common Use Cases:

  • 3-Month Minimum: Set minCycles=3 for quarterly commitment
  • Annual Contract: Set minCycles=12 for yearly subscriptions
  • Trial Completion: Require 1-2 cycles before allowing cancellation
  • Remove Restriction: Set minCycles=0 or null to remove minimum

Behavior:

  • Customer portal will show "X cycles remaining until cancellation allowed"
  • Cancellation button disabled until minimum met
  • Does not affect pausing subscriptions
  • Applies to future billing cycles, not retroactive

Parameters:

  • contractId (required): The subscription contract ID
  • minCycles (optional): Number of minimum cycles (null or 0 = no minimum)

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

Query
contractIdinteger(int64)required

Subscription contract ID

Example: contractId=12345
api_keystring

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

minCyclesinteger(int32)

Minimum number of billing cycles required (null or 0 = no minimum)

Example: minCycles=3
Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-min-cycles?contractId=12345&api_key=string&minCycles=3' \
  -H 'X-API-Key: string'

Responses

Min cycles updated successfully, returns updated subscription contract

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string",
    "id": "string",
    "methodType": "SHIPPING",
    "serviceCode": "string",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": { … },
    "brandedPromise": { … }
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

Update maximum billing cycles for subscription contract

Request

Sets the maximum number of billing cycles (payments) after which the subscription will automatically expire and cancel. This is useful for creating fixed-term memberships or limited-duration subscriptions.

Key Features:

  • Auto-Expiration: Subscription automatically cancels after max cycles reached
  • Fixed-Term Plans: Create memberships with defined end dates
  • No Manual Intervention: System handles cancellation automatically
  • Flexible Duration: Set any number or null for unlimited

Common Use Cases:

  • 6-Month Program: Set maxCycles=6 for half-year membership
  • Annual Subscription: Set maxCycles=12 for one-year auto-expiring plan
  • Trial Extensions: Set maxCycles=3 for limited trial periods
  • Unlimited Subscription: Set maxCycles=null or 0 for no maximum

Behavior:

  • Subscription cancels automatically after final billing cycle
  • Customer receives notification before expiration
  • No refunds issued on auto-cancellation
  • Contract status changes to EXPIRED after last cycle

Parameters:

  • contractId (required): The subscription contract ID
  • maxCycles (optional): Maximum number of billing cycles (null or 0 = unlimited)

Note: Setting maxCycles lower than current cycle count will cause immediate expiration.

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

Query
contractIdinteger(int64)required

Subscription contract ID

Example: contractId=12345
api_keystring

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

maxCyclesinteger(int32)

Maximum number of billing cycles (null or 0 = unlimited)

Example: maxCycles=12
Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles?contractId=12345&api_key=string&maxCycles=12' \
  -H 'X-API-Key: string'

Responses

Max cycles updated successfully, returns updated subscription contract

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string",
    "id": "string",
    "methodType": "SHIPPING",
    "serviceCode": "string",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": { … },
    "brandedPromise": { … }
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

Update subscription line item quantity and pricing

Request

Updates an existing line item in a subscription contract, modifying quantity, variant, or price. This endpoint allows comprehensive updates to subscription products.

Line Item Update Process:

  • Line Item Identification: Locates line item using GraphQL line ID
  • Quantity Update: Changes product quantity for recurring orders
  • Variant Change: Can switch to different variant of same product
  • Price Override: Optional custom pricing override
  • Contract Sync: Updates Shopify subscription contract
  • Activity Logging: Records line item modification event

Update Capabilities:

  • Quantity Adjustment: Increase or decrease product quantity
  • Variant Switching: Change product variant (size, color, flavor, etc.)
  • Custom Pricing: Override standard pricing per line item
  • Combined Updates: Change multiple properties in single request

Parameters:

  • lineId: GraphQL ID of line item to update
  • quantity: New quantity (must be positive integer)
  • variantId: Product variant ID (can change to different variant)
  • price: Custom price override (optional, overrides default pricing)

Price Override:

  • Allows custom per-line pricing
  • Useful for special pricing arrangements
  • Overrides default product pricing
  • Price in shop's base currency

Use Cases:

  • Customer increases/decreases product quantity
  • Switch product variant (e.g., Medium → Large roast)
  • Special pricing for VIP customers
  • Seasonal variant changes (Summer → Winter flavor)
  • Customer portal quantity adjustments
  • Wholesale pricing overrides
  • Build-a-box quantity modifications

Important Notes:

  • Quantity must be positive (use remove-line-item to delete)
  • Variant must be valid and available
  • Price updates don't affect existing discount percentages
  • Changes apply to next billing cycle

Returns: Updated subscription contract object with modified line item

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

Query
contractIdinteger(int64)required

Subscription contract ID

Example: contractId=123456789
api_keystring

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

quantityinteger(int32)required

New quantity for the line item

Example: quantity=3
variantIdstringrequired

Product variant ID (can be different variant)

Example: variantId=12345678
lineIdstringrequired

Line item GraphQL ID to update

Example: lineId=gid://shopify/SubscriptionLine/987654321
pricenumber(double)required

Custom price override (optional)

Example: price=29.99
Headers
X-API-Keystring
curl -i -X PUT \
  'https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item?contractId=123456789&api_key=string&quantity=3&variantId=12345678&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLine%2F987654321&price=29.99' \
  -H 'X-API-Key: string'

Responses

Line item successfully updated

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string",
    "id": "string",
    "methodType": "SHIPPING",
    "serviceCode": "string",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": { … },
    "brandedPromise": { … }
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

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