External (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves comprehensive customer information from Shopify for a specific customer ID. This endpoint fetches the customer record directly from Shopify's API, returning all personal details, addresses, payment methods, and metadata associated with the customer account.

What This Endpoint Returns: Provides a complete Shopify Customer object containing all customer-related data for building customer portals, validating identities, displaying profiles, or integrating with external CRM/analytics systems.

Response Data Structure:

{
  "id": "gid://shopify/Customer/6789012345",
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+1-555-123-4567",
  "displayName": "Jane Smith",
  "defaultAddress": {
    "address1": "123 Main St",
    "city": "San Francisco",
    "province": "CA",
    "zip": "94102",
    "country": "United States"
  },
  "addresses": [...],
  "tags": ["VIP", "Subscriber"],
  "note": "Prefers morning deliveries",
  "state": "ENABLED",
  "createdAt": "2023-01-15T10:30:00Z"
}

Customer Data Fields Returned:

Personal Information:

• id - Shopify global customer ID (format: gid://shopify/Customer/{numeric_id})
• firstName - Customer's first name
• lastName - Customer's last name
• displayName - Full name for display purposes
• email - Primary email address (unique identifier)
• phone - Contact phone number (optional, may be null)

Address Information:

• defaultAddress - Primary shipping/billing address object
  • address1, address2 - Street address lines
  • city, province, zip, country - Location details
  • provinceCode, countryCodeV2 - Standardized codes
  • company - Company name (if B2B customer)
• addresses - Array of all saved addresses (shipping + billing)

Account Status:

• state - Account status: ENABLED, DISABLED, INVITED, DECLINED
• verifiedEmail - Whether email has been verified (boolean)
• taxExempt - Tax exemption status (boolean)
• acceptsMarketing - Email marketing opt-in status

Metadata & Custom Fields:

• tags - Array of customer tags for segmentation
• note - Merchant notes about the customer
• metafields - Custom data fields (if queried)
• numberOfOrders - Total lifetime order count

Timestamps:

• createdAt - When customer account was created
• updatedAt - Last modification timestamp

Common Use Cases & Integration Scenarios:

1. Customer Portal - Profile Display

Use Case: Show customer their account information
1. Get customerId from session/JWT token
2. Call GET /subscription-customers/{customerId}
3. Display: Name, Email, Default Address
4. Show "Edit Profile" button linking to address update endpoint

2. Pre-fill Shipping Address Form

Use Case: Auto-populate address form when updating shipping
1. Fetch customer data via this endpoint
2. Extract defaultAddress object
3. Pre-fill form fields with existing address
4. Allow customer to edit and submit changes

3. Identity Verification Before Critical Actions

Use Case: Verify customer email before canceling subscription
1. User clicks "Cancel Subscription"
2. Fetch customer data
3. Compare session email with customer.email
4. If mismatch: Reject (security violation)
5. If match: Proceed with cancellation

4. CRM Integration / Analytics

Use Case: Sync customer data to external CRM (Salesforce, HubSpot)
1. Webhook triggers on customer update
2. Call this endpoint to get fresh customer data
3. Map fields to CRM schema
4. Push to CRM via their API

5. Customer Segmentation

Use Case: Filter customers by tags for targeted campaigns
1. Fetch customer details
2. Check tags array for "VIP" or "Churned"
3. Apply special pricing or retention offers
4. Customize email communications

Customer ID Format & Validation:

• Input: Numeric Shopify customer ID (e.g., 6789012345)
• Not Accepted: GraphQL global ID format (will cause 400 error)
• Extraction from GraphQL ID: If you have gid://shopify/Customer/6789012345, extract 6789012345
• Example Valid IDs: 123, 456789, 9876543210

Privacy & Security Considerations:

PII Protection:

• This endpoint returns personally identifiable information (PII)
• Ensure compliance with GDPR, CCPA, and privacy regulations
• Only expose customer data to authenticated, authorized users
• Do not log full customer records (contains emails, addresses, phone numbers)

Access Control:

• Customer can only access their own data (enforced by authentication)
• Merchants can access all customers via API key
• Never expose API keys in frontend code
• Use server-to-server calls for merchant access

Data Minimization:

• Only fetch customer data when necessary
• Cache responsibly with short TTL (5-10 minutes max)
• Clear cache on customer updates

Error Handling & Edge Cases:

404 - Customer Not Found:

Reasons:
- Customer ID doesn't exist in Shopify
- Customer was deleted from Shopify admin
- Wrong shop (customer belongs to different store)
- Typo in customer ID

Solution:
- Verify customer ID is correct
- Check if customer exists in Shopify admin
- Ensure shop domain matches customer's store

400 - Invalid Customer ID Format:

Reasons:
- Non-numeric customer ID provided
- Negative number or zero
- GraphQL format instead of numeric ID

Solution:
- Ensure customer ID is positive integer
- Extract numeric portion from GraphQL ID if needed

401 - Authentication Failed:

Reasons:
- Missing API key or customer portal token
- Expired authentication token
- Invalid API key for the shop

Solution:
- Verify X-API-Key header is set
- Regenerate API key if compromised
- Check token expiration

Null/Empty Fields: Some fields may be null/empty if customer hasn't provided data:

• phone - Not all customers provide phone numbers
• addresses - New customers may have empty address list
• defaultAddress - Could be null if no addresses saved
• note - Empty unless merchant added notes
• tags - Empty array if no tags assigned

Always handle null checks in your code.

Performance & Caching Recommendations:

• Response Time: Typically 100-300ms (Shopify GraphQL query)
• Rate Limits: Subject to Shopify API rate limits (40 requests/second)
• Caching: Safe to cache for 5-10 minutes (customer data changes infrequently)
• Optimization: Fetch once per session, store in memory/local state

Related Endpoints:

• /subscription-customers-detail/valid/{customerId} - Gets customer + subscription details
• /subscription-contract-details - Lists all subscriptions for customer
• /customer-payments/token/{customerId} - Get customer payment tokens
• /customer-portal-token - Generate authentication token for customer

Authentication: Requires API key authentication via X-API-Key header or api_key parameter. Customer portal tokens also supported for self-service access.

Retrieves a list of all valid (active, paused, or pending) subscription contract IDs associated with a specific customer. This endpoint is useful for quickly checking which subscriptions a customer has without retrieving full contract details.

Key Features:

• Quick Lookup: Returns only contract IDs, not full contract details
• Active Subscriptions Only: Excludes cancelled or expired contracts
• Set Response: Returns unique contract IDs (no duplicates)
• Fast Performance: Lightweight query for list views

Included Subscription Statuses:

• ACTIVE: Currently active recurring subscriptions
• PAUSED: Temporarily paused but valid subscriptions
• PENDING: Scheduled to start in the future

Excluded Subscription Statuses:

• CANCELLED: Customer-cancelled subscriptions
• EXPIRED: Reached max cycles or end date
• FAILED: Failed billing with no recovery

Common Use Cases:

• Subscription Count: Quickly determine how many active subscriptions a customer has
• Access Control: Verify customer has valid subscriptions before showing portal
• List Navigation: Build dropdown or list of customer's subscriptions
• Bulk Operations: Get all contract IDs for batch processing
• Validation: Check if customer has any active memberships
• Dashboard Display: Show subscription count without full data

Example Response:

[12345, 12346, 12389]

Parameters:

• customerId (required, path): The Shopify customer ID

Response: Returns a Set of Long values representing valid subscription contract IDs

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Retrieves comprehensive details for all subscription contracts associated with a specific customer. This endpoint returns complete subscription contract data including products, pricing, billing schedule, and status.

Key Information Returned:

• Contract Details: Contract ID, status (active, paused, cancelled), creation date
• Products: Line items with product names, variants, quantities, and prices
• Billing Information: Next billing date, billing frequency, payment method
• Delivery Details: Shipping address, delivery method, delivery frequency
• Pricing: Subtotal, discounts applied, total amount per cycle
• Membership Plan: Associated subscription plan name and details
• Order History: Past billing attempts and fulfillment records

Subscription Contract Details Include:

• Contract ID: Unique identifier for the subscription
• Customer ID: Shopify customer ID associated with the contract
• Status: ACTIVE, PAUSED, CANCELLED, EXPIRED
• Billing Cycle: Number of completed billing cycles
• Next Billing Date: When the next payment will be charged
• Delivery Date: When the next order will be shipped
• Products: All line items in the subscription with pricing
• Discount Codes: Applied discount codes and their values
• Custom Attributes: Any custom metadata or tags

Common Use Cases:

• Display full subscription list in customer account dashboard
• Retrieve all contract details for customer support inquiries
• Build custom customer portal with subscription management
• Sync subscription data to external CRM or analytics systems
• Generate customer subscription reports and analytics
• Validate customer's active subscriptions before offering upgrades
• Show subscription history and upcoming deliveries

Response Format: Returns a List of SubscriptionContractDetailsDTO objects, one per active/paused contract. If customer has no subscriptions, returns an empty list.

Authentication: Requires API key authentication via X-API-Key header or api_key parameter