# 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.

Endpoint: GET /api/external/v2/subscription-customers/{customerId}
Version: 0.0.1

## Path parameters:

  - `customerId` (integer, required)
    Shopify customer ID
    Example: 6789012345

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

## Header parameters:

  - `X-API-Key` (string)

## Response 200 fields (application/json):

  - `get__typename` (string)

  - `id` (string)

  - `displayName` (string)

  - `firstName` (string)

  - `lastName` (string)

  - `email` (string)

  - `phone` (string)

## Response 400 fields (*/*):

  - `get__typename` (string)

  - `id` (string)

  - `displayName` (string)

  - `firstName` (string)

  - `lastName` (string)

  - `email` (string)

  - `phone` (string)

## Response 401 fields (*/*):

  - `get__typename` (string)

  - `id` (string)

  - `displayName` (string)

  - `firstName` (string)

  - `lastName` (string)

  - `email` (string)

  - `phone` (string)

## Response 404 fields (*/*):

  - `get__typename` (string)

  - `id` (string)

  - `displayName` (string)

  - `firstName` (string)

  - `lastName` (string)

  - `email` (string)

  - `phone` (string)

## Response 500 fields (*/*):

  - `get__typename` (string)

  - `id` (string)

  - `displayName` (string)

  - `firstName` (string)

  - `lastName` (string)

  - `email` (string)

  - `phone` (string)