Get detailed subscription information for a customer

Retrieves comprehensive subscription contract details for a specific customer, including subscription status, products, billing information, delivery schedules, and more. This endpoint returns full subscription objects with all associated data, making it ideal for displaying subscription management interfaces and detailed analytics.

Full behavior, validation rules, and side effects

What This Endpoint Returns: Unlike the contract IDs endpoint which returns only numeric IDs, this endpoint provides complete SubscriptionContractDetailsDTO objects for each of the customer’s subscriptions. Each object contains all information needed to display and manage a subscription.

Data Included in Response:

Subscription Identity:

• Subscription contract ID (Shopify numeric ID)
• Subscription GraphQL ID (Shopify GID format)
• Internal Appstle database ID
• Contract creation date

Subscription Status & Lifecycle:

• Current status (ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED)
• Status reason (why paused/cancelled)
• Next billing date and time
• Contract anchor date
• Cancellation date (if applicable)
• Current billing cycle number
• Min/max cycle limits

Billing Configuration:

• Billing interval (WEEK, MONTH, YEAR)
• Billing interval count (e.g., every 2 weeks)
• Billing policy (pricing details)
• Currency code
• Recurring total price
• Applied discounts and pricing policies

Delivery Configuration:

• Delivery interval (WEEK, MONTH, YEAR)
• Delivery interval count
• Delivery method (SHIPPING, PICK_UP, LOCAL_DELIVERY)
• Delivery policy details
• Delivery price

Products & Line Items:

• All subscribed products and variants
• Product titles, SKUs, and images
• Quantities per product
• Individual line item prices
• Product-specific discounts
• Line item attributes and custom fields

Customer Information:

• Customer ID and GraphQL ID
• Customer name and email
• Customer acceptance status

Address Details:

• Billing address (full address object)
• Shipping address (full address object)
• Address validation status

Payment Information:

• Payment instrument type
• Payment method details (card last 4, etc.)
• Payment gateway used

Order & Fulfillment:

• Last order ID and details
• Last order date
• Order note
• Fulfillment status

Additional Metadata:

• Custom note attributes
• Tags and labels
• Internal flags and settings
• Selling plan ID and group ID
• Shop domain

Use Cases:

1. Customer Portal:

• Display all subscriptions on customer dashboard
• Show subscription details page
• Enable subscription management actions
• Display upcoming order information

2. Admin Dashboard:

• View customer’s complete subscription portfolio
• Analyze subscription health and status
• Identify at-risk or high-value subscriptions
• Generate customer subscription reports

3. Customer Support:

• Quick access to all customer subscription details
• Troubleshoot billing or delivery issues
• Verify subscription configurations
• Assist with subscription modifications

4. Analytics & Reporting:

• Calculate customer lifetime value
• Analyze subscription mix per customer
• Track subscription frequency distribution
• Identify cross-sell/upsell opportunities

5. Integration & Automation:

• Sync subscription data to CRM/analytics platforms
• Trigger workflows based on subscription details
• Build custom reporting dashboards
• Export subscription data for analysis

Response Format:

Returns an array of SubscriptionContractDetailsDTO objects:

[
  {
    "id": 789,
    "subscriptionContractId": 5234567890,
    "status": "ACTIVE",
    "nextBillingDate": "2024-03-15T00:00:00Z",
    "billingInterval": "MONTH",
    "billingIntervalCount": 1,
    "deliveryInterval": "MONTH",
    "deliveryIntervalCount": 1,
    "currencyCode": "USD",
    "currentTotalPrice": "49.99",
    "customerId": 12345,
    "customerEmail": "[e-mail]",
    "lineItems": [...],
    "billingAddress": {...},
    "shippingAddress": {...}
  },
  {...}
]

Response Scenarios:

Customer with no subscriptions:

[]

Returns empty array with 200 OK status (not an error).

Customer with multiple subscriptions: Array contains multiple subscription objects, each representing a separate subscription contract.

Performance Considerations:

Response Size:

• Each subscription object can be 5-50 KB depending on line items
• Customer with 10 subscriptions: ~100-500 KB response
• Consider pagination or filtering for customers with 20+ subscriptions

Query Performance:

• Typical response time: 200-500ms
• Slower for customers with many subscriptions or complex products
• Database query is optimized with indexed lookups

Best Practices:

1. Cache Results: Cache response data to minimize API calls
2. Filter Client-Side: Filter/sort subscriptions on client after retrieval
3. Selective Display: Don’t display all fields if not needed
4. Handle Empty Array: Always gracefully handle case with no subscriptions
5. Optimize Images: Product images can be large - lazy load if displaying

Data Freshness:

• Data is retrieved from Appstle database (not real-time Shopify query)
• Updated via webhooks with < 1 second lag typically
• Use sync endpoint if data appears stale

