Customers

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:

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)

GET

api

external

subscription-customers

sync-info

{customerId}

Sync customer subscription details from Shopify

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

const options = {method: 'GET'};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-customers/sync-info/{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/sync-info/{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/sync-info/{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/sync-info/{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/sync-info/{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

{
  "detail": "Customer ID must be a valid positive integer",
  "status": 400,
  "title": "Invalid request",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "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"
}

{
  "detail": "No customer found with ID 12345 in Shopify",
  "status": 404,
  "title": "Customer not found",
  "type": "https://example.com/errors/not-found"
}

{
  "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"
}

{
  "detail": "Failed to connect to Shopify API. Please try again later.",
  "status": 502,
  "title": "Shopify API error",
  "type": "https://example.com/errors/bad-gateway"
}

{
  "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"
}

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

Customer subscription data successfully synchronized from Shopify. No response body returned. Check activity logs to verify sync completion and review changes made.

Sync customer subscription details from Shopify

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

const options = {method: 'GET'};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-customers/sync-info/{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/sync-info/{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/sync-info/{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/sync-info/{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/sync-info/{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

{
  "detail": "Customer ID must be a valid positive integer",
  "status": 400,
  "title": "Invalid request",
  "type": "https://example.com/errors/bad-request"
}

{
  "detail": "Valid X-API-Key header is required",
  "status": 401,
  "title": "Authentication required",
  "type": "https://example.com/errors/unauthorized"
}

{
  "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"
}

{
  "detail": "No customer found with ID 12345 in Shopify",
  "status": 404,
  "title": "Customer not found",
  "type": "https://example.com/errors/not-found"
}

{
  "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"
}

{
  "detail": "Failed to connect to Shopify API. Please try again later.",
  "status": 502,
  "title": "Shopify API error",
  "type": "https://example.com/errors/bad-gateway"
}

{
  "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"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Sync customer subscription details from Shopify

Headers

Path Parameters

Query Parameters

Response