> ## 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. # Get subscription customer details > 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:** ```json { "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. ## OpenAPI ````yaml /memberships/admin-api-swagger.json get /api/external/v2/subscription-customers/{customerId} openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing memberships, payments, and related operations. These APIs allow you to programmatically manage membership lifecycles, handle payments, configure products, and integrate membership functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://membership-admin.appstle.com security: [] tags: - description: >- APIs for managing Shopify delivery profiles, shipping rates, zones, and free shipping configuration for subscription memberships name: Shipping & Delivery Profiles - description: >- APIs for retrieving historical discount code usage and redemption information for membership contracts name: Customer Discount History - description: >- APIs for managing membership cancellation flow settings including retention offers, survey questions, and cancel confirmation screens name: Cancellation Flow Configuration - description: >- APIs for managing membership billing attempts, recurring orders, payment retries, order history, and order skipping name: Billing & Orders - description: >- APIs for managing one-time product additions to upcoming subscription orders, including adding, retrieving, and removing one-off items name: One-Time Add-Ons - description: >- APIs for managing membership/subscription plan groups, including creating plans, configuring discounts, billing intervals, and assigning products to plans name: Membership Plans - description: >- APIs for managing subscription product bundles, bundle configurations, item grouping, and bundle-specific discount codes name: Product Bundles - description: >- APIs for retrieving custom CSS styles applied to subscription widgets and customer portal for theme customization name: Custom CSS Styling - description: >- APIs for managing customer portal settings including UI customization, text labels, feature toggles, and branding options for the member self-service portal name: Customer Portal Configuration - description: >- APIs for managing membership/subscription contracts including creation, updates, status changes, line items, discounts, and billing operations name: Membership Contracts - description: >- APIs for managing subscription bundle configuration settings including bundle behavior, pricing rules, and display options name: Bundle Settings - description: >- APIs for managing customer payment methods, payment tokens, and payment method retrieval for subscriptions name: Customer Payment Methods - description: >- APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups name: Product Swap Rules - description: >- APIs for retrieving product catalog, variants, pricing, and inventory information for subscription memberships. name: Product & Inventory Data - description: >- APIs for managing shop-level membership settings, configuration, and general store information. name: Shop Settings - description: >- APIs for performing bulk/mass operations on multiple membership contracts including status updates, product replacements, and billing date changes. name: Bulk Operations paths: /api/external/v2/subscription-customers/{customerId}: get: tags: - Membership Contracts summary: Get subscription customer details description: >- 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:** ```json { "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. operationId: getSubscriptionCustomerV2 parameters: - description: Shopify customer ID example: 6789012345 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: '200': content: application/json: schema: $ref: '#/components/schemas/Customer' description: >- Customer details retrieved successfully. Returns full Shopify Customer object with all fields populated. '400': content: '*/*': schema: $ref: '#/components/schemas/Customer' description: >- Bad request - invalid customer ID format (must be numeric positive integer, not GraphQL global ID) '401': content: '*/*': schema: $ref: '#/components/schemas/Customer' description: >- Authentication required - invalid or missing API key / customer portal token '404': content: '*/*': schema: $ref: '#/components/schemas/Customer' description: >- Customer not found - customer ID doesn't exist, was deleted, or belongs to different shop '500': content: '*/*': schema: $ref: '#/components/schemas/Customer' description: >- Internal server error - Shopify API unavailable or query timeout. Retry after brief delay. components: schemas: Customer: properties: displayName: type: string email: deprecated: true type: string firstName: type: string get__typename: type: string id: type: string lastName: type: string phone: deprecated: true type: string type: object ````