Skip to content
External APIs
/
/
Cancel a subscription con...

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

Retrieve raw Shopify GraphQL response for a subscription contract

Request

Fetches the complete, unprocessed JSON response directly from Shopify's GraphQL API for the specified subscription contract. This endpoint returns the full subscription data structure as provided by Shopify, including all nested objects and relationships.

Use Cases:

  • Debugging subscription issues
  • Accessing all available subscription data
  • Understanding the complete data structure
  • Building custom integrations

Response Structure: The response includes complete details about:

  • Customer information (email, name, ID)
  • Line items (products, quantities, pricing)
  • Billing and delivery policies
  • Payment method details
  • Discounts and pricing policies
  • Order history and billing attempts
  • Custom attributes and notes

Note: This is a direct Shopify response with GraphQL type information (__typename fields)

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

The unique identifier of the subscription contract. Use the numeric ID without the 'gid://shopify/SubscriptionContract/' prefix. For example, use '26833420451' instead of 'gid://shopify/SubscriptionContract/26833420451'.

Example: contractId=26833420451
api_keystringDeprecated

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

Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X GET \
  'https://subscription-admin.appstle.com/api/external/v2/contract-raw-response?contractId=26833420451&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully retrieved raw contract data

Bodyapplication/json
subscriptionContractobject(SubscriptionContract)
Response
application/json
{
  "subscriptionContract": {
    "__typename": "SubscriptionContract",
    "id": "gid://shopify/SubscriptionContract/26833420451",
    "createdAt": "2025-06-19T12:19:21Z",
    "updatedAt": "2025-06-19T12:19:25Z",
    "nextBillingDate": "2025-07-19T12:00:00Z",
    "status": "ACTIVE",
    "deliveryPrice": { … },
    "lastPaymentStatus": null,
    "billingPolicy": { … },
    "deliveryPolicy": { … },
    "lines": { … },
    "customerPaymentMethod": { … },
    "customer": { … },
    "originOrder": { … },
    "note": null,
    "customAttributes": [],
    "discounts": { … }
  }
}

Cancel a subscription contract

Request

Cancels an existing subscription contract. This operation terminates all future billing and delivery cycles for the subscription. The cancellation takes effect immediately.

Important Notes:

  • Any pending/scheduled orders will be cancelled
  • The customer will receive a cancellation confirmation email if SUBSCRIPTION_CANCELLED email template is enabled
  • Cancellation feedback and notes are stored for analytics and reporting
  • Minimum cycle requirements ARE enforced via API (unlike internal cancellations)
  • If the subscription is under a free trial period, minimum cycles are not enforced

Validation Rules:

  • Contract must exist and belong to the authenticated shop
  • Contract must not already be cancelled
  • Must have completed minimum required billing cycles (unless in trial)

Post-Cancellation:

  • Status changes to 'cancelled' (lowercase)
  • Any pause settings are cleared
  • Cancellation feedback and notes are saved
  • Activity log entry is created
  • Cancellation email is sent (if enabled)
  • Any invalid discount codes are automatically removed

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)>= 1required

The unique identifier of the subscription contract to cancel. Must be a valid contract ID that belongs to the authenticated shop.

Example: 123456789
Query
cancellationFeedbackstring<= 500 characters

Optional feedback from the customer about why they are cancelling. This information is valuable for understanding cancellation reasons and improving retention. Common values include: 'Too expensive', 'No longer needed', 'Found alternative', 'Quality issues', 'Delivery issues', 'Customer service', 'Product not as expected', etc. This field is stored permanently with the contract for analytics.

Example: cancellationFeedback=Too expensive
cancellationNotestring<= 1000 characters

Optional internal note for recording additional cancellation context. This field is for internal use and not visible to customers. Can be used to track special circumstances, support ticket references, competitor information, or other relevant details about why the customer cancelled. This note is stored permanently with the contract.

Example: cancellationNote=Customer switching to competitor X due to pricing. Support ticket #12345
curl -i -X DELETE \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/123456789?cancellationFeedback=Too+expensive&cancellationNote=Customer+switching+to+competitor+X+due+to+pricing.+Support+ticket+%2312345'

Responses

Subscription successfully cancelled. No content returned.

Headers
X-Application-Contextstring

Application context

Response
No content

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