Customer Portal 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

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

Checks whether the current customer has valid Customer Account API tokens stored. Used by the customer portal to determine if the customer needs to authenticate.

Use Cases:

• Check if customer is authenticated before making Customer Account API GraphQL calls
• Determine whether to show 'Connect Account' button in UI
• Validate token validity before attempting sensitive operations

Response: Returns authentication status and customer ID.

Authentication: Customer must be logged in via Shopify customer session

OAuth 2.0 callback endpoint that receives the authorization code from Shopify after customer authorization. This endpoint is called automatically by Shopify after the customer authorizes the app.

Flow:

1. Shopify redirects customer here with authorization code and state
2. Validates state parameter to prevent CSRF
3. Exchanges authorization code for access token using PKCE verifier
4. Validates ID token (JWT) from Shopify
5. Stores access token and refresh token securely
6. Redirects customer back to original return URL

Security:

• Validates state parameter matches stored value
• Uses PKCE code verifier to exchange authorization code
• Validates ID token signature and claims
• State expires after 10 minutes

Error Handling:

• If customer denies authorization, redirects with error parameter
• If token exchange fails, redirects with error parameter
• All errors are logged for debugging

Note: This endpoint should not be called directly - it's invoked by Shopify's OAuth redirect.