Generate customer portal access link by customer ID or email

Key Features:

• Dual Lookup: Find customer by ID or email
• Auto Customer Discovery: Automatically finds customer from email
• Secure Tokens: Encrypted tokens with 2-hour expiration
• Custom Domains: Supports shop’s public domain
• Zero-Auth Access: Customers don’t need passwords

Customer Lookup Logic:

Option 1: By Customer ID (Preferred)

GET /api/external/v2/manage-subscription-link?customerId=12345

• Direct lookup by Shopify customer ID
• Fastest and most reliable method
• No ambiguity

Option 2: By Email

GET /api/external/v2/manage-subscription-link?emailId=customer@example.com

• Searches for customer by email in subscription database
• Finds customer ID automatically
• If not found: Returns error

Validation Rules:

• Either customerId OR emailId must be provided
• Cannot provide both (customerId takes precedence)
• Email must match a customer with subscriptions
• Customer must belong to authenticated shop

Token Generation:

Token Contents:

• Encrypted customer ID
• Shop domain
• Generation timestamp
• Expiration time (2 hours)

Security Features:

• Cryptographically secure encryption
• Cannot be forged or modified
• Automatic expiration after 2 hours
• Single-use recommended (though not enforced)
• Tied to specific shop and customer

Generated URL Structure:

https://[shop-domain]/[manage-subscriptions-path]?token=[encrypted-token]

Example URLs:

https://mystore.com/tools/recurring/customer_portal?token=eyJhbGc...
https://shop.myshopify.com/tools/recurring/customer_portal?token=eyJhbGc...

Use Cases:

1. Email Campaigns:

• Add “Manage Subscription” button to transactional emails
• Include in billing reminder emails
• Send in order confirmation emails
• Add to marketing campaigns

2. Customer Support:

• Provide customers quick portal access
• Avoid “forgot password” issues
• Enable instant self-service
• Reduce support ticket volume

3. Post-Purchase Flows:

• Thank you page portal links
• First order welcome emails
• Onboarding email sequences
• Re-engagement campaigns

4. Account Management:

• SMS notifications with portal links
• Push notification deep links
• Customer dashboard integrations
• Third-party app integrations

Response Format:

{
  "manageSubscriptionLink": "https://mystore.com/tools/recurring/customer_portal?token=eyJhbGciOiJIUzI1NiJ9...",
  "tokenExpirationTime": "2024-03-15T14:30:00Z"
}

Response Fields:

• manageSubscriptionLink: Complete URL ready to use
• tokenExpirationTime: ISO 8601 timestamp when token expires

Integration Examples:

Email Template:

const response = await fetch(
  `/api/external/v2/manage-subscription-link?emailId=${customerEmail}`,
  { headers: { 'X-API-Key': 'your-key' } }
).then(r => r.json());

const emailHtml = `
  <p>Hi ${customerName},</p>
  <p>Manage your subscription:</p>
  <a href="${response.manageSubscriptionLink}">Manage Subscription</a>
  <p><small>Link expires ${formatDate(response.tokenExpirationTime)}</small></p>
`;

SMS Notification:

const { manageSubscriptionLink } = await getPortalLink(customerId);
const shortUrl = await shortenUrl(manageSubscriptionLink);

await sendSMS(customerPhone, 
  `Your subscription ships tomorrow! Manage it here: ${shortUrl}`
);

Important Considerations:

Token Expiration:

• Tokens expire after exactly 2 hours
• Generate new token if expired
• Don’t store tokens long-term
• Best practice: Generate on-demand

Domain Selection:

• Uses shop’s publicDomain if configured
• Falls back to Shopify domain (.myshopify.com)
• Respects custom domain settings
• Maintains brand consistency

Customer Lookup Errors:

• Email not found: Returns 400 error
• Invalid customer ID: Returns error
• No parameters provided: Returns 400
• Both parameters provided: Uses customerId

Security Notes:

• Tokens cannot be used across different shops
• Cannot be used for different customers
• Tampering invalidates token
• Consider rate limiting token generation

Best Practices:

1. Generate On-Demand: Create tokens when needed, not in advance
2. Use HTTPS: Always serve links over HTTPS
3. Show Expiry: Inform customers when link expires
4. URL Shortening: Use URL shorteners for SMS/print materials
5. Track Usage: Monitor which emails drive portal visits
6. Prefer Customer ID: Use customerId when available for faster lookup

Comparison with /manage-subscription-link/:

• This endpoint: Flexible lookup (ID or email)
• Path parameter version: Customer ID only
• Both generate identical tokens
• Use this for email-based flows

Authentication: Requires valid X-API-Key header