> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Portal

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

## Query

<CodeGroup>
  ```graphql Query theme={null}
  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
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123"
    }
  }
  ```

  ```json Response theme={null}
  {
    "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": []
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="CustomerPortalInput" required>
  Input parameters for the customer portal query

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      The unique reference ID of the customer
    </ParamField>

    <ParamField body="resourceId" type="String">
      Optional resource ID for multi-resource customers
    </ParamField>

    <ParamField body="productId" type="String">
      Filter portal data to a specific product
    </ParamField>
  </Expandable>
</ParamField>

## 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

<AccordionGroup>
  <Accordion title="Self-service portal page">
    Build a complete customer portal showing current plan, usage, and upgrade options.
  </Accordion>

  <Accordion title="Usage dashboard">
    Display current feature usage against limits with progress bars.
  </Accordion>

  <Accordion title="Billing management">
    Show payment method and link to billing portal for updates.
  </Accordion>

  <Accordion title="Upgrade prompts">
    Check `canUpgradeSubscription` and show upgrade CTAs when appropriate.
  </Accordion>
</AccordionGroup>

## Example: Building a Portal UI

```javascript theme={null}
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](/api-and-sdks/api-reference/queries/get-customer) - Get customer details
* [Paywall](/api-and-sdks/api-reference/queries/paywall) - Get available plans for upgrade
* [Preview Subscription](/api-and-sdks/api-reference/mutations/preview-subscription) - Preview upgrade pricing