Search Overlay

Create a Plan

POST /subscriptionsplans/v1/plans

Create a Plan requests allow you to save the details of your various product payment plans with Paysafe so that customers can sign up for subscriptions/ recurring payment plans for these products.

Request Parameters

The request contains the following parameters:

Element Child Element Type Required Description
name   string
>= 4 chars
<= 50 chars
Yes The name of the plan.
description   string
>= 0 chars
<= 255 chars
No The description of the plan.
amount   number
>= 1
Yes

The amount of the plan, in minor units. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.

Note: If your merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

quantifiableAmount   number
>= 1
No

If subscription quantity is specified then this amount is multiplied by it. This is the quantifiableAmount of the plan, in minor units.

Note: The same restriction applies as in the amount field.

Example:
If you have a subscription for a service that costs $20 and 10 licenses for this service which cost $10 each (the price is specified in the quantifiableAmount field). The total amount that will be charged is calculated as such: amount + subscription.itemQuantity * quantifiableAmount($20 + 10 * $10)

retryPolicy   object No

If this object is present, you opt-in for smart retries.

Note: This setting applies to all subscriptions. Disabling an active retryPolicy will CANCEL all pending retries.

Example:
If you have frequency DAILY and number of retries 5. If a payment fails it will be retried every day until it is successful for a maximum of 5 days.

enabled boolean No If this field is true, then the frequency and numberOfRetries must be provided.
frequency

string

No

The frequency of the retry attempts for the failed payment.

Allowed value:
DAILY

numberOfRetries number
>= 1
<= 10
No Maximum number of retries that will be attempted for the failed payment.
setupFee   number
>= 1
No

The fee used to set up a plan, which is charged only once at the beginning.

This is the amount of the plan, in minor units. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.

Note: If your  merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

billingCycle   object Yes

This is the setup for the billing cycle.

Example:
For example if you have MONTHLY frequency, interval of 1 and numberOfCycles 12, this means that you will be billed every month for 1 year.

frequency

string

Yes

Frequency shows how often the payment for the plan will be executed.

Allowed values:

  • DAILY
  • MONTHLY
  • YEARLY
interval number
>= 1
<= 365
Yes

The number of intervals after which a subscriber is billed. This field is required when a plan is created.

  • DAILY - 365 is the maximum value for interval if the frequency is DAILY.
  • MONTHLY - 12 is the maximum value for interval if the frequency is MONTHLY.
  • YEARLY - 1 is the maximum value for interval if the frequency is YEARLY.
numberOfCycles number
>= 0
<= 99
Yes The number of times this billing cycle is executed. Billing cycles can be executed infinite times (value of 0 for numberOfCycles) or a finite number of times (value between 1 and 99 for numberOfCycles). This field is required when a plan is created.
startDate   string<date> No

Start date of the plan. Date format = YYYY-MM-DD, ISO 8601 expected. UTC Date Format. You cannot create subscriptions for this plan before this date.

Note: The start date CANNOT be in the past.

endDate   string<date> No End date of the plan. Date format = YYYY-MM-DD, ISO 8601 expected. UTC Date Format. You cannot create subscriptions for this plan after this date. Not providing an end date means that the plan can be used indefinitely.
subscriptionBehaviourOnDeactivation   string No

This property controls what will happen with the plan's subscriptions when it is deactivated.

The property must be provided either on plan creation or when its status is set to INACTIVE.

Allowed values:

  • DO_NOTHING - When a plan is deactivated it will not affect the subscriptions associated with it.
  • TERMINATE_IMMEDIATELY - When a plan is deactivated the subscriptions associated with it will be terminated immediately.
  • TERMINATE_AFTER_NEXT_BILLING - When a plan is deactivated the subscriptions associated with it will be terminated after their next billing.

Example:
If the value of subscriptionBehaviourOnDeactivation is TERMINATE_IMMEDIATELY, then the subscriptions of this plan will be set to status CANCELLED and no further billing will occur.

status  

string

No

Allowed values:

  • INITIAL - This is the status in which you can update all fields of the plan.
  • ACTIVE - This is the status in which you can create subscriptions.
currencyCode   string Yes

The currency code, for example, USD or CAD. See Currency Codes.

Note: When creating a subscription, the currencyCode specified in the plan must match the processing currency of the account.

Example:
USD

trialPeriod   object Yes

Trial period will be applied only at the beginning of the subscription.

Example:
If the trialPeriod is with amount 0 then for the duration of it, there wont be any billing.

numberOfCycles number
>= 1
Yes How many cycles the trial period will last.
frequency

string

 

Yes

Frequency shows how often the trial payment for the plan will be executed.

Allowed value:
MONTHLY

amount number Yes

The amount of the trial period, in minor units. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.

Note: If your merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

Response Parameters

The response parameters that are not included in the request are described below:

Element Child Element Type Description
creationTime   string yyyy-MM-dd'T'HH:mm:ss'Z'
lastdUpdatedTime   string yyyy-MM-dd'T'HH:mm:ss'Z'
id   string<uuid>