Products
Anatomy of a plan
A plan sits inside a product and defines the APIs, access, security, limits, and price for one tier. This page covers the plan tabs, statuses, publishing, what can block it, and how new versions replace old ones.
A plan sits inside a product and defines one tier: the APIs it includes, how access is secured, its limits, and its price. You open a plan from a product's API Plans tab, then work through its tabs. See API Products for how products and plans fit your business.
What are the tabs on a plan?
A plan is configured across a row of tabs. Each tab owns one part of the plan, and they save together when you choose Save Changes in the plan header.
| Tab | What it configures |
|---|---|
| Details | The plan's description, how long subscriptions last, how many subscriptions a customer may hold, and a link that takes customers straight to subscribing. |
| APIs | The APIs in the plan, and its coupling: Gateway-bound or Catalog-bound. |
| Access Control | Scope assignments per API. |
| Security | The authentication method, which sets the credential subscribers receive. |
| Documentation | The API specifications and SDKs for the plan, and whether anyone or only signed-in users can read them. |
| Limits | Rate limits. Disabled on Catalog-bound plans. |
| Approvals | The approval group that reviews subscriptions, when the plan needs approval. |
| Monetization | The plan's pricing and billing. |
| Custom Properties | Extra properties added to each new subscription, shown to your team and the subscriber. |
| Onboarding | The partner onboarding pipeline: the sandbox flow, a submission form and auto-enrollment. Available when Sandbox & Partner Pipeline is enabled for your account. |
| Publish | Publishing the plan and managing its versions. |
The Access Control tab shows only when scope-based access control is enabled for your account and at least one Authorization Server is connected. The Limits tab is disabled on Catalog-bound plans, because rate limits run on a single gateway.
What do the plan statuses mean?
A plan has one of five statuses. The header toggle switches a plan between Inactive and Active; versioning produces the others.
| Status | Meaning |
|---|---|
| Draft | A new version in progress. Publish it from its Publish tab. |
| Inactive | Saved but not offered to developers. |
| Active | Published and offered in your API Portal. |
| Deprecated | Replaced by a newer published version. The API Portal no longer lists it. Existing subscriptions continue, unless you set a date by which subscribers must migrate. |
| Archived | Retired. It takes no new subscriptions and can no longer be edited. |
A product needs at least one Active plan before the product itself can be published.
How do I publish a plan?
Open the plan's Publish tab and choose Confirm & Publish this version, then Publish version in the dialog. The button appears on a draft version, and on a plan's first version while it is Inactive.
- Open the plan and select the Publish tab.
- Review the comparison with an earlier version under Compare to version, if the plan has one.
- Choose Confirm & Publish this version.
- In the Ready to publish version dialog, choose Publish version.
Publishing a first version sets it to Active and saves the plan. Once a plan is Active, the Publish tab shows Save Changes in place of the publish button.
Why can't I publish or activate this plan?
The plan is missing something it needs. Hover the disabled Confirm & Publish this version button to see what. These checks don't stop you saving the plan.
| What you see | What to do |
|---|---|
| Confirm & Publish this version is disabled, and hovering it shows "Choose a coupling mode to save this plan." | Pick Gateway-bound or Catalog-bound on the APIs tab. Despite the wording, you can save; it is publishing that waits. See Add APIs and choose coupling. |
| Confirm & Publish this version is disabled, and hovering it shows "Add at least one API from the selected gateway to save this plan." | On a Gateway-bound plan, add at least one API from the selected gateway on the APIs tab. Here too you can save; publishing waits. |
| A yellow banner reads "This plan cannot be activated yet.", and the header toggle is disabled | The plan is bound to an Authorization Server and has no security method. Follow the banner's Security tab link and pick one. The same reason shows on Confirm & Publish this version. See Set a plan's security level. |
| The banner says the Authorization Server "has not reported which security methods it supports" | Refresh the server's discovery document, then pick a method on the Security tab. |
| Confirm & Publish this version is disabled with no message | Check that the header button does not read Errors, and that your role can manage products. On plans with scope-based access control, check that the Access Control tab has an Authorization Server picked and no conflict to resolve. |
When do I create a new plan version?
When you need to change a plan that already has active or pending subscriptions. A new version is a draft copy you can edit freely, while current subscribers stay on the version they have.
While a plan has active or pending subscriptions, a banner at the top of the plan says so, with a Create button. Most of that version's settings are locked, including its APIs and coupling, access control, security method, pricing and rate limits.
- Choose Create in the banner. You can also choose New version from the plan card's menu on the product's API Plans tab.
- Edit the new Draft version.
- Publish it from its Publish tab.
A plan has at most one draft at a time. When a draft exists, the plan card's menu reads Open draft version and opens it.
What happens when I publish a new version?
Publishing a new version deprecates every Active version of the plan. Deprecated versions drop out of your API Portal, which lists Active plans only. Only forcing subscribers to migrate by a date is optional.
When the plan has earlier versions, the Publish tab asks Deprecate previous version on publish?:
- Off (the default): Existing users will be able to continue to use their current plans indefinitely. Their subscriptions to the deprecated version keep working.
- On: Subscribers must migrate to the newest version by this date, or their subscriptions will become inactive. Pick the date under Deprecate previous version on. It can be today or later, not in the past. Once that date passes, subscriptions to the previous version expire.
Either way, your API Portal offers only the new version to new subscribers. If email notifications are available for your account and an email sender is set up, you can also tell current subscribers about the new version, using one of your email templates.
Where to next
Add APIs and choose coupling
Add APIs to the plan and choose Gateway-bound or Catalog-bound.
Set a plan's security level
Choose the authentication a subscriber uses, from API key to OAuth2.
Set rate limits on a plan
Cap throughput per subscriber on Gateway-bound plans.
Attach documentation to a plan
Add versioned docs and publish SDKs for the plan.
Assign scopes to a plan
Set each scope to Active, Optional, or Restricted on the Access Control tab.