Paywall

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

Query

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

Show properties

productId · String

Filter paywall to a specific product

customerId · String

Customer ID to personalize paywall (show applicable plans)

resourceId · String

Resource ID for multi-resource scenarios

billingCountryCode · String

Country code for regional pricing (e.g., “US”, “DE”)

environmentId · UUID

Environment ID

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

Public pricing page

Build a pricing page showing all available plans and their features.

Upgrade modal

Show upgrade options to existing customers with their current plan highlighted.

Feature comparison

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

Related Operations

• List Plans - Raw plan data
• Preview Subscription - Preview checkout pricing
• Provision Subscription - Create subscription