Get valid subscription contract IDs for a customer

Retrieves a set of all valid (active, paused, or otherwise non-deleted) subscription contract IDs for a specific customer. This endpoint returns only the contract IDs without detailed subscription information, making it ideal for quick lookups and validation checks.

What Are Valid Subscription Contracts? Valid contracts are subscriptions that exist in the system and haven’t been permanently deleted. This includes subscriptions in all states except those that have been hard-deleted or hidden from the system. The contract IDs returned represent subscriptions that can be queried, modified, or managed through other API endpoints.

Contract States Included:

Active States:

• ACTIVE - Currently active and billing recurring subscriptions
• PAUSED - Temporarily paused subscriptions (customer can resume)

Inactive States:

• CANCELLED - Cancelled subscriptions (retained for historical data)
• EXPIRED - Subscriptions that reached their max cycle limit
• FAILED - Subscriptions with payment failures (may be in dunning)

Excluded:

• Hard-deleted subscription records
• Hidden subscriptions (marked for cleanup)
• Subscriptions from test/development that were purged

Use Cases:

1. Customer Portal:

• Check if customer has any subscriptions before showing portal
• Display subscription count in dashboard
• Validate customer access to subscription management

2. Integration & Automation:

• Pre-flight check before bulk operations
• Verify customer has subscriptions before sending emails
• Filter customers for targeted campaigns (has active subscriptions)

3. Validation & Security:

• Verify a specific contract ID belongs to a customer
• Validate user permissions before showing subscription details
• Check authorization for subscription modification requests

4. Analytics & Reporting:

• Count total subscriptions per customer
• Identify customers with multiple subscriptions
• Build customer segmentation based on subscription count

Response Format:

Returns a Set<Long> containing Shopify subscription contract IDs.

[123456789, 123456790, 123456791]

Set Properties:

• Unique values: No duplicate contract IDs
• Unordered: IDs are not in any specific order
• Numeric: IDs are Long integers (not GraphQL GIDs)

Common Response Scenarios:

Customer with multiple subscriptions:

[5234567890, 5234567891, 5234567892, 5234567893]

Customer with single subscription:

[5234567890]

Customer with no subscriptions:

[]

Integration Examples:

Example 1: Check if customer has subscriptions

const contractIds = await fetch('/api/external/v2/subscription-customers/valid/12345', {
  headers: { 'X-API-Key': 'your-api-key' }
}).then(r => r.json());

if (contractIds.length > 0) {
  console.log(`Customer has ${contractIds.length} subscriptions`);
  // Show customer portal
} else {
  console.log('Customer has no subscriptions');
  // Redirect to create subscription page
}

Example 2: Validate contract ownership

const customerId = 12345;
const contractIdToVerify = 5234567890;

const validContracts = await fetch(`/api/external/v2/subscription-customers/valid/${customerId}`, {
  headers: { 'X-API-Key': 'your-api-key' }
}).then(r => r.json());

if (validContracts.includes(contractIdToVerify)) {
  console.log('Customer owns this contract - allowing access');
  // Proceed with subscription modification
} else {
  console.log('Unauthorized - contract does not belong to customer');
  // Return 403 Forbidden
}

Performance Characteristics:

Fast Response:

• Lightweight query (returns only IDs, not full subscription data)
• Typical response time: 50-200ms
• Suitable for real-time validation checks

Scalability:

• Efficient even for customers with 100+ subscriptions
• Database query uses indexed customer ID field
• Minimal network payload (just array of numbers)

Important Notes:

Contract ID Format:

• Returns numeric Shopify contract IDs (e.g., 5234567890)
• NOT Shopify GraphQL GIDs (e.g., gid://shopify/SubscriptionContract/...)
• Use these IDs with other Appstle API endpoints

Data Freshness:

• Returns data from Appstle database (not real-time Shopify query)
• Data is updated via webhooks (typically < 1 second lag)
• If data seems stale, use sync endpoint to refresh

Empty Response:

• Empty array [] means customer has no valid subscriptions
• This is NOT an error - it’s a valid response
• Returns 200 OK with empty array (not 404)

Security & Authorization:

• Customer ID is validated against authenticated shop
• Cannot query customers from other shops
• API key must have customer read permissions

Best Practices:

1. Use for Validation: Perfect for quick ownership/existence checks
2. Cache Locally: Cache results briefly to reduce API calls
3. Check Empty Array: Always handle empty array case gracefully
4. Combine with Details: Use this for initial check, then fetch full details if needed
5. Avoid Polling: Don’t poll this endpoint repeatedly - use webhooks for updates

When to Use vs. Other Endpoints:

Use this endpoint when you:

• Need just the contract IDs (not full subscription details)
• Want to validate a customer has subscriptions
• Need to verify contract ownership for authorization
• Want fast, lightweight responses

Use subscription-customers-detail endpoint when you:

• Need full subscription details (status, products, billing dates, etc.)
• Want to display subscription information to users
• Need to make decisions based on subscription state

Related Endpoints:

• GET /api/external/v2/subscription-customers-detail/valid/{customerId} - Get full subscription details
• GET /api/external/v2/subscription-contract-details - Query subscriptions with filters
• GET /api/external/v2/subscription-contracts/contract-external/{contractId} - Get single contract details

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