Subscribing to a plan

A developer subscribes by opening a product in your API Portal, choosing a plan, and running the subscription wizard. The plan decides what the wizard does next and what status the subscription starts in.

What are the steps in the subscription wizard?

The wizard moves through up to four steps: choose a plan, add information, checkout, and a confirmation. Steps that do not apply to the chosen plan are skipped automatically.

The final button reads Subscribe, Request approval on a plan with an approval group, or Proceed to checkout on a paid plan. The subscription name must be at least three characters, and required fields must be filled in. Subscribing needs Full API keys access in the team.

The wizard checks the plan against your gateway when the developer picks it. If the check fails, the wizard shows an error and blocks subscribing to that plan.

How does subscribing to a free plan work?

A free plan skips checkout. The subscription is created Active, and the wizard opens the new subscription, where the developer creates credentials.

Contract and prepaid plans also skip checkout. A prepaid plan draws down the team's credit balance instead; see Billing and credits.

How does subscribing to a paid plan work?

The subscription is created as Pending Payment, and the developer goes to Stripe checkout. When Stripe confirms the payment, the subscription becomes Active and credentials can be created.

Checkout runs for the graduated, volume, flat fee, and flat fee with overage pricing models. It needs Stripe connected to your account; see Connect Stripe. If the developer leaves checkout before paying, the subscription stays Pending Payment, and a Checkout button on the subscription resumes it.

What happens when a plan requires approval?

When a plan has an approval group and no sandbox, the subscription is created as Pending Approval. The wizard shows This plan requires an approval. Credentials can't be created until your team approves the request.

Your team approves or declines from Consumers, Requests in the dashboard, or from the subscription's own page. See Requests and approvals.

On a paid plan, approval moves the subscription to Pending Payment. The developer then clicks Checkout on the subscription and pays, and the subscription becomes Active.

What happens on a sandbox plan?

A sandbox plan starts the developer in the sandbox. The subscription is created Active in the Sandbox phase, with no charge. The developer builds against sandbox credentials, then submits for review. Production credentials, and payment on a paid plan, follow your team's approval.

On a sandbox plan with an approval group, the wizard still shows the approval notice and the Request approval button. The subscription starts in the sandbox anyway, and the approval applies to the move to production. See From sandbox to production.

What about a contract plan with an external link?

A contract plan can carry an external call-to-action link, with its own button text. When it does, the wizard opens that link in a new tab instead of creating a subscription, so the developer reaches your sales or contract flow.

Can a plan limit how many subscriptions a team holds?

Yes. A plan can set a maximum number of subscriptions per team. When the team reaches it, the wizard shows Reached the maximum number of subscriptions and blocks another subscription to that plan. Cancelled and expired subscriptions don't count toward the limit.

Below the limit, if the team already has a subscription to the plan, the wizard shows Subscription to this plan already exists but still allows another.

What does each subscription status mean?

A subscription holds one status at a time, shown on the subscription in the API Portal. The status decides whether credentials can be created and whether they work.

How does a developer change, upgrade, or cancel a subscription?

From the subscription's page. Change Plan moves to another plan of the same product when the product allows plan changes. An upgrade banner offers a newer version of the current plan. Cancel Subscription schedules a cancellation for a date the developer picks.

A plan qualifies for Change Plan when it sits on the same side of the sandbox boundary, shares a currency with the current plan unless either plan is free, and has no custom properties. The change dialog warns that billing can change and new credentials are generated. On a paid plan the developer goes to checkout.

The upgrade dialog says whether the credentials stay the same or are regenerated, and whether pricing changes.

To cancel, the developer picks a date, or uses Select end of period date on a paid plan. The subscription shows Cancellation Pending until that date. If the date is today, it is cancelled within an hour.

Troubleshooting

Where to next