Copy page

Configuration

Plans

Plans are what the people who use your API choose: a free tier, a paid tier, a contact-us tier. Each one has its own limits, and the gateway enforces them on every call made with that plan's API key.

The portal shows them on /pricing (public) and /account/plans, where signed-in people subscribe, switch and cancel.

Turn plans on

apitogo.config.json
{
  "plans": {}
}

The plans themselves live in apitogo/plans.json. apitogo add plans creates it, and apitogo config adds plans interactively or with --plan (a plan with the same sku is replaced):

Code
apitogo config --plan '{"sku":"free","displayName":"Free"}'

plans.json

apitogo/plans.json
{
  "version": 1,
  "plans": [
    {
      "sku": "free",
      "displayName": "Free",
      "default": true,
      "limits": {
        "rateLimit": { "calls": 60, "periodSeconds": 60 },
        "quota": { "calls": 1000, "periodDays": 30 }
      }
    },
    {
      "sku": "pro",
      "displayName": "Pro",
      "priceAmount": 19,
      "priceCurrency": "usd",
      "billingInterval": "month",
      "featured": true,
      "limits": { "rateLimit": { "calls": 600, "periodSeconds": 60 } },
      "features": ["Email support", "Usage history"]
    },
    {
      "sku": "enterprise",
      "displayName": "Enterprise",
      "pricingModel": "custom",
      "priceLabel": "Let's talk"
    }
  ]
}

Field	What it does
sku	The plan's id, unique in the file
displayName	The name on the pricing page
default	The plan the portal offers first
limits	rateLimit (calls per periodSeconds) and quota (calls per periodDays)
priceAmount	The price; 0 or left out is free
priceCurrency	A currency code such as usd or eur
billingInterval	month or year
pricingModel	fixed (default) or custom for a contact-us plan
priceLabel	The text shown instead of a price, for a contact-us plan
featured	Shown as Popular
features	Extra lines on the plan's card
includedActions	The endpoints the plan includes, such as get:/orders; left out, all of them
sortOrder	The plan's place on the page; by default the file order

An unknown field is refused, so a typo never goes unnoticed.

What a pricing card shows

Each card lists, in this order:

1. The limits: 600 requests per minute, 1,000 requests / month
2. The plan's features
3. The endpoints it includes: the ones in includedActions, or every operation of the gateway

apitogo run shows the same cards as the deployed portal.

Paid plans

A plan with a price is paid through your own Stripe account. When the file has one, deploy asks for your Stripe secret key, then for the webhook signing secret, and stores both as project secrets. Set up Stripe for paid plans shows where to find them.

Free and contact-us plans need no Stripe at all.

The billing settings are only needed to change the defaults:

Code
"plans": {
  "billing": {
    "apiKey": "secret:STRIPE_API_KEY",
    "webhookSecret": "secret:STRIPE_WEBHOOK",
    "successUrl": "https://portal.example.com/account/plans",
    "cancelUrl": "https://portal.example.com/pricing"
  }
}

Selling paid plans needs the Starter or Professional hosting plan. On Free, deploy stops at a paid plan and says so.

Contact-us plans

"pricingModel": "custom" makes a plan you price per customer. Its card shows priceLabel (or Custom) and a Contact sales button, which opens a public form instead of a checkout. Each request is emailed to the project's sales contact, or to its owner.

Deploy

Code
apitogo deploy --only plans

deploys the plans, their limits on the gateway and the pricing page. A plain apitogo deploy does it together with everything else.

Hosting plans are something else

Kind	What it is	Where
Your plans	What your users pay you for using your API	apitogo/plans.json
APItoGo hosting plan	What you pay APItoGo: Free, Starter, Professional	apitogo project create --plan

Related

• Set up Stripe for paid plans
• Your customers' account pages
• Gateway