> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. **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:** 1. **Data Retrieval**: Fetches customer subscription data from Shopify using their GraphQL API 2. **Validation**: Validates the retrieved data against existing records 3. **Update**: Updates customer subscription details in Appstle database 4. **Reconciliation**: Reconciles any discrepancies between Shopify and Appstle data 5. **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:** 1. **Use Sparingly**: Rely on webhooks for automatic sync; use this only when needed 2. **Check Logs**: Review activity logs after sync to verify changes 3. **Validate Results**: Query customer data after sync to confirm updates 4. **Handle Errors**: Implement retry logic with exponential backoff 5. **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) ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-customers/sync-info/{customerId} openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/subscription-customers/sync-info/{customerId}: get: tags: - Customers - Subscription Contracts summary: Sync customer subscription details from Shopify description: >- 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. **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:** 1. **Data Retrieval**: Fetches customer subscription data from Shopify using their GraphQL API 2. **Validation**: Validates the retrieved data against existing records 3. **Update**: Updates customer subscription details in Appstle database 4. **Reconciliation**: Reconciles any discrepancies between Shopify and Appstle data 5. **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:** 1. **Use Sparingly**: Rely on webhooks for automatic sync; use this only when needed 2. **Check Logs**: Review activity logs after sync to verify changes 3. **Validate Results**: Query customer data after sync to confirm updates 4. **Handle Errors**: Implement retry logic with exponential backoff 5. **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) operationId: syncCustomerInfo parameters: - description: Customer Id in: path name: customerId required: true schema: format: int64 type: integer - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string responses: '204': content: application/json: {} description: >- Customer subscription data successfully synchronized from Shopify. No response body returned. Check activity logs to verify sync completion and review changes made. '400': content: application/json: example: detail: Customer ID must be a valid positive integer status: 400 title: Invalid request type: https://example.com/errors/bad-request description: Bad request - Invalid customer ID or malformed request parameters '401': content: application/json: example: detail: Valid X-API-Key header is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required - Missing or invalid API key '403': content: application/json: example: detail: >- Customer does not belong to your shop or API key lacks required permissions status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: >- Insufficient permissions or customer does not belong to authenticated shop '404': content: application/json: example: detail: No customer found with ID 12345 in Shopify status: 404 title: Customer not found type: https://example.com/errors/not-found description: Customer not found in Shopify or has no subscriptions '429': content: application/json: example: detail: >- Shopify API rate limit exceeded. Please retry after 60 seconds. retryAfter: 60 status: 429 title: Rate limit exceeded type: https://example.com/errors/rate-limit description: >- Rate limit exceeded - Too many sync requests or Shopify API rate limit hit '502': content: application/json: example: detail: Failed to connect to Shopify API. Please try again later. status: 502 title: Shopify API error type: https://example.com/errors/bad-gateway description: Bad gateway - Shopify API error or connection failure '504': content: application/json: example: detail: >- Sync operation timed out. Customer may have too many subscriptions. Please contact support for manual sync. status: 504 title: Sync timeout type: https://example.com/errors/timeout description: >- Gateway timeout - Sync operation took too long (customer has too many subscriptions) ````