Skip to content
External APIs
/
/
Retrieve raw Shopify Grap...

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 subscription contracts

Request

Retrieves a paginated list of subscription contracts with powerful filtering capabilities. This endpoint enables complex queries to find specific subscriptions based on various criteria including dates, customer information, product details, and subscription characteristics.

Key Features:

  • Comprehensive filtering across 20+ parameters
  • Full pagination support with customizable page size
  • Partial text matching for customer and order searches
  • Date range filtering for multiple date fields
  • Product and variant filtering within line items
  • Order amount range filtering
  • Plan type differentiation (prepaid vs pay-per-delivery)

Pagination:

  • Uses Spring's Pageable format
  • Default page size: 20 items
  • Maximum page size: 2000 items (exceeding this limit will result in a 400 error)
  • Returns total count in X-Total-Count header
  • Provides navigation links in Link header

IMPORTANT - Sorting Limitations: Due to the use of native SQL queries, sort parameters MUST use database column names (snake_case) rather than Java field names (camelCase).

Common sorting examples:

  • sort=next_billing_date,asc (NOT nextBillingDate)
  • sort=customer_name,desc (NOT customerName)
  • sort=created_at,asc (NOT createdAt)
  • sort=subscription_contract_id,desc (NOT subscriptionContractId)
  • sort=order_amount,asc (NOT orderAmount)

Date Format: All date parameters use ISO 8601 format with timezone: yyyy-MM-dd'T'HH:mm:ssXXX Examples: 2024-03-15T10:30:00+00:00 or 2024-03-15T10:30:00Z

Date Range Filtering:

  • For created, updated dates: Can use either 'from', 'to', or both
  • For next billing date: Both 'from' and 'to' must be provided together (current limitation)

Text Search Behavior:

  • Customer name searches both name and email fields
  • Order name searches current and historical orders (in subscription_billing_attempt table)
  • All text searches are case-insensitive
  • Partial matches are supported (contains logic)
  • Subscription contract ID search supports partial numeric matching

Plan Type Classification:

  • prepaid: Billing interval > delivery interval
  • non-prepaid: Billing interval = delivery interval

Performance Considerations:

  • Complex filters (especially JSON searches and order amount calculations) may impact response time
  • Use specific filters when possible
  • Consider smaller page sizes for complex queries
  • Product, variant, and selling plan searches use JSON_SEARCH which may be slow on large datasets

Authentication: Requires valid X-API-Key header (the deprecated 'api_key' query parameter is still accepted but not recommended)

Query
fromCreatedDatestring(date-time)

Filter by subscriptions created on or after this date

Example: fromCreatedDate=2025-10-01T00:00:00+02:00
toCreatedDatestring(date-time)

Filter by subscriptions created on or before this date

Example: toCreatedDate=2025-10-31T23:59:59+02:00
fromUpdatedDatestring(date-time)

Filter by subscriptions updated on or after this date

Example: fromUpdatedDate=2025-10-01T00:00:00+02:00
toUpdatedDatestring(date-time)

Filter by subscriptions updated on or before this date

Example: toUpdatedDate=2025-10-31T23:59:59+02:00
fromNextDatestring(date-time)

Filter by subscriptions with next billing date on or after this date. Note: Both fromNextDate and toNextDate must be provided together

Example: fromNextDate=2025-10-01T00:00:00+02:00
toNextDatestring(date-time)

Filter by subscriptions with next billing date on or before this date. Note: Both fromNextDate and toNextDate must be provided together

Example: toNextDate=2025-10-31T23:59:59+02:00
subscriptionContractIdstring

Filter by subscription contract ID (partial match supported, case-insensitive)

Example: subscriptionContractId=123456
customerNamestring

Filter by customer name or email (partial match, case-insensitive). Searches both customer_name and customer_email fields

Example: customerName=john
orderNamestring

Filter by order number (searches current order_name and historical orders in subscription_billing_attempt table, partial match)

