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

# Paywall

Retrieves plan data formatted specifically for building pricing pages and paywall components.

## Query

<CodeGroup>
  ```graphql Query theme={null}
  query GetPaywall($input: GetPaywallInput!) {
    paywall(input: $input) {
      plans {
        refId
        displayName
        description
        pricingType
        basePlan {
          refId
        }
        pricePoints {
          billingPeriod
          amount
          currency
        }
        entitlements {
          feature {
            refId
            displayName
            featureType
            featureUnits
          }
          hasUnlimitedUsage
          usageLimit
          displayNameOverride
        }
        inheritedEntitlements {
          feature {
            refId
            displayName
          }
          hasUnlimitedUsage
          usageLimit
        }
        compatibleAddons {
          refId
          displayName
          pricePoints {
            billingPeriod
            amount
            currency
          }
        }
        defaultTrialConfig {
          duration
          units
        }
      }
      configuration {
        palette {
          primary
          textColor
          backgroundColor
        }
        customCss
        typography {
          fontFamily
          h1
          h2
          body
        }
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "productId": "product-main",
      "billingCountryCode": "US"
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "paywall": {
        "plans": [
          {
            "refId": "plan-free",
            "displayName": "Free",
            "description": "Get started for free",
            "pricingType": "FREE",
            "basePlan": null,
            "pricePoints": [],
            "entitlements": [
              {
                "feature": {
                  "refId": "feature-api-calls",
                  "displayName": "API Calls",
                  "featureType": "NUMBER",
                  "featureUnits": "call"
                },
                "hasUnlimitedUsage": false,
                "usageLimit": 1000,
                "displayNameOverride": null
              }
            ],
            "inheritedEntitlements": [],
            "compatibleAddons": [],
            "defaultTrialConfig": null
          },
          {
            "refId": "plan-pro",
            "displayName": "Pro",
            "description": "For growing teams",
            "pricingType": "PAID",
            "basePlan": null,
            "pricePoints": [
              {
                "billingPeriod": "MONTHLY",
                "amount": 99,
                "currency": "USD"
              },
              {
                "billingPeriod": "ANNUAL",
                "amount": 990,
                "currency": "USD"
              }
            ],
            "entitlements": [
              {
                "feature": {
                  "refId": "feature-api-calls",
                  "displayName": "API Calls",
                  "featureType": "NUMBER",
                  "featureUnits": "call"
                },
                "hasUnlimitedUsage": false,
                "usageLimit": 50000,
                "displayNameOverride": null
              },
              {
                "feature": {
                  "refId": "feature-sso",
                  "displayName": "Single Sign-On",
                  "featureType": "BOOLEAN",
                  "featureUnits": null
                },
                "hasUnlimitedUsage": false,
                "usageLimit": null,
                "displayNameOverride": null
              }
            ],
            "inheritedEntitlements": [],
            "compatibleAddons": [
              {
                "refId": "addon-seats",
                "displayName": "Extra Seats",
                "pricePoints": [
                  {
                    "billingPeriod": "MONTHLY",
                    "amount": 10,
                    "currency": "USD"
                  }
                ]
              }
            ],
            "defaultTrialConfig": {
              "duration": 14,
              "units": "DAYS"
            }
          }
        ],
        "configuration": {
          "palette": {
            "primary": "#6366F1",
            "textColor": "#1F2937",
            "backgroundColor": "#FFFFFF"
          },
          "customCss": null,
          "typography": {
            "fontFamily": "Inter",
            "h1": "32px",
            "h2": "24px",
            "body": "14px"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="GetPaywallInput" required>
  Input parameters for paywall retrieval

  <Expandable title="properties">
    <ParamField body="productId" type="String">
      Filter paywall to a specific product
    </ParamField>

    <ParamField body="customerId" type="String">
      Customer ID to personalize paywall (show applicable plans)
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID for multi-resource scenarios
    </ParamField>

    <ParamField body="billingCountryCode" type="String">
      Country code for regional pricing (e.g., "US", "DE")
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

## Return Type

Returns a `Paywall` object with:

| Field           | Type                 | Description                         |
| --------------- | -------------------- | ----------------------------------- |
| `plans`         | \[PaywallPlan]       | Plans formatted for paywall display |
| `configuration` | PaywallConfiguration | Visual customization settings       |

### PaywallPlan Fields

| Field                | Type                 | Description                |
| -------------------- | -------------------- | -------------------------- |
| `refId`              | String               | Plan reference ID          |
| `displayName`        | String               | Plan name                  |
| `description`        | String               | Plan description           |
| `pricingType`        | PricingType          | FREE, PAID, CUSTOM         |
| `pricePoints`        | \[PaywallPricePoint] | Pricing per billing period |
| `entitlements`       | \[Entitlement]       | Included entitlements      |
| `compatibleAddons`   | \[PaywallAddon]      | Available addons           |
| `defaultTrialConfig` | TrialConfig          | Trial configuration        |

## Common Use Cases

<AccordionGroup>
  <Accordion title="Public pricing page">
    Build a pricing page showing all available plans and their features.
  </Accordion>

  <Accordion title="Upgrade modal">
    Show upgrade options to existing customers with their current plan highlighted.
  </Accordion>

  <Accordion title="Feature comparison">
    Build feature comparison tables using entitlement data.
  </Accordion>
</AccordionGroup>

## Example: Rendering a Pricing Page

```javascript theme={null}
const { data } = await client.query({
  query: GET_PAYWALL,
  variables: {
    input: {
      productId: "product-main",
      customerId: user?.customerId // Optional for personalization
    }
  }
});

const { plans, configuration } = data.paywall;

// Render plans
plans.forEach(plan => {
  console.log(`${plan.displayName}: ${plan.description}`);

  // Show pricing
  plan.pricePoints.forEach(price => {
    console.log(`  ${price.billingPeriod}: ${price.amount} ${price.currency}`);
  });

  // Show features
  plan.entitlements.forEach(e => {
    if (e.hasUnlimitedUsage) {
      console.log(`  ✓ Unlimited ${e.feature.displayName}`);
    } else if (e.usageLimit) {
      console.log(`  ✓ ${e.usageLimit} ${e.feature.featureUnits}`);
    } else {
      console.log(`  ✓ ${e.feature.displayName}`);
    }
  });
});
```

## Related Operations

* [List Plans](/api-and-sdks/api-reference/queries/list-plans) - Raw plan data
* [Preview Subscription](/api-and-sdks/api-reference/mutations/preview-subscription) - Preview checkout pricing
* [Provision Subscription](/api-and-sdks/api-reference/mutations/provision-subscription) - Create subscription