Skip to content
Customer Portal APIs
/
/
Proxy GraphQL queries to...

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

Initiate Customer Account API OAuth flow

Request

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

Bodyapplication/jsonrequired

OAuth initiation request with return URL

returnUrlstring
curl -i -X POST \
  https://www.myshop.com/apps/subscriptions/cp/api/customer-account-api/initiate \
  -H 'Content-Type: application/json' \
  -d '{
    "returnUrl": "https://myshop.com/account/subscriptions"
  }'

Responses

OAuth flow initiated successfully

Bodyapplication/json
Response
application/json
{
  "authorizationUrl": "https://shopify.com/12345/auth/oauth/authorize?client_id=...",
  "state": "random-state-value-for-csrf-protection"
}

Proxy GraphQL queries to Shopify Customer Account API

Request

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:

query {
  customer {
    id
    emailAddress { emailAddress }
    defaultAddress { address1 city }
  }
}

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

Bodyapplication/jsonrequired

GraphQL query and optional variables

querystring
variablesobject
curl -i -X POST \
  https://www.myshop.com/apps/subscriptions/cp/api/customer-account-api/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query { customer { id emailAddress { emailAddress } } }",
    "variables": {}
  }'

Responses

GraphQL query executed successfully

Bodyapplication/json
Response
application/json
{
  "data": {
    "customer": { … }
  }
}

Get available loyalty point redemption options

Request

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

curl -i -X GET \
  https://www.myshop.com/apps/subscriptions/cp/api/loyalty-integration/redeem-options

Responses

Redemption options retrieved successfully

Bodyapplication/json
Response
application/json
[
  {
    "id": 1,
    "name": "$5 Off Coupon",
    "description": "Get $5 off your next order",
    "pointsCost": 500,
    "rewardValue": 5,
    "rewardType": "FIXED_AMOUNT",
    "canRedeem": true
  },
  {
    "id": 2,
    "name": "15% Off Entire Order",
    "description": "Get 15% off your entire order",
    "pointsCost": 1500,
    "rewardValue": 15,
    "rewardType": "PERCENTAGE",
    "canRedeem": true
  }
]

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.