# Customer Portal

Core customer portal APIs for managing customer account settings, authentication, and portal configurations.

## Process refund for subscription order

 - [PUT /subscriptions/cp/api/subscription-billing-attempts/refund-fulfillment/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/refundfulfillment.md): Processes a refund for a fulfilled subscription order. This creates a refund in Shopify and returns the money to the customer's original payment method.

What it does:
1. Validates order is eligible for refund (fulfilled, not already refunded)
2. Creates refund transaction in Shopify
3. Processes refund with payment gateway
4. Updates order status to 'Refunded'
5. Sends refund confirmation email to customer
6. Logs refund activity

Refund Eligibility:
- Order must be fulfilled
- Cannot already be refunded
- Must be within merchant's refund policy window
- Payment gateway must support refunds

Refund Processing:
- Refund is processed to original payment method
- Takes 5-10 business days to appear in customer's account
- Processing fees are typically not refunded
- Partial refunds are supported (if configured)

Important Warnings:
- This action cannot be undone
- Refunded orders cannot be un-refunded
- Inventory is restocked automatically
- Refunds may incur gateway fees

Authentication: Customer must be logged in and own the subscription

## Redeem loyalty points for a reward

 - [POST /subscriptions/cp/api/loyalty-integration/redeem](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/redeempoints.md): Allows a customer to redeem their loyalty points for a specific reward option. This deducts points from their balance and generates a discount code or applies the reward.

What happens:
1. Validates customer has enough points
2. Deducts points from customer's balance
3. Generates discount code (for discount rewards)
4. Records redemption in customer's history
5. Returns discount code or confirmation

Reward Types:
- Discount codes: Generates unique code customer can use at checkout
- Auto-apply discounts: Automatically applied to next order
- Free products: Adds free product to next order
- Free shipping: Waives shipping on next order

Important Notes:
- Points are deducted immediately and cannot be refunded
- Discount codes typically expire after 30 days
- Some rewards have minimum purchase requirements
- Rewards cannot be combined with other discounts (depends on configuration)

Use Cases:
- Customer clicks 'Redeem' button in customer portal
- Apply points at checkout
- Redeem points for subscription discount

Authentication: Customer must be logged in via Shopify customer session

## Initiate Customer Account API OAuth flow

 - [POST /subscriptions/cp/api/customer-account-api/initiate](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/initiateoauth.md): Initiates the OAuth 2.0 authorization flow for Shopify's Customer Account API. This endpoint is used when a customer wants to grant the subscription app access to their Shopify customer account data.

What is Customer Account API?
Shopify's Customer Account API allows apps to access customer data (orders, addresses, payment methods) on behalf of the customer. This requires customer consent through an OAuth flow.

How it works:
1. Customer portal calls this endpoint with a return URL
2. Backend generates PKCE challenge and state parameter
3. Returns authorization URL to redirect customer to Shopify
4. Customer authorizes on Shopify
5. Shopify redirects back to callback endpoint with authorization code
6. Callback endpoint exchanges code for access token

Important Notes:
- Requires customer to be logged in to the Shopify store
- Only works with stores that have 'New Customer Accounts' enabled
- Uses PKCE (Proof Key for Code Exchange) for security
- State parameter prevents CSRF attacks
- Access tokens are stored securely and used for subsequent Customer Account API calls

Authentication: Customer must be logged in via Shopify customer session

## Proxy GraphQL queries to Shopify Customer Account API

 - [POST /subscriptions/cp/api/customer-account-api/graphql](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/proxygraphql.md): Executes GraphQL queries against Shopify's Customer Account API on behalf of the authenticated customer. This endpoint handles token management, refresh, and authentication automatically.

What you can query:
- Customer profile information
- Order history and details
- Saved addresses
- Payment methods
- Subscriptions (via Customer Account API schema)

Token Management:
- Automatically uses stored access token
- Refreshes expired tokens automatically
- Returns 401 if customer needs to re-authenticate

Example Queries:
graphql
query {
  customer {
    id
    emailAddress { emailAddress }
    defaultAddress { address1 city }
  }
}


Authentication: Customer must be logged in and have completed OAuth flow

## Get available loyalty point redemption options

 - [GET /subscriptions/cp/api/loyalty-integration/redeem-options](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/getredeemoptionsforcp.md): Returns all available rewards that the customer can redeem their loyalty points for. This shows customers what they can spend their points on.