Security Notes:

• Customer ID is validated against authenticated shop
• Returns only subscriptions belonging to specified customer
• Cannot access customers from other shops
• Sensitive payment details (full card numbers) are never returned

Comparison with Other Endpoints:

vs. GET /subscription-customers/valid/:

• This endpoint: Returns complete subscription details
• Valid contracts endpoint: Returns only contract IDs
• Use this when you need full subscription information

vs. GET /subscription-contract-details:

• This endpoint: Filtered by single customer
• Contract details endpoint: Query across all customers with filters
• Use this for customer-specific views

vs. GET /subscription-contracts/contract-external/:

• This endpoint: All contracts for a customer
• Contract external endpoint: Single contract with Shopify raw data
• Use this for customer overview, other for detailed single contract

Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)

GET /api/external/v2/subscription-customers-detail/valid/{customerId}

Get detailed subscription information for a customer

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}

200

Customer with active subscriptions

[
  {
    "id": 789,
    "subscriptionContractId": 5234567890,
    "status": "ACTIVE",
    "nextBillingDate": "2024-03-15T00:00:00Z",
    "billingInterval": "MONTH",
    "billingIntervalCount": 1,
    "deliveryInterval": "MONTH",
    "deliveryIntervalCount": 1,
    "currencyCode": "USD",
    "currentTotalPrice": "49.99",
    "customerId": 12345,
    "customerEmail": "[e-mail]",
    "shop": "example-shop.myshopify.com",
    "currentCycle": 3,
    "deliveryMethod": "SHIPPING"
  },
  {
    "id": 790,
    "subscriptionContractId": 5234567891,
    "status": "PAUSED",
    "billingInterval": "WEEK",
    "billingIntervalCount": 2,
    "currencyCode": "USD",
    "currentTotalPrice": "24.99",
    "customerId": 12345,
    "customerEmail": "[e-mail]"
  }
]

Headers

X-API-Key · string

Path Parameters

customerId · integer<int64> · required

Customer Id

Query Parameters

api_key · string

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

Response

200

application/json

Successfully retrieved customer subscription details. Returns array of subscription objects (may be empty).

shop · string · required

id · integer<int64>

graphSubscriptionContractId · string

subscriptionContractId · integer<int64>

billingPolicyInterval · string

billingPolicyIntervalCount · integer<int32>

currencyCode · string

customerId · integer<int64>

graphCustomerId · string

deliveryPolicyInterval · string

deliveryPolicyIntervalCount · integer<int32>

status · string

graphOrderId · string

orderId · integer<int64>

createdAt · string<date-time>

updatedAt · string<date-time>

nextBillingDate · string<date-time>

orderAmount · number<double>

orderName · string

customerName · string

customerEmail · string

subscriptionCreatedEmailSent · boolean

endsAt · string<date-time>

startsAt · string<date-time>

subscriptionCreatedEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_PAUSED_STATUS

minCycles · integer<int32>

maxCycles · integer<int32>

customerFirstName · string

customerLastName · string

autoCharge · boolean

importedId · string

stopUpComingOrderEmail · boolean

pausedFromActive · boolean

skipPaymentCreateUnpaidOrder · boolean

subscriptionCreatedSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_PAUSED_STATUS, PHONE_NUMBER_EMPTY

phone · string

activatedOn · string<date-time>

pausedOn · string<date-time>

cancelledOn · string<date-time>

contractDetailsJSON · string

deletedVariantIds · string

cancellationFeedback · string

orderNote · string

orderNoteAttributes · string

allowDeliveryPriceOverride · boolean

disableFixEmptyQueue · boolean

orderAmountUSD · number<double>

originType · enum<string>

Available options: STORE_FRONT, IMPORTED, SPLIT_ATTEMPT_BILLING, SPLIT_CONTRACT

originalContractId · integer<int64>

cancellationNote · string

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

upcomingEmailBufferDays · integer<int32>

upcomingEmailTaskUrl · string

contractAmount · number<double>

contractAmountUSD · number<double>

lastSuccessfulOrder · string

totalSuccessfulOrders · integer<int32>

lifetimeValue · number<double>

lifetimeValueUSD · number<double>

allowDeliveryAddressOverride · boolean

billingDateAfterTrial · string<date-time>

pauseReason · string

pauseFeedback · string

pauseTillDate · string<date-time>

pauseDurationCycle · integer<int32>

pendingCancellationCycle · integer<int32>

pendingCancellationDate · string<date-time>

emailBouncedOrFailed · boolean

updatingQueue · boolean

customerTag · string

queueUpdatedAt · string<date-time>

orderAmountShopCurrency · number<double>

orderAmountContractCurrency · number<double>

billingCountryCode · string

deliveryCountryCode · string

nextPaidBillingDate · string<date-time>