Skip to main content
Retrieves plan data formatted specifically for building pricing pages and paywall components.

​
Query

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

{
  "input": {
    "productId": "product-main",
    "billingCountryCode": "US"
  }
}

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

​
Parameters

​
input
GetPaywallInput
required
Input parameters for paywall retrieval

​
Return Type

Returns a Paywall object with:
FieldTypeDescription
plans[PaywallPlan]Plans formatted for paywall display
configurationPaywallConfigurationVisual customization settings

​
PaywallPlan Fields

FieldTypeDescription
refIdStringPlan reference ID
displayNameStringPlan name
descriptionStringPlan description
pricingTypePricingTypeFREE, PAID, CUSTOM
pricePoints[PaywallPricePoint]Pricing per billing period
entitlements[Entitlement]Included entitlements
compatibleAddons[PaywallAddon]Available addons
defaultTrialConfigTrialConfigTrial configuration

​
Common Use Cases

Build a pricing page showing all available plans and their features.
Show upgrade options to existing customers with their current plan highlighted.
Build feature comparison tables using entitlement data.

​
Example: Rendering a Pricing Page

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}`);
    }
  });
});