Example: orderName=SUB-1001
statusstring

Filter by subscription status (case-insensitive)

Enum"ACTIVE""PAUSED""CANCELLED"
Example: status=ACTIVE
billingPolicyIntervalCountinteger[ 1 .. 365 ]

Filter by delivery interval count (Note: This parameter name is misleading - it actually filters the delivery_policy_interval_count field)

Example: billingPolicyIntervalCount=1
billingPolicyIntervalstring

Filter by delivery interval type (Note: This parameter name is misleading - it actually filters the delivery_policy_interval field)

Enum"DAY""WEEK""MONTH""YEAR"
Example: billingPolicyInterval=MONTH
planTypestring

Filter by plan type classification. 'prepaid' = billing interval count ≠ delivery interval count, 'non-prepaid' = billing interval count = delivery interval count

Enum"prepaid""non-prepaid"
Example: planType=prepaid
recordTypestring

Filter by record type. 'imported' = has imported_id, 'nonImported' = no imported_id

Enum"imported""nonImported"
Example: recordType=imported
productIdinteger(int64)

Filter by product ID (searches within subscription line items JSON). Provide numeric ID only

Example: productId=7890123456
variantIdinteger(int64)

Filter by variant ID (searches within subscription line items JSON). Provide numeric ID only

Example: variantId=42549172011164
sellingPlanIdinteger(int64)

Filter by selling plan ID (searches within subscription line items JSON). Provide numeric ID only

Example: sellingPlanId=123456
minOrderAmountnumber(double)

Filter by minimum total order amount (calculated from sum of line items: quantity * currentPrice)

Example: minOrderAmount=50
maxOrderAmountnumber(double)

Filter by maximum total order amount (calculated from sum of line items: quantity * currentPrice)

Example: maxOrderAmount=500
pageableobject(Pageable)required

Pagination and sorting parameters. IMPORTANT: Sort fields must use database column names (snake_case), not Java field names. Maximum page size is 2000.

Example: pageable=page=0&size=20&sort=next_billing_date,asc&sort=id,desc
pageable.​pageinteger(int32)>= 0
pageable.​sizeinteger(int32)>= 1
pageable.​sortArray of strings
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/subscription-contract-details?fromCreatedDate=2025-10-01T00%3A00%3A00%2B02%3A00&toCreatedDate=2025-10-31T23%3A59%3A59%2B02%3A00&fromUpdatedDate=2025-10-01T00%3A00%3A00%2B02%3A00&toUpdatedDate=2025-10-31T23%3A59%3A59%2B02%3A00&fromNextDate=2025-10-01T00%3A00%3A00%2B02%3A00&toNextDate=2025-10-31T23%3A59%3A59%2B02%3A00&subscriptionContractId=123456&customerName=john&orderName=SUB-1001&status=ACTIVE&billingPolicyIntervalCount=1&billingPolicyInterval=MONTH&planType=prepaid&recordType=imported&productId=7890123456&variantId=42549172011164&sellingPlanId=123456&minOrderAmount=50&maxOrderAmount=500&pageable=page%3D0%26size%3D20%26sort%3Dnext_billing_date%2Casc%26sort%3Did%2Cdesc&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Successfully retrieved subscription contracts

Headers
X-Total-Countinteger

Total number of matching subscription contracts

Example: 150
Linkstring

Pagination navigation links (first, prev, next, last)

