Skip to main content
GET
Retrieve subscription contracts

Headers

X-API-Key
string
required

API Key for authentication

Query Parameters

api_key
string

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

fromCreatedDate
string<date-time>

Filter by subscriptions created on or after this date

toCreatedDate
string<date-time>

Filter by subscriptions created on or before this date

fromUpdatedDate
string<date-time>

Filter by subscriptions updated on or after this date

toUpdatedDate
string<date-time>

Filter by subscriptions updated on or before this date

fromNextDate
string<date-time>

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

toNextDate
string<date-time>

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

subscriptionContractId
string

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

customerName
string

Filter by customer name or email (partial match, case-insensitive). Searches both customerName and customerEmail

orderName
string

Filter by order name (partial match). Matches the contract's checkout order and its renewal orders

status
enum<string>

Filter by subscription status (case-insensitive). Send one full value. A value that matches no status, such as ARCHIVED or ACTIVE,PAUSED, returns an empty list with 200, not an error

Available options:
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED
billingPolicyIntervalCount
integer

Filter by billing interval count (billingPolicyIntervalCount), such as 3 for a plan billed every 3 months

Required range: 1 <= x <= 365
billingPolicyInterval
enum<string>

Filter by billing interval (billingPolicyInterval), case-insensitive

Available options:
DAY,
WEEK,
MONTH,
YEAR
planType
enum<string>

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

Available options:
prepaid,
non-prepaid
recordType
enum<string>

Filter by record type. imported: contracts with an importedId. nonImported: all other contracts

Available options:
imported,
nonImported
productId
integer<int64>

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

variantId
integer<int64>

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

sellingPlanId
integer<int64>

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

minOrderAmount
number<double>

Filter by the contract's minimum line total: the sum of quantity times currentPrice across contractDetailsJSON, before manual and code discounts. It is neither orderAmount nor contractAmount

maxOrderAmount
number<double>

Filter by the contract's maximum line total: the sum of quantity times currentPrice across contractDetailsJSON, before manual and code discounts. It is neither orderAmount nor contractAmount

page
integer
default:0

Zero-based page index (0..N)

Required range: x >= 0
size
integer
default:20

The size of the page to be returned

Required range: x >= 1
sort
string[]

Sort by a field's name in snake_case, then asc or desc, such as next_billing_date,asc or created_at,desc. Repeat sort to sort by more than one field. A camelCase name such as nextBillingDate returns 400.

Response

Successfully retrieved subscription contracts

shop
string
required
activatedOn
string<date-time>
allowDeliveryAddressOverride
boolean
allowDeliveryPriceOverride
boolean
autoCharge
boolean
billingCountryCode
string
billingDateAfterTrial
string<date-time>
billingPolicyInterval
string
billingPolicyIntervalCount
integer<int32>
cancellationFeedback
string
cancellationNote
string
cancelledOn
string<date-time>

When the contract was cancelled. The value stays if the contract is reactivated later, so read status to know whether a contract is cancelled.

contractAmount
number<double>

What the contract bills per renewal now, in currencyCode: the sum of its lines' discountedPrice in contractDetailsJSON (each line's price times quantity, after discounts). Shipping and tax are not included. On a prepaid contract, one renewal pays for every delivery until the next renewal. Appstle recalculates it when the contract is updated, so changes to lines, quantities and prices show up here. It is a floating-point number and can read like 84.60000000000001: round it to the currency's decimals before you show or compare it. For the checkout order, see orderAmount.

contractAmountUSD
number<double>

contractAmount converted to US dollars.

contractDetailsJSON
string

The contract's lines as a JSON string, not an array: parse it before you read it. Each line has productId, variantId, title, variantTitle, sku, quantity, lineId, sellingPlanId and sellingPlanName (empty strings when the line has no selling plan), discountAllocations (the IDs of the discounts on the line), and three prices sent as strings: currentPrice (one unit, per renewal, after the plan's discount; on a prepaid contract it covers every delivery the renewal pays for), discountedPrice (the line total: currentPrice times quantity, after manual and code discounts) and basePrice (one unit before the plan's discount, from pricingPolicy; on a line without pricingPolicy, currentPrice divided by the number of deliveries per renewal). A line can also have pricingPolicy (the plan's discount by cycle) and customAttributes.