Common Redemption Options:
- Discount codes (e.g., $5 off for 500 points)
- Percentage discounts (e.g., 10% off for 1000 points)
- Free shipping rewards
- Free products or samples
- Exclusive access to sales

Response includes:
- Redemption option ID
- Name and description
- Points cost
- Reward value (dollar amount or percentage)
- Availability (minimum purchase, restrictions)
- Whether customer has enough points

Filtering:
- Only shows active redemption options
- Filters based on customer's tier/VIP level
- Shows whether customer has sufficient points

Use Cases:
- Display 'Redeem Points' section in customer portal
- Show available rewards in checkout
- Encourage customers to save points for bigger rewards

Authentication: Customer must be logged in via Shopify customer session

## Get customer loyalty points and rewards data

 - [GET /subscriptions/cp/api/loyalty-integration/customer](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/fetchcustomerdetailforcp.md): Retrieves the loyalty/rewards program data for the currently logged-in customer. This includes points balance, tier status, and available rewards.

Supported Loyalty Programs:
- Appstle Loyalty & Rewards
- Yotpo Loyalty & Referrals
- Smile.io (via Appstle integration)

What you get:
- Current points balance
- Points pending (from recent orders)
- VIP tier/level
- Points history
- Available reward redemptions

Use Cases:
- Display points balance in customer portal
- Show available rewards customer can redeem
- Display VIP tier badge
- Show points expiration dates

Authentication: Customer must be logged in via Shopify customer session

Note: Requires loyalty app integration to be configured in merchant settings

## Get currently logged-in customer ID

 - [GET /subscriptions/cp/api/logged-in-customer](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/updatesubscriptioncontractdetails_1.md): Returns the customer ID of the currently authenticated customer from their Shopify session. This endpoint is used by the customer portal UI to identify which customer is logged in.

Use Cases:
- Customer portal initialization - determine who's logged in
- Fetch customer-specific data (subscriptions, orders, settings)
- Validate customer session before displaying sensitive information
- Personalize customer portal UI with customer name/email

How it works:
- Customer must be logged in to their Shopify customer account
- Session is validated via Shopify App Proxy
- Returns Shopify customer ID (numeric)

Important Notes:
- This endpoint only works when called from the shop domain (via Shopify App Proxy)
- Customer must be logged in to Shopify
- Returns null if customer is not authenticated
- Do not use this for external API integrations - use External APIs with explicit customer ID instead

Authentication: Requires active Shopify customer session (browser-based)

## Get custom CSS for customer portal

 - [GET /subscriptions/cp/api/subscription-custom-csses/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/getsubscriptioncustomcss.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

## Calculate refund amount preview

 - [GET /subscriptions/cp/api/subscription-billing-attempts/refund-preview/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/calculaterefundpreview.md): 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

## Get available ways to earn loyalty points

 - [GET /subscriptions/cp/api/loyalty-integration/earn-options](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/getearnoptions.md): 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

## Get customer portal settings

 - [GET /subscriptions/cp/api/customer-portal-settings/{id}](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/getcustomerportalsettings.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

## Check Customer Account API authentication status

 - [GET /subscriptions/cp/api/customer-account-api/status](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/checkauthstatus.md): 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

## Handle OAuth callback from Shopify

 - [GET /subscriptions/cp/api/customer-account-api/oauth/callback](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/handleoauthcallback.md): 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.

## Logout from Customer Account API

 - [GET /subscriptions/cp/api/customer-account-api/logout](https://developers.subscription.appstle.com/customer-portal-swagger/customer-portal/handlelogout.md): Logs out the customer from the Customer Account API session. This can be initiated either by the customer clicking logout in the customer portal, or by Shopify's end session callback.

What it does:
- Deletes stored access and refresh tokens
- Initiates Shopify's end session flow (if tokens available)
- Redirects to return URL or back to customer portal

Two scenarios:
1. App-initiated logout: Customer clicks logout in portal
   - Portal calls this endpoint with return URL
   - Tokens deleted, redirects to Shopify end session endpoint
   - Shopify redirects back to return URL

2. Shopify-initiated logout: Customer logs out globally from Shopify
   - Shopify calls this endpoint with id_token_hint
   - Tokens deleted, returns success

Important:
- This only logs out from Customer Account API, not from Shopify customer account
- Customer will need to re-authenticate to use Customer Account API features again
- Does not affect regular customer portal access (subscription management)

Authentication: Optional - can be called from Shopify without authentication