Core customer portal APIs for managing customer account settings, authentication, and portal configurations.
Customer Portal APIs
/- Get available ways to earn loyalty points
Process refund for subscription order
Redeem loyalty points for a reward
Initiate Customer Account API OAuth flow
Proxy GraphQL queries to Shopify Customer Account API
Get available loyalty point redemption options
Get customer loyalty points and rewards data
Get currently logged-in customer ID
Get custom CSS for customer portal
Calculate refund amount preview
Get customer portal settings
Check Customer Account API authentication status
Handle OAuth callback from Shopify
Logout from Customer Account API
Get available ways to ear...
Customer Portal APIs (0.0.1)
Comprehensive API documentation for the customer-facing subscription portal. These APIs enable customers to manage their subscriptions, update billing information, modify delivery schedules, and access their account details through your storefront.
Important: These APIs must be called from your shop's domain (e.g., https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error.
Download OpenAPI description
Languages
Servers
https://www.myshop.com/apps
Request
Calculates the refund amount that would be issued if a specific subscription order fulfillment were refunded. This provides a preview without actually processing the refund.
What it calculates:
- Total refund amount (order amount minus processing fees)
- Restocking fees (if applicable)
- Gateway fees that cannot be refunded
- Net refund amount customer will receive
Use Cases:
- Show customer how much they'll get back before confirming refund
- Display refund breakdown in customer portal
- Validate refund eligibility
Important Notes:
- This is a preview only - does not process refund
- Refund amount may vary based on payment gateway
- Some gateways don't refund processing fees
- Refunds can only be issued for fulfilled orders
Authentication: Customer must be logged in and own the subscription
- https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/refund-preview/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/refund-preview/{id}?subscriptionContractId=0'Response
application/json
{ "orderAmount": 45.99, "processingFees": 1.5, "restockingFee": 0, "refundAmount": 44.49, "currency": "USD" }
Request
Returns all active point earning campaigns and rules that the customer can participate in. This shows customers how they can earn more points.
Common Earning Methods:
- Points per dollar spent on purchases
- Bonus points for first subscription
- Points for referring friends
- Birthday bonus points
- Social media follows (Instagram, Facebook, Twitter)
- Product reviews
- Account creation bonus
Response includes:
- Campaign name and description
- Points awarded
- Action required (e.g., 'Follow on Instagram')
- Icon/image URL
- Terms and conditions
Use Cases:
- Display 'Ways to Earn' section in customer portal
- Show earning opportunities on product pages
- Encourage customer engagement
Authentication: Customer must be logged in via Shopify customer session
- https://www.myshop.com/apps/subscriptions/cp/api/loyalty-integration/earn-options
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://www.myshop.com/apps/subscriptions/cp/api/loyalty-integration/earn-options?customerId=string'Response
application/json
[ { "name": "Purchase Rewards", "description": "Earn 5 points for every $1 spent", "pointsAmount": 5, "action": "Make a purchase" }, { "name": "Refer a Friend", "description": "Earn 500 points when your friend makes their first purchase", "pointsAmount": 500, "action": "Share referral link" } ]
Request
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
- https://www.myshop.com/apps/subscriptions/cp/api/customer-portal-settings/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://www.myshop.com/apps/subscriptions/cp/api/customer-portal-settings/{id}'Response
application/json
{ "id": 12345, "shop": "example-shop.myshopify.com", "portalEnabled": true, "customDomain": "subscriptions.example.com", "allowPause": true, "maxPauseDuration": 90, "allowSkip": true, "maxConsecutiveSkips": 2, "allowFrequencyChange": true, "allowQuantityChange": true, "allowProductSwap": true, "allowAddressEdit": true, "allowPaymentMethodUpdate": true, "allowCancellation": true, "requireCancellationReason": true, "enableOneTimeProducts": true, "minimumSubscriptionCycles": 3, "theme": { "primaryColor": "#4A90E2", "secondaryColor": "#50E3C2", "accentColor": "#F5A623", "fontFamily": "'Helvetica Neue', Arial, sans-serif", "logoUrl": "https://cdn.shopify.com/s/files/1/0000/0000/files/logo.png", "customCss": ".subscription-card { border-radius: 8px; }" }, "authentication": { "method": "MAGIC_LINK", "sessionDuration": 3600, "requireEmailVerification": true }, "notifications": { "sendSkipConfirmation": true, "sendPauseConfirmation": true, "sendFrequencyChangeConfirmation": true, "sendCancellationConfirmation": true }, "supportContact": { "email": "support@example.com", "phone": "+1-800-123-4567", "chatEnabled": true }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-02-20T14:45:00Z" }