Skip to content
Customer Portal APIs
/
/
Handle OAuth callback fro...

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
customer-portal-swagger.json
customer-portal-swagger.yaml
Languages
Servers
https://www.myshop.com/apps

Customer Portal

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

Operations

Check Customer Account API authentication status

Request

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

curl -i -X GET \
  https://www.myshop.com/apps/subscriptions/cp/api/customer-account-api/status

Responses

Authentication status retrieved successfully

Bodyapplication/json
Response
application/json
{
  "authenticated": true,
  "customerId": "123456789"
}

Handle OAuth callback from Shopify

Request

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.

Query
codestring

Authorization code from Shopify (if successful)

Example: code=abc123...
statestringrequired

State parameter for CSRF protection

errorstring

Error code if authorization failed

Example: error=access_denied
error_descriptionstring

Human-readable error description

curl -i -X GET \
  'https://www.myshop.com/apps/subscriptions/cp/api/customer-account-api/oauth/callback?code=abc123...&state=string&error=access_denied&error_description=string'

Responses

Redirects to return URL with success or error parameter

Logout from Customer Account API

Request

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

Query
return_urlstring

URL to redirect to after logout

Example: return_url=https://myshop.com/account
id_token_hintstring

ID token for Shopify-initiated logout (optional)

shopstring

Shop domain (optional, for Shopify-initiated logout)

curl -i -X GET \
  'https://www.myshop.com/apps/subscriptions/cp/api/customer-account-api/logout?return_url=https%3A%2F%2Fmyshop.com%2Faccount&id_token_hint=string&shop=string'

Responses

Logout successful (when no redirect configured)

Subscription Management

APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations.

Operations

Billing & Payments

APIs for managing payment methods, billing information, and processing subscription payments.

Operations

Product Catalog

APIs for retrieving product information, selling plans, variant data, and subscription-enabled products available to customers.

Operations

Delivery & Shipping

APIs for managing delivery schedules, shipping addresses, delivery methods, and tracking order status.

Customer Retention

APIs for handling subscription cancellations, retention activities, and customer feedback management.

Loyalty Integration

APIs for integrating loyalty programs with subscriptions including points redemption and earning options.

Customization

APIs for accessing portal customization settings, translations, and theme configurations.