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

Replaces an existing product variant with a new variant in a subscription contract. This allows customers to swap products in their membership while maintaining their subscription.

Key Features:

• Product Swapping: Replace any line item's variant with a different variant
• Quantity Preservation: Maintains the same quantity after variant swap
• Price Updates: New variant pricing is applied automatically
• Flexible Identification: Identify old variant by lineId OR variantId
• Activity Logging: All variant changes are logged for audit trail

Identification Methods: You can identify the old variant using either:

• oldLineId: The Shopify line item ID from the subscription contract
• oldVariantId: The Shopify product variant ID At least one of these must be provided.

Common Use Cases:

• Customer wants to change product flavor/color/size in their membership
• Swap discontinued products with new alternatives
• Change product preferences mid-subscription
• Update seasonal product selections
• Replace out-of-stock variants with alternatives

Important Notes:

• Immediate Effect: Variant change applies to the next billing cycle
• Validation: System validates new variant exists and is available
• Same Product: Old and new variants can be from different products
• Price Changes: Customer is charged the new variant's price

Variant ID Format:

• Accepts both numeric IDs and GraphQL IDs (gid://shopify/ProductVariant/...)
• System automatically converts to correct format

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

Adds a new product (line item) to an existing subscription contract. This allows customers or merchants to add products to their recurring subscription orders.

Key Features:

• Add Products: Include new products in future subscription deliveries
• Quantity Control: Specify how many units of the product to add
• Price Override: Set custom pricing for the added product
• Immediate Effect: Changes apply to next billing cycle
• Activity Logging: All additions are tracked in activity logs

Required Parameters:

• contractId: Subscription contract ID to modify
• variantId: Shopify product variant ID (with gid:// prefix or numeric)
• quantity: Number of units to add (must be positive integer)
• price: Price per unit in shop's base currency

Product Variant ID Format: Accepts two formats:

• Shopify GID: gid://shopify/ProductVariant/12345678901
• Numeric ID: 12345678901

Price Behavior:

• Price is per unit, not total
• Must be in shop's base currency (USD, EUR, etc.)
• Can override product's default price
• Does not include taxes or shipping
• Total line item cost = price × quantity

Line Item Addition Rules:

• Product variant must exist in Shopify catalog
• Product must be active and available
• Variant must have sufficient inventory (if tracked)
• Contract must be ACTIVE or PAUSED (not CANCELLED)
• Cannot add duplicate variants (use update quantity instead)

Common Use Cases:

• Customer adds complementary product to existing subscription
• Upsell additional products through customer portal
• Merchant adds bonus items to customer subscriptions
• Build custom "add-on" product selection interfaces
• Cross-sell related products to existing subscribers
• Create bundle upgrades (add multiple products at once)

Post-Addition Effects:

• Next billing amount increases by (price × quantity)
• Product appears in all future subscription deliveries
• Customer receives confirmation of subscription update
• Activity log records the addition with source (portal/merchant)
• Contract's next billing date remains unchanged

Integration Example:

PUT /api/external/v2/subscription-contract-add-line-item?
  contractId=123456&
  variantId=gid://shopify/ProductVariant/987654321&
  quantity=2&
  price=19.99

This adds 2 units of variant 987654321 at $19.99 each ($39.98 total) to contract 123456.

Important Notes:

• Changes apply to NEXT billing cycle, not current/past orders
• If product is out of stock, order may be delayed or skipped
• Price changes don't affect historical orders
• Consider inventory availability before adding products

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

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.