Customer Portal

Retrieves all the data needed to render a customer self-service portal, including subscriptions, entitlements, and billing information.

Query

Query

query GetCustomerPortal($input: CustomerPortalInput!) {
  customerPortal(input: $input) {
    subscriptions {
      subscriptionId
      status
      startDate
      currentBillingPeriodEnd
      plan {
        refId
        displayName
      }
      addons {
        addon {
          refId
          displayName
        }
        quantity
      }
      prices {
        billingPeriod
        price {
          amount
          currency
        }
      }
    }
    entitlements {
      feature {
        refId
        displayName
        featureType
      }
      isGranted
      hasUnlimitedUsage
      usageLimit
      currentUsage
      resetPeriod
    }
    billingInformation {
      defaultPaymentMethodLast4Digits
      defaultPaymentMethodType
      defaultPaymentExpirationMonth
      defaultPaymentExpirationYear
    }
    billingPortalUrl
    canUpgradeSubscription
    promotionalEntitlements {
      featureId
      displayName
      hasUnlimitedUsage
      usageLimit
    }
  }
}

{
  "input": {
    "customerId": "customer-123"
  }
}

{
  "data": {
    "customerPortal": {
      "subscriptions": [
        {
          "subscriptionId": "sub-456",
          "status": "ACTIVE",
          "startDate": "2024-01-15T00:00:00Z",
          "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
          "plan": {
            "refId": "plan-pro",
            "displayName": "Pro Plan"
          },
          "addons": [
            {
              "addon": {
                "refId": "addon-seats",
                "displayName": "Extra Seats"
              },
              "quantity": 5
            }
          ],
          "prices": [
            {
              "billingPeriod": "MONTHLY",
              "price": {
                "amount": 99,
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "entitlements": [
        {
          "feature": {
            "refId": "feature-api-calls",
            "displayName": "API Calls",
            "featureType": "NUMBER"
          },
          "isGranted": true,
          "hasUnlimitedUsage": false,
          "usageLimit": 10000,
          "currentUsage": 4532,
          "resetPeriod": "MONTH"
        }
      ],
      "billingInformation": {
        "defaultPaymentMethodLast4Digits": "4242",
        "defaultPaymentMethodType": "CARD",
        "defaultPaymentExpirationMonth": 12,
        "defaultPaymentExpirationYear": 2025
      },
      "billingPortalUrl": "https://billing.stripe.com/session/...",
      "canUpgradeSubscription": true,
      "promotionalEntitlements": []
    }
  }
}

Parameters

input · CustomerPortalInput · required

Input parameters for the customer portal query

Show properties

customerId · String · required

The unique reference ID of the customer

resourceId · String

Optional resource ID for multi-resource customers

productId · String

Filter portal data to a specific product

Return Type

Returns a CustomerPortal object with:

Field	Type	Description
subscriptions	[CustomerPortalSubscription]	Active subscriptions
entitlements	[Entitlement]	All effective entitlements
billingInformation	CustomerPortalBillingInformation	Payment method details
billingPortalUrl	String	Link to billing provider portal
canUpgradeSubscription	Boolean	Whether upgrade is available
promotionalEntitlements	[CustomerPortalPromotionalEntitlement]	Promotional grants
resource	CustomerResource	Resource details (if applicable)

Billing Information Fields

Field	Type	Description
defaultPaymentMethodLast4Digits	String	Last 4 digits of payment method
defaultPaymentMethodType	PaymentMethodType	CARD, BANK_TRANSFER, etc.
defaultPaymentExpirationMonth	Int	Card expiration month
defaultPaymentExpirationYear	Int	Card expiration year
defaultPaymentMethodId	String	Payment method ID

Common Use Cases

Self-service portal page

Build a complete customer portal showing current plan, usage, and upgrade options.

Usage dashboard

Display current feature usage against limits with progress bars.

Billing management

Show payment method and link to billing portal for updates.

Upgrade prompts

Check canUpgradeSubscription and show upgrade CTAs when appropriate.

Example: Building a Portal UI

const { data } = await client.query({
  query: GET_CUSTOMER_PORTAL,
  variables: { input: { customerId: user.customerId } }
});

const portal = data.customerPortal;

// Display subscription info
portal.subscriptions.forEach(sub => {
  console.log(`Plan: ${sub.plan.displayName}`);
  console.log(`Status: ${sub.status}`);
  console.log(`Renews: ${sub.currentBillingPeriodEnd}`);
});

// Display usage meters
portal.entitlements
  .filter(e => e.feature.featureType === 'NUMBER')
  .forEach(e => {
    const percentage = (e.currentUsage / e.usageLimit) * 100;
    console.log(`${e.feature.displayName}: ${e.currentUsage}/${e.usageLimit}`);
  });

// Show upgrade option
if (portal.canUpgradeSubscription) {
  showUpgradeButton();
}

Related Operations

• Get Customer - Get customer details
• Paywall - Get available plans for upgrade
• Preview Subscription - Preview upgrade pricing