Sync customer subscription details from Shopify
Synchronizes customer subscription information from Shopify to the Appstle subscription system. This endpoint fetches the latest customer data from Shopify and updates the local database to ensure data consistency across platforms.
Full behavior, validation rules, and side effects
What Does This Endpoint Do? This endpoint triggers a synchronization process that pulls customer subscription data from Shopify’s GraphQL API and updates the Appstle subscription database with the latest information. It ensures that customer details, subscription statuses, and associated metadata are current and accurate.
Sync Process:
- Data Retrieval: Fetches customer subscription data from Shopify using their GraphQL API
- Validation: Validates the retrieved data against existing records
- Update: Updates customer subscription details in Appstle database
- Reconciliation: Reconciles any discrepancies between Shopify and Appstle data
- Logging: Logs all sync activities for audit trail
What Gets Synchronized:
Customer Information:
- Customer ID and Shopify GraphQL ID
- Customer name and email address
- Customer tags and metadata
- Customer acceptance status
- Marketing preferences
Subscription Details:
- Active subscription contracts
- Subscription statuses (ACTIVE, PAUSED, CANCELLED, EXPIRED)
- Next billing dates
- Billing interval and delivery interval
- Subscription line items (products and variants)
- Pricing and discounts
Payment Information:
- Associated payment methods
- Payment instrument status
- Billing address details
Delivery Information:
- Shipping address details
- Delivery method and profile
- Delivery preferences
Use Cases:
1. Data Consistency:
- Resolve data discrepancies between Shopify and Appstle
- Update customer information after changes in Shopify admin
- Sync subscription modifications made directly in Shopify
2. Troubleshooting:
- Fix sync issues for specific customers
- Recover from webhook delivery failures
- Debug customer portal display issues
3. Migration & Integration:
- Initial data sync after app installation
- Re-sync after system maintenance or updates
- Integration testing and validation
4. Customer Support:
- Refresh customer data when assisting with support tickets
- Verify latest subscription status during customer inquiries
- Update data after manual changes in Shopify
When to Use This Endpoint:
Recommended Scenarios:
- Customer reports incorrect subscription data in portal
- After making manual changes to subscriptions in Shopify admin
- When troubleshooting webhook sync failures
- Before running bulk operations on customer subscriptions
- During migration or data reconciliation processes
Avoid Using For:
- Real-time data refresh (webhooks handle this automatically)
- Frequent polling (use webhooks instead to avoid rate limits)
- Bulk syncs of many customers (use batch endpoints or scheduled jobs)
Sync Behavior:
Synchronous Operation:
- Endpoint blocks until sync completes
- Returns void on success
- Throws exception on failure
Data Precedence:
- Shopify data is always treated as source of truth
- Local Appstle data is overwritten with Shopify values
- Custom Appstle-specific fields are preserved
Error Handling:
- Invalid customer ID: Returns 400 Bad Request
- Customer not found in Shopify: Returns 404 Not Found
- Shopify API errors: Returns 502 Bad Gateway
- Rate limit exceeded: Returns 429 Too Many Requests
Important Considerations:
Performance:
- Sync duration depends on number of subscriptions (typically 1-5 seconds)
- May timeout for customers with 100+ active subscriptions
- Consider using asynchronous sync for high-volume customers
Rate Limiting:
- Subject to Shopify GraphQL API rate limits
- Frequent calls may exhaust rate limit budget
- Use webhooks for real-time sync instead of polling this endpoint
Data Integrity:
- Always creates audit log entries for tracking
- Preserves historical data and activity logs
- Does not delete local-only data (e.g., custom notes)
Best Practices:
- Use Sparingly: Rely on webhooks for automatic sync; use this only when needed
- Check Logs: Review activity logs after sync to verify changes
- Validate Results: Query customer data after sync to confirm updates
- Handle Errors: Implement retry logic with exponential backoff
- Monitor Rate Limits: Track Shopify API usage to avoid hitting limits
Security Notes:
- Requires valid API key authentication via X-API-Key header
- Customer ID is validated against shop ownership
- Cannot sync customers from other shops
- All sync operations are logged for audit compliance
Response:
- Returns HTTP 204 No Content on successful sync
- No response body returned
- Check activity logs for detailed sync results
Alternative Approaches:
If you need to:
- Sync multiple customers: Use bulk sync endpoint or scheduled job
- Real-time updates: Rely on webhook subscriptions
- Verify data without modifying: Use GET endpoints to retrieve current data
Integration Workflow Example:
1. Customer contacts support about incorrect billing date
2. Support agent checks subscription in Appstle admin
3. Agent makes correction in Shopify admin
4. Agent calls sync endpoint for this customer
5. Sync retrieves latest data from Shopify
6. Appstle database is updated with corrected billing date
7. Customer portal now shows correct date
8. Support ticket resolved
Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)
Documentation Index
Fetch the complete documentation index at: https://appstleinc-aeca3e0a.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Headers
Path Parameters
Customer Id
Query Parameters
API Key (Deprecated - Use Header X-API-Key instead)
Response
Customer subscription data successfully synchronized from Shopify. No response body returned. Check activity logs to verify sync completion and review changes made.