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.
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": "customer@example.com",
"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:
- Cache Results: Cache response data to minimize API calls
- Filter Client-Side: Filter/sort subscriptions on client after retrieval
- Selective Display: Don’t display all fields if not needed
- Handle Empty Array: Always gracefully handle case with no subscriptions
- 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)
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body[
{
"billingInterval": "MONTH",
"billingIntervalCount": 1,
"currencyCode": "USD",
"currentCycle": 3,
"currentTotalPrice": "49.99",
"customerEmail": "customer@example.com",
"customerId": 12345,
"deliveryInterval": "MONTH",
"deliveryIntervalCount": 1,
"deliveryMethod": "SHIPPING",
"id": 789,
"nextBillingDate": "2024-03-15T00:00:00Z",
"shop": "example-shop.myshopify.com",
"status": "ACTIVE",
"subscriptionContractId": 5234567890
},
{
"billingInterval": "WEEK",
"billingIntervalCount": 2,
"currencyCode": "USD",
"currentTotalPrice": "24.99",
"customerEmail": "customer@example.com",
"customerId": 12345,
"id": 790,
"status": "PAUSED",
"subscriptionContractId": 5234567891
}
]Response
Successfully retrieved customer subscription details. Returns array of subscription objects (may be empty).
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.
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.
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.
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-customers-detail/valid/{customerId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body[
{
"billingInterval": "MONTH",
"billingIntervalCount": 1,
"currencyCode": "USD",
"currentCycle": 3,
"currentTotalPrice": "49.99",
"customerEmail": "customer@example.com",
"customerId": 12345,
"deliveryInterval": "MONTH",
"deliveryIntervalCount": 1,
"deliveryMethod": "SHIPPING",
"id": 789,
"nextBillingDate": "2024-03-15T00:00:00Z",
"shop": "example-shop.myshopify.com",
"status": "ACTIVE",
"subscriptionContractId": 5234567890
},
{
"billingInterval": "WEEK",
"billingIntervalCount": 2,
"currencyCode": "USD",
"currentTotalPrice": "24.99",
"customerEmail": "customer@example.com",
"customerId": 12345,
"id": 790,
"status": "PAUSED",
"subscriptionContractId": 5234567891
}
]