Example: "<http://api.example.com/subscription-contract-details?page=2&size=20>; rel=\"next\""
Bodyapplication/jsonArray [
idinteger(int64)
shopstringrequired
graphSubscriptionContractIdstring
subscriptionContractIdinteger(int64)
billingPolicyIntervalstring
billingPolicyIntervalCountinteger(int32)
currencyCodestring
customerIdinteger(int64)
graphCustomerIdstring
deliveryPolicyIntervalstring
deliveryPolicyIntervalCountinteger(int32)
statusstring
graphOrderIdstring
orderIdinteger(int64)
createdAtstring(date-time)
updatedAtstring(date-time)
nextBillingDatestring(date-time)
orderAmountnumber(double)
orderNamestring
customerNamestring
customerEmailstring
subscriptionCreatedEmailSentboolean
endsAtstring(date-time)
startsAtstring(date-time)
subscriptionCreatedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_PAUSED_STATUS"
minCyclesinteger(int32)
maxCyclesinteger(int32)
customerFirstNamestring
customerLastNamestring
autoChargeboolean
importedIdstring
stopUpComingOrderEmailboolean
pausedFromActiveboolean
subscriptionCreatedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_PAUSED_STATUS""PHONE_NUMBER_EMPTY"
phonestring
activatedOnstring(date-time)
pausedOnstring(date-time)
cancelledOnstring(date-time)
contractDetailsJSONstring
deletedVariantIdsstring
cancellationFeedbackstring
orderNotestring
orderNoteAttributesstring
allowDeliveryPriceOverrideboolean
disableFixEmptyQueueboolean
orderAmountUSDnumber(double)
originTypestring
Enum"STORE_FRONT""IMPORTED""SPLIT_ATTEMPT_BILLING""SPLIT_CONTRACT"
originalContractIdinteger(int64)
cancellationNotestring
subscriptionTypestring
Enum"REGULAR_SUBSCRIPTION""BUILD_A_BOX_CLASSIC""BUILD_A_BOX_SINGLE_PRODUCT""BUNDLING_CLASSIC""BUNDLING_MIX_AND_MATCH""SECTIONED_BUNDLE""VOLUME_DISCOUNT"
subscriptionTypeIdentifierstring
upcomingEmailBufferDaysinteger(int32)
upcomingEmailTaskUrlstring
contractAmountnumber(double)
contractAmountUSDnumber(double)
lastSuccessfulOrderstring
totalSuccessfulOrdersinteger(int32)
lifetimeValuenumber(double)
lifetimeValueUSDnumber(double)
allowDeliveryAddressOverrideboolean
billingDateAfterTrialstring(date-time)
pauseReasonstring
pauseFeedbackstring
pauseTillDatestring(date-time)
pauseDurationCycleinteger(int32)
emailBouncedOrFailedboolean
updatingQueueboolean
customerTagstring
queueUpdatedAtstring(date-time)
orderAmountShopCurrencynumber(double)
orderAmountContractCurrencynumber(double)
billingCountryCodestring
deliveryCountryCodestring
]
Response
application/json
[
  {
    "id": 1001,
    "subscriptionContractId": 123456789,
    "graphSubscriptionContractId": "gid://shopify/SubscriptionContract/123456789",
    "status": "active",
    "customerId": 987654321,
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "orderName": "#SUB-1001",
    "nextBillingDate": "2024-04-01T12:00:00.000+00:00",
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 1,
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "totalPrice": 99.99,
    "currencyCode": "USD",
    "createdAt": "2024-01-15T08:00:00.000+00:00",
    "updatedAt": "2024-03-01T14:30:00.000+00:00",
    "contractDetailsJson": [ … ],
    "minCycles": 3,
    "maxCycles": null,
    "activatedOn": "2024-01-15T08:00:00.000+00:00",
    "pausedOn": null,
    "cancelledOn": null,
    "importedId": null
  },
  {
    "id": 1002,
    "subscriptionContractId": 123456790,
    "status": "paused",
    "customerId": 987654322,
    "customerName": "Jane Smith",
    "customerEmail": "jane.smith@example.com",
    "orderName": "#SUB-1002",
    "nextBillingDate": "2024-05-01T12:00:00.000+00:00",
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 3,
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "totalPrice": 149.97,
    "currencyCode": "USD",
    "createdAt": "2024-02-01T10:00:00.000+00:00",
    "updatedAt": "2024-03-10T16:45:00.000+00:00"
  }
]

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