Skip to content
/Customer Portal

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

Process refund for subscription order

Request

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

Path
idinteger(int64)required

Billing attempt ID to refund

Query
subscriptionContractIdinteger(int64)

Subscription contract ID for validation

curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/refund-fulfillment/{id}?subscriptionContractId=0'

Responses

Refund processed successfully

Bodyapplication/json
Response
application/json
{
  "success": true,
  "refundId": "123456",
  "refundAmount": 44.49,
  "message": "Refund processed successfully. Amount will appear in 5-10 business days."
}

Redeem loyalty points for a reward

Request

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

Query
customerIdstringrequired

Customer ID (Shopify GraphQL ID format)

Example: customerId=gid://shopify/Customer/6548267876558
redeemOptionIdinteger(int64)required

ID of the redemption option to redeem

Example: redeemOptionId=1
pointsinteger(int64)

Number of points to redeem (for variable point redemptions)

curl -i -X POST \
  'https://www.myshop.com/apps/subscriptions/cp/api/loyalty-integration/redeem?customerId=gid%3A%2F%2Fshopify%2FCustomer%2F6548267876558&redeemOptionId=1&points=0'

Responses

Points redeemed successfully

Bodyapplication/json
Response
application/json
"LOYALTY500-ABC123"

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"
}

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.