# Customer Portal

APIs powering the customer-facing portal where subscribers can manage their own subscriptions.

## Regenerate subscription widget scripts

 - [GET /api/external/v2/theme-settings/regenerate-scripts-for-shop](https://developers.subscription.appstle.com/external-api-swagger/customer-portal/regeneratescriptforshop.md): Triggers regeneration and deployment of subscription widget JavaScript files for the authenticated shop. This endpoint rebuilds the widget scripts that power subscription functionality on your storefront and deploys them to CDN.

What Does This Endpoint Do?
This endpoint initiates an asynchronous process to regenerate and update the JavaScript files that enable subscription widgets on your store's theme. The widget scripts handle:
- Subscription product selection and display
- Subscription plan offerings on product pages
- Frequency and delivery interval selectors
- Subscription pricing display
- Add-to-cart subscription functionality
- Widget styling and customization

When to Use This Endpoint:

1. After Widget Settings Changes:
- Modified widget appearance or styling
- Changed subscription plan display options
- Updated widget text or labels
- Altered widget positioning or layout
- Changed frequency options display

2. After Theme Customization:
- Installed a new theme
- Updated existing theme
- Made CSS customizations affecting widgets
- Changed theme structure requiring widget updates

3. After Plan Configuration Changes:
- Added new subscription plans
- Modified existing plan details
- Changed plan pricing or discounts
- Updated plan availability rules

4. Troubleshooting:
- Widget not displaying correctly on storefront
- Subscription options showing outdated information
- Widget functionality broken after theme changes
- Script conflicts or errors on product pages
- Cache issues preventing updates from showing

5. After App Updates:
- Appstle subscription app has been upgraded
- New widget features have been released
- Bug fixes requiring script updates

How It Works:

1. Initiation: API call triggers the script regeneration process
2. Compilation: System compiles widget configuration, theme settings, and subscription plans into optimized JavaScript
3. Deployment: Generated scripts are uploaded to CDN for fast global delivery
4. Cache Invalidation: Old cached versions are invalidated
5. Completion: Updated scripts become available to your storefront (typically within 1-2 minutes)

What Gets Regenerated:
- Widget JavaScript: Core widget functionality and UI components
- Configuration Data: Embedded shop-specific settings and plan information
- Styling Rules: Custom CSS and theme-specific styles
- Initialization Code: Auto-load and widget mounting logic
- Event Handlers: Customer interaction and analytics tracking

Process Details:
- Asynchronous: The regeneration happens in the background
- Non-blocking: Endpoint returns immediately (true on success)
- No downtime: Existing widgets continue working during regeneration
- Automatic deployment: Scripts are automatically deployed to CDN
- Versioning: New script versions don't break existing functionality

Expected Behavior:
- Endpoint returns true immediately to confirm process started
- Script regeneration completes in background (typically 30-90 seconds)
- Updated scripts propagate to CDN (1-2 minutes)
- Browser cache may need clearing to see changes immediately
- Changes visible to customers after cache expiration (varies by browser)

Use Cases:
- Automated Deployments: Include in CI/CD pipeline after theme updates
- Widget Troubleshooting: Force refresh when widget issues occur
- Configuration Sync: Ensure widgets reflect latest settings after bulk changes
- Theme Migration: Update scripts after moving to new theme
- Testing: Regenerate scripts after making configuration changes in staging
- Maintenance: Periodic regeneration to ensure optimal performance

Important Notes:
- Safe to call multiple times (idempotent operation)
- No negative impact on existing subscriptions
- Does not modify theme files directly
- Scripts are hosted on CDN, not in your theme
- Changes apply to all store pages using subscription widgets
- Browser caching may delay visibility of changes to end users

Best Practices:
- Call this endpoint after making widget setting changes
- Wait 2-3 minutes before testing changes on storefront
- Clear browser cache when testing to see latest version
- Use in test/staging environment before production
- Avoid calling excessively (once per configuration change is sufficient)
- Monitor widget functionality after regeneration

Troubleshooting:
If widgets still don't reflect changes after regeneration:
1. Wait 5 minutes for full CDN propagation
2. Clear browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
3. Check browser console for JavaScript errors
4. Verify theme has widget embed code installed
5. Confirm subscription plans are properly configured
6. Test in incognito/private browsing mode

Integration Workflows:

Theme Update Workflow:
1. Make theme changes
2. Update widget settings if needed
3. Call regenerate-scripts endpoint
4. Wait 2-3 minutes
5. Test widgets on storefront
6. Deploy to production

Bulk Configuration Update:
1. Update multiple subscription plans
2. Modify widget appearance settings
3. Call regenerate-scripts once (not after each change)
4. Verify changes propagated correctly

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

## Get custom CSS for customer portal

 - [GET /api/external/v2/subscription-custom-csses/{id}](https://developers.subscription.appstle.com/external-api-swagger/customer-portal/getsubscriptioncustomcssv2.md): Retrieves the custom CSS styling configuration for the customer portal. This endpoint returns all custom CSS rules that have been configured to customize the appearance, layout, and branding of the subscription customer portal.

What is Custom CSS?
Custom CSS allows merchants to fully customize the visual appearance of their customer portal beyond the basic theme settings. This enables complete brand alignment and creates a seamless experience that matches the merchant's main store design.

Custom CSS Capabilities:
- Layout Customization:
  - Modify page layouts and spacing
  - Adjust grid and flexbox configurations
  - Control responsive breakpoints
  - Customize navigation and sidebars

- Typography:
  - Custom fonts and font families
  - Font sizes, weights, and line heights
  - Letter spacing and text transforms
  - Heading and paragraph styles

- Colors and Branding:
  - Brand color palette application
  - Custom background colors and gradients
  - Button and link styling
  - Hover and focus states
  - Border colors and shadows

- Component Styling:
  - Subscription card appearances
  - Form input styling
  - Button designs and interactions
  - Modal and dialog boxes
  - Navigation menus
  - Product images and thumbnails

- Advanced Features:
  - CSS animations and transitions
  - Media queries for responsive design
  - Pseudo-elements and pseudo-classes
  - Custom icons using CSS
  - Transform and filter effects

CSS Structure:
The returned CSS includes:
- Global styles for portal-wide consistency
- Component-specific styles
- Responsive design rules
- Theme overrides
- Custom animations
- Print styles (optional)

Common CSS Selectors Available:
css
/ Portal container /
.subscription-portal { }

/ Subscription cards /
.subscription-card { }
.subscription-card-header { }
.subscription-card-body { }

/ Buttons /
.btn-primary { }
.btn-secondary { }
.btn-cancel { }

/ Forms /
.form-control { }
.form-group { }
.form-label { }

/ Navigation /
.portal-nav { }
.nav-item { }

/ Product displays /
.product-item { }
.product-image { }
.product-title { }


Use Cases:
- Apply custom branding to match main store design
- Create unique visual experiences for different customer segments
- Implement seasonal or promotional themes
- Enhance mobile responsiveness
- Add accessibility improvements (high contrast, larger fonts)
- A/B test different portal designs
- Integrate with design systems
- Implement dark mode or theme switching

Important Notes:
- CSS is sanitized for security (XSS prevention)
- Certain properties may be restricted for security reasons
- External resources (fonts, images) must use HTTPS
- CSS is cached for performance - changes may take a few minutes to propagate
- Invalid CSS syntax is automatically filtered out
- Some core portal elements have !important styles that cannot be overridden

Best Practices:
- Use specific selectors to avoid conflicts
- Test across different browsers and devices
- Keep CSS organized with comments
- Use CSS variables for maintainability
- Minify CSS for production performance
- Consider accessibility in color choices (WCAG compliance)
- Provide fallbacks for advanced CSS features

Security Considerations:
- CSS is sanitized to prevent code injection
- External URLs are validated
- JavaScript in CSS is blocked (e.g., expression(), behavior())
- Data URIs are validated for malicious content

Authentication: Requires valid X-API-Key header

## Send magic link email to customer for portal access

 - [GET /api/external/v2/subscription-contracts-email-magic-link](https://developers.subscription.appstle.com/external-api-swagger/customer-portal/emailmagiclinkv2.md): Sends an automated email to a customer containing a secure magic link for accessing their subscription management portal. The email is sent using the shop's configured email template and includes a time-limited authentication token.

What This Endpoint Does:
1. Validates customer exists and has subscriptions
2. Generates secure portal access token
3. Retrieves shop's email template configuration
4. Sends personalized email with magic link
5. Logs activity for audit trail

Magic Link Functionality:

What is a Magic Link?
A magic link is a special URL containing an encrypted authentication token that allows customers to access their portal without entering a password. Clicking the link automatically logs them in.

Link Contents:
- Shop's portal URL
- Encrypted customer token (2-hour expiration)
- Direct access to subscription management
- No password required

Security:
- Token expires in 2 hours
- Single customer authentication
- Cannot be used by others
- Logged for security audit

Request Parameters:

email (required):
- Customer's email address
- Must exactly match email in Shopify
- Customer must have at least one subscription
- Case-sensitive in some systems

Email Template Configuration:

Template Requirements:
- Email template must be configured in Appstle settings
- Template type: SUBSCRIPTION_MANAGEMENT_LINK
- Template must not be disabled
- Template includes shop branding and customization

Email Content:
- Personalized greeting with customer name
- Clickable magic link button/link
- Expiration notice (link valid 2 hours)
- Shop branding and footer
- Optional custom messaging

Template Variables:
- {customer_name}: Customer's display name
- {magic_link}: Portal URL with token
- {shop_name}: Store name
- {expiration_time}: Token expiry time

Use Cases:

1. Customer Self-Service:
- "Forgot password" alternative
- Quick portal access without account setup
- Passwordless authentication flow
- Reduce friction for customers

2. Subscription Management Prompts:
- "Manage your subscription" emails
- Pre-billing reminders with management link
- Post-purchase subscription setup
- Re-engagement campaigns

3. Customer Support:
- Send portal access to customers
- Enable self-service during support interactions
- Provide instant portal access
- Reduce support workload

4. Automated Workflows:
- Payment failure recovery emails
- Subscription expiration notices
- Pause/skip reminders
- Renewal notifications

5. Marketing Campaigns:
- Subscription feature announcements
- New product availability
- Loyalty program invitations
- Referral program links

Process Flow:


1. API receives email parameter
2. Searches subscription database for customer email
3. If not found → Returns 400 error
4. If found → Retrieves customer subscriptions
5. Sorts subscriptions by status (active first)
6. Checks email template configuration
7. If disabled → Returns 400 error with instructions
8. If enabled → Generates magic link token
9. Prepares email with template
10. Sends email via configured provider
11. Logs activity (source: MERCHANT_EXTERNAL_API)
12. Returns success message


Response Format:
json
"Email triggered successfully."


Simple string response confirming email queued for delivery.

Important Considerations:

Customer Validation:
- Email MUST exist in subscription database
- Customer MUST have at least one subscription
- Customers without subscriptions cannot receive link
- Returns error if customer not found

Email Template Disabled:
- If template disabled in settings: Returns error
- Error message guides merchant to enable template
- Path: "More -> Email Settings"
- Template must be explicitly enabled

Email Delivery:
- Email sent asynchronously
- Success response doesn't guarantee delivery
- Check email logs for delivery confirmation
- Respects shop's email provider settings

Multiple Subscriptions:
- If customer has multiple subscriptions: Sorts by status
- Active subscriptions shown first
- Link provides access to ALL customer subscriptions
- Portal displays all contracts

Activity Logging:
- All magic link emails logged
- Source: MERCHANT_EXTERNAL_API
- Includes timestamp and customer
- Viewable in activity logs

Integration Examples:

Webhook Trigger - Payment Failed:
javascript
async function handlePaymentFailure(webhook) {
  const customerEmail = webhook.customer.email;
  
  // Send magic link to customer
  await fetch(
    /api/external/v2/subscription-contracts-email-magic-link?email=${customerEmail},
    { headers: { 'X-API-Key': process.env.APPSTLE_API_KEY } }
  );
  
  console.log(Magic link sent to ${customerEmail} for payment update);
}


Customer Support Button:
javascript
async function sendPortalAccess(customerEmail) {
  try {
    const response = await fetch(
      /api/external/v2/subscription-contracts-email-magic-link?email=${encodeURIComponent(customerEmail)},
      { 
        headers: { 'X-API-Key': apiKey },
        method: 'GET'
      }
    );
    
    if (response.ok) {
      alert('Portal access email sent to customer!');
    }
  } catch (error) {
    console.error('Failed to send magic link:', error);
  }
}


Best Practices:

1. Validate Email: Check email format before calling API
2. Rate Limiting: Don't spam customers - limit frequency
3. Error Handling: Handle customer not found gracefully
4. User Feedback: Confirm email sent to user
5. Test Template: Ensure email template configured and working
6. Monitor Logs: Check activity logs for delivery issues

Common Errors:

"Customer Email does not exist":
- Email not found in subscription database
- Customer has no subscriptions
- Email may be misspelled

"Email template not found":
- SUBSCRIPTION_MANAGEMENT_LINK template not configured
- Contact Appstle support to set up template

"Email is currently disabled":
- Template disabled in Email Settings
- Navigate to More -> Email Settings
- Enable "Subscription Management Link" email

Authentication: Requires valid X-API-Key header

## Generate customer portal authentication token

 - [GET /api/external/v2/customer-portal-token](https://developers.subscription.appstle.com/external-api-swagger/customer-portal/getcustomerportaltoken.md): 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:
json
{
  "customerId": 12345,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxMjM0NSwic2hvcCI6Im15c3RvcmUubXlzaG9waWZ5LmNvbSIsInRpbWVzdGFtcCI6MTcwOTU2MjAwMH0.abc123xyz789"
}


Using the Token:

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


Store in Session:
javascript
// 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:
javascript
// 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

## Get customer portal settings

 - [GET /api/external/v2/customer-portal-settings/{id}](https://developers.subscription.appstle.com/external-api-swagger/customer-portal/getcustomerportalsettingsv2.md): 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