Skip to content
External APIs
/
/
Update subscription deliv...

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

Update maximum cycles for a subscription contract

Request

Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders.

What are Maximum Cycles? Maximum cycles define subscription duration limits where:

  • Subscription automatically cancels after the specified number of orders
  • No further orders are generated once maximum is reached
  • Useful for fixed-term offers, trials, or seasonal subscriptions
  • Customer is notified before final order (if configured)

Key Features:

  • Cannot set below current cycle count (prevents immediate cancellation)
  • Setting to null creates an indefinite subscription
  • Automatically reschedules order queue based on new limit
  • Preserves all other subscription settings
  • Validates against current subscription progress

Current Cycle Calculation:

  • Current cycle = Successful billing attempts + 1
  • Failed payments don't count toward maximum
  • First order is cycle 1, second is cycle 2, etc.
  • System prevents setting max below current position

Common Use Cases:

  • Trial Subscriptions: '3-box trial' that auto-ends
  • Seasonal Programs: '6-month summer subscription'
  • Limited Series: '12-issue magazine subscription'
  • Promotional Offers: 'First 5 boxes at special price'
  • Gift Subscriptions: Fixed duration gifts that don't renew

What Happens at Maximum: When a subscription reaches its maximum cycles:

  1. Final order is processed normally
  2. Subscription status changes to CANCELLED
  3. No future orders are scheduled
  4. Customer receives cancellation notification
  5. Cannot be reactivated (new subscription required)

Interaction with Min Cycles:

  • Can have both min and max (e.g., 3 min, 12 max)
  • Min cycles enforces commitment period
  • Max cycles enforces termination
  • Common pattern: Commitment with defined end

Queue Management: After updating max cycles:

  • System recalculates future order schedule
  • Removes orders beyond the new maximum
  • Adjusts upcoming order notifications
  • Updates subscription end date projections

Important Notes:

  • Validation prevents accidental immediate cancellation
  • Changes apply to future billing cycles only
  • Activity log tracks old and new values
  • Consider customer communication for changes
  • Setting null removes any duration limit

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required

Contract ID

api_keystring

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

maxCyclesinteger or null[ 1 .. 9999 ]required

Maximum Cycles. The total number of orders after which the subscription will automatically terminate. Must be greater than or equal to the current cycle count and any configured minimum cycles. Common values:

  • 3: Three-order trial
  • 6: Six-month seasonal subscription
  • 12: Annual subscription
  • 24: Two-year commitment
  • null: Ongoing subscription with no end date
Example: maxCycles=12
Headers
X-API-Keystring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-max-cycles?contractId=0&api_key=string&maxCycles=12' \
  -H 'X-API-Key: string'

Responses

Maximum cycles updated successfully

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
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "displayName": "John Doe"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 3,
    "maxCycles": 12,
    "anchors": [ … ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lastBillingAttemptDate": "2024-03-01T00:00:00Z",
  "orders": {
    "edges": [ … ]
  },
  "lines": {
    "edges": [ … ]
  }
}

Update subscription delivery method

Request

Updates the delivery method for a subscription contract, supporting standard shipping, local delivery, and customer pickup options. The delivery method determines how future orders will be fulfilled.

Delivery Method Types: The system automatically determines the type based on the subscription's current delivery address:

  • SHIPPING: Standard shipping to customer address (default)
  • LOCAL: Local delivery within merchant's delivery zones
  • PICK_UP: Customer pickup at designated location

Two Ways to Update:

  1. Manual Parameters: Provide title, code, and presentment title directly
  2. Delivery Method ID: Provide a Shopify DeliveryMethodDefinition ID to auto-populate all fields

Using Delivery Method ID: When providing a delivery-method-id:

  • System fetches the method from Shopify's delivery profiles
  • Automatically sets title, code, and presentment title
  • Applies associated delivery price if defined
  • ID can be numeric or full GraphQL ID format

Delivery Type Requirements:

  • Standard Shipping: No additional requirements
  • Local Delivery: Phone number must exist in delivery address
  • Pickup: Pickup location must be configured in subscription

Price Updates:

  • If using delivery-method-id with a fixed price, updates delivery price
  • Manual updates don't change the delivery price
  • Price changes affect all future orders

Side Effects:

  • Creates activity log entry with method details
  • May remove invalid discount codes automatically
  • Updates apply to all future orders immediately
  • No customer notification sent

Common Use Cases:

  • Switch from standard shipping to express shipping
  • Change pickup location for customer convenience
  • Update local delivery options based on availability
  • Apply seasonal delivery methods

Important Notes:

  • Cannot change the delivery type (shipping/local/pickup) - only the method within that type
  • Delivery methods must be configured in Shopify's shipping settings
  • Changes don't affect orders already in fulfillment

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to update

Example: contractId=123456789
delivery-method-titlestring<= 255 charactersrequired

Display name of the delivery method. This is what customers see. Ignored if delivery-method-id is provided.

Example: delivery-method-title=Express Shipping
delivery-method-codestring<= 255 charactersrequired

Internal code for the delivery method. Often same as title. Used for system identification. Ignored if delivery-method-id is provided.

Example: delivery-method-code=EXPRESS_SHIP
delivery-method-presentment-titlestring<= 255 charactersrequired

Localized version of the title for multi-language stores. Often same as title for single-language stores. Ignored if delivery-method-id is provided.

Example: delivery-method-presentment-title=Express Shipping
delivery-method-idstring

Optional Shopify DeliveryMethodDefinition ID. When provided, automatically fetches and applies the delivery method's title, code, presentment title, and price. Can be numeric ID or full GraphQL ID (gid://shopify/DeliveryMethodDefinition/123).

Example: delivery-method-id=123456
Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-delivery-method?contractId=123456789&delivery-method-title=Express+Shipping&delivery-method-code=EXPRESS_SHIP&delivery-method-presentment-title=Express+Shipping&delivery-method-id=123456' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Delivery method successfully updated

Headers
X-Alertstring

Success message

Example: "Subscription Updated"
Response
No content

Update delivery interval for a subscription contract

Request

Updates the delivery interval for the specified subscription contract. This endpoint allows external API consumers to change the delivery interval count and type (of type SellingPlanInterval) used for scheduling deliveries.

The service validates that the contract exists, that the new delivery interval differs from the current setting, and that it meets all business rules.

Authentication is enforced via the X-API-Key header (the 'api_key' parameter is deprecated).

Query
contractIdinteger(int64)required

Contract ID

api_keystring

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

deliveryIntervalCountinteger(int32)required

Delivery Interval Count

deliveryIntervalstringrequired

Delivery Interval Type

Enum"DAY""WEEK""MONTH""YEAR""$UNKNOWN"
Headers
X-API-Keystring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-delivery-interval?contractId=0&api_key=string&deliveryIntervalCount=0&deliveryInterval=DAY' \
  -H 'X-API-Key: string'

Responses

Delivery interval updated successfully

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"
  },
  "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": [ … ]
  }
}

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

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