External APIs (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

Generates a secure, time-limited authentication token that grants access to the customer portal. Supports lookup by either Shopify customer ID or customer email address, making it flexible for various integration patterns.

What This Endpoint Returns: An encrypted JWT-like token that authenticates a customer for the subscription management portal, along with token metadata. Unlike the manage-subscription-link endpoint which returns a complete URL, this returns only the token itself.

Response Components:

token (string):

• Encrypted authentication token
• JWT-style format with cryptographic signature
• Contains customer ID and shop information
• Valid for 2 hours from generation
• Cannot be forged or tampered with

customerId (long):

• Shopify customer ID (numeric)
• Useful for verification
• Same ID used to generate token

Customer Lookup Methods:

Option 1: By Customer ID (Recommended)

GET /api/external/v2/customer-portal-token?customerId=12345

• Direct lookup by numeric Shopify customer ID
• Can use GraphQL GID format (automatically parsed)
• Fastest and most reliable
• No ambiguity

Option 2: By Email Address

GET /api/external/v2/customer-portal-token?email=customer@example.com

• Searches subscription database for matching email
• Finds associated customer ID automatically
• Useful when customer ID unknown
• Fails if email not found or invalid

Parameter Validation:

• Exactly ONE of customerId or email must be provided
• Providing neither: Returns 400 error
• Providing both: customerId takes precedence
• Email must exist in subscription database

Token Security:

Encryption:

• Uses HMAC-SHA256 cryptographic signing
• Secret key stored securely on server
• Token includes tamper detection
• Modification invalidates token

Expiration:

• Tokens expire exactly 2 hours after generation
• Timestamp embedded in token payload
• Verified on each use
• Cannot be extended

Scope:

• Token tied to specific customer
• Token tied to specific shop
• Cannot be used for other customers
• Cannot be used across shops

Use Cases:

1. Custom Portal Implementations:

• Build custom authentication flows
• Integrate portal into existing apps
• Create native mobile app authentication
• Headless commerce integrations

2. API-First Architectures:

• Generate tokens programmatically
• Pass tokens to frontend applications
• Build microservice authentication
• Separate auth from presentation

3. Single Sign-On (SSO):

• Authenticate users from existing system
• Bypass password entry
• Seamless portal access
• Cross-platform authentication

4. Email/SMS Campaigns:

• Generate tokens for magic links
• Embed in notification emails
• Include in SMS messages
• Create passwordless login links

5. Customer Support Tools:

• Generate portal access for support agents
• View customer's portal perspective
• Troubleshoot portal issues
• Assist customers remotely

Response Format:

{
  "customerId": 12345,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxMjM0NSwic2hvcCI6Im15c3RvcmUubXlzaG9waWZ5LmNvbSIsInRpbWVzdGFtcCI6MTcwOTU2MjAwMH0.abc123xyz789"
}

Using the Token:

Append to Portal URL:

const { token } = await getCustomerPortalToken(customerId);
const portalUrl = `https://mystore.com/tools/recurring/customer_portal?token=${token}`;
window.location.href = portalUrl;

Store in Session:

// Store for authenticated API calls
sessionStorage.setItem('portalToken', response.token);
sessionStorage.setItem('customerId', response.customerId);

// Use in subsequent requests
fetch('/api/subscription-data', {
  headers: { 'Authorization': `Bearer ${sessionStorage.getItem('portalToken')}` }
});

Mobile App Authentication:

// Generate token server-side
const tokenData = await generateToken(email);

// Send to mobile app
return {
  authToken: tokenData.token,
  customerId: tokenData.customerId,
  expiresIn: 7200 // 2 hours in seconds
};

Important Considerations:

Token vs. Full URL:

• This endpoint: Returns token only
• /manage-subscription-link endpoint: Returns complete URL
• Use this for custom implementations
• Use manage-subscription-link for simple email links

Email Lookup Limitations:

• Email must exist in subscription database
• Searches only customers with subscriptions
• Won't find customers without subscriptions
• Case-sensitive in some databases

Customer ID Formats:

• Accepts numeric ID: 12345
• Accepts GraphQL GID: gid://shopify/Customer/12345
• Automatically extracts numeric portion
• Always stores numeric format

Best Practices:

1. Generate On-Demand: Create tokens when needed, not in advance
2. Don't Store Long-Term: Tokens expire in 2 hours
3. Use HTTPS: Always transmit tokens over secure connections
4. Validate Expiry: Check token age on frontend
5. Prefer Customer ID: Use customerId lookup when available
6. Handle Errors: Gracefully handle missing customers

Security Notes:

• Treat tokens like passwords
• Don't log tokens in plain text
• Don't expose in URLs if possible (use POST bodies)
• Rotate tokens frequently
• Monitor for suspicious token generation patterns

Comparison with Other Endpoints:

vs. /manage-subscription-link:

• This: Token only
• That: Complete URL
• Use this for APIs, that for emails

vs. /subscription-contracts-email-magic-link:

• This: Returns token
• That: Sends email
• Use this for programmatic access, that for customer notifications

Authentication: Requires valid X-API-Key header

Retrieves the customer portal configuration and settings for the authenticated shop. The customer portal is the self-service interface where subscribers can manage their subscriptions, update payment methods, modify delivery addresses, and more.

What is the Customer Portal? The customer portal is a dedicated web interface that allows your subscribers to manage their subscription accounts independently. This reduces support burden and improves customer experience by enabling self-service subscription management.

Settings Returned:

• Display Configuration:

  • Portal theme and branding settings
  • Custom colors and logo
  • Layout preferences
  • Custom CSS selectors

• Feature Toggles:

  • Enable/disable subscription pausing
  • Enable/disable order skipping
  • Enable/disable product swapping
  • Enable/disable frequency changes
  • Enable/disable quantity modifications
  • Enable/disable address editing
  • Enable/disable payment method updates
  • Enable/disable subscription cancellation

• Subscription Management Options:

  • Maximum pause duration allowed
  • Minimum subscription duration requirements
  • Skip limits per billing cycle
  • Product swap availability
  • One-time product add-ons

• Communication Settings:

  • Email notification preferences
  • Custom portal messaging
  • Support contact information
  • Help text and instructions

• Access Control:

  • Portal authentication method
  • Password requirements
  • Magic link settings
  • Session duration

• Advanced Options:

  • Custom domain configuration
  • Redirect URLs
  • Webhook endpoints
  • Analytics tracking settings

Use Cases:

• Display customer portal with correct branding and theme
• Determine which features are available to subscribers
• Build custom portal interfaces using your settings
• Sync portal configuration across systems
• Validate subscription management capabilities
• Configure third-party integrations

Important Notes:

• Settings are shop-specific and unique per merchant
• Some features may be restricted based on subscription plan
• Changes to settings are reflected immediately in the portal
• Custom CSS must be valid and secure
• Portal URL is typically: shop-domain.com/apps/subscriptions

Common Configuration Scenarios:

1. Standard Self-Service Portal:

• Allow pausing (up to 3 months)
• Allow skipping (max 2 consecutive orders)
• Allow frequency changes
• Allow quantity updates
• Allow address editing
• Enable payment method updates
• Enable cancellation with feedback

2. Locked-Down Portal (Minimal Self-Service):

• Disable pausing
• Disable skipping
• Disable cancellation (require support contact)
• Allow address editing only
• Allow payment method updates only

3. Full-Service Portal (Maximum Flexibility):

• Enable all subscription management features
• Allow unlimited pauses and skips
• Enable product swapping
• Enable one-time add-ons
• Allow subscription splitting/merging
• Custom branding and domain

Authentication: Requires valid X-API-Key header