Create a Plan

POST /subscriptionsplans/v1/plans

This request creates a plan, which you can then use to set up recurring subscription payments. When you create a plan, you specify values like the name of the plan, the amount of the payment, and how frequently the payment will be made (e.g., weekly or monthly). Each subscription request that you subsequently create will include an ID returned in the response to a plan creation request, as well as a paymentToken from a customer profile that you created with the Paysafe Customer Vault API.

To create a plan, you must initiate a POST request to the plans endpoint.

Prior to trying the example, you should replace the API key (after the -u) with the Test API key you received.

This table describes the elements used in a plan creation request.

Element Type Required Description
name string Yes This is your name for the plan.
description string This is a description of the plan.
amount number Yes This is the amount of the subscription payment, in minor units.
currencyCode string Yes This is the currency used for the plan amounts, e.g., USD or CAD.



Combine this value with the interval element to specify how often a subscription should be billed.




Combine this value with the frequency element to specify the number of time units between each subscription payment. For example:

  • To create a monthly plan, set frequency to MONTHLY and interval to 1.
  • To create a weekly plan, set frequency to DAILY and interval to 7.
  • To create a biannual plan (two payments in a year), set frequency to MONTHLY and interval to 6.



This is the date the plan will be available to use to set up a subscription.




Once the end date for the plan is reached, no new subscriptions can be created using that plan.

The response contains the additional elements in this table.

Element Type Description
id string This is the unique plan ID returned in the response. You will use it in your request to create a subscription.
links array of link objects

This contains a self link that can be used to fetch details about the request.

version number

This is the plan version, returned in the response. This will always be set to 1 when you create a new plan.

status enum

This is the status of the plan that was created. Possible values are:

  • INITIAL – The plan has been newly created. You cannot use a plan with this status to create a subscription. All elements can be changed when a plan is in this status.
  • ACTIVE – The plan can be used to create subscriptions. Once a plan is active, only some of its elements can be changed.
  • INACTIVE – The plan can not be updated or used to create a subscription.
  • EXPIRED– The plan endDate is now in the past. The plan can no longer be used to create a subscription.
creationTime UTC formatted date

This is the date and time the plan was created.

lastUpdatedTime UTC formatted date This is the date and time the plan was last updated.

For a complete list and description of the elements and values associated with a plan, consult the plan creation API request.

Did you find this page useful?