createdAt
string<date-time>
currencyCode
string

The three-letter code of the contract's currency. contractAmount and the prices in contractDetailsJSON are in this currency. orderAmount is in the store's currency.

customerEmail
string
customerFirstName
string
customerId
integer<int64>
customerLastName
string
customerName
string
customerTag
string
deletedVariantIds
string
deliveryCountryCode
string
deliveryPolicyInterval
string
deliveryPolicyIntervalCount
integer<int32>
disableFixEmptyQueue
boolean
emailBouncedOrFailed
boolean
endsAt
string<date-time>
graphCustomerId
string
graphOrderId
string
graphSubscriptionContractId
string
id
integer<int64>
importedId
string
lastSuccessfulOrder
string
lifetimeValue
number<double>
lifetimeValueUSD
number<double>
maxCycles
integer<int32>
minCycles
integer<int32>
nextBillingDate
string<date-time>

The date of the contract's next renewal, in ISO 8601 (UTC). A paused or cancelled contract keeps a date here but isn't charged on it, so read it with status. For the next renewal that charges the customer, see nextPaidBillingDate.

nextPaidBillingDate
string<date-time>
orderAmount
number<double>

This subscription's share of the order the customer placed at checkout: its lines' prices after discounts, times quantity, plus their tax when the store's prices don't include tax. Shipping and the order's other items are not included, so each subscription created by one order has its own orderAmount. It is in the store's currency, which can differ from currencyCode, and it is null when the contract has no checkout order (orderName is UNKNOWN). For what the contract bills per renewal now, use contractAmount.

orderAmountContractCurrency
number<double>
orderAmountShopCurrency
number<double>
orderAmountUSD
number<double>
orderId
integer<int64>
orderName
string
orderNote
string
orderNoteAttributes
string
originType
enum<string>
Available options:
STORE_FRONT,
IMPORTED,
SPLIT_ATTEMPT_BILLING,
SPLIT_CONTRACT
originalContractId
integer<int64>
pauseDurationCycle
integer<int32>
pauseFeedback
string
pauseReason
string
pauseTillDate
string<date-time>
pausedFromActive
boolean
pausedOn
string<date-time>
pendingCancellationCycle
integer<int32>
pendingCancellationDate
string<date-time>
phone
string
queueUpdatedAt
string<date-time>
skipPaymentCreateUnpaidOrder
boolean
startsAt
string<date-time>
status
string

The contract's status, in lowercase: active, paused or cancelled. A contract can also be expired or failed, for example one imported with a failed status.

stopUpComingOrderEmail
boolean
subscriptionContractId
integer<int64>
subscriptionCreatedEmailSent
boolean
subscriptionCreatedEmailSentStatus
enum<string>
Available options:
SENT,
UNSENT,
FAILED,
EMAIL_SETTINGS_DISABLED,
CUSTOMER_PAYMENT_EMPTY,
CONTRACT_PAUSED_STATUS
subscriptionCreatedSmsSentStatus
enum<string>
Available options:
SENT,
UNSENT,
FAILED,
SMS_SETTINGS_DISABLED,
CUSTOMER_PAYMENT_EMPTY,
CONTRACT_PAUSED_STATUS,
PHONE_NUMBER_EMPTY
subscriptionType
enum<string>
Available options:
REGULAR_SUBSCRIPTION,
BUILD_A_BOX_CLASSIC,
BUILD_A_BOX_SINGLE_PRODUCT,
BUNDLING_CLASSIC,
BUNDLING_MIX_AND_MATCH,
SECTIONED_BUNDLE,
VOLUME_DISCOUNT
subscriptionTypeIdentifier
string
totalSuccessfulOrders
integer<int32>
upcomingEmailBufferDays
integer<int32>
upcomingEmailTaskUrl
string
updatedAt
string<date-time>
updatingQueue
boolean