Create Subscription Plan

Last changes: 11-29-2021

Request parameters

Field	Description	Type	Length	Mandatory
name	Name of the Subscription Plan	String	255	Yes
description	Description of the Subscription Plan	String	255	Yes
recurrentAmount	Amount to be billed recurrently	Double	18.2	Yes
currencyIsoCode	Currency code (E.g. EUR). Format: ISO 4217	String	3	Yes
trialDurationPeriod	Period of the trial. (E.g. 14 days - trialDurationUnit to be set to "days"). MinValue: 1 - MaxValue: 28. When a Trial duration Unit is provided a trialDurationPeriod is required.	Int	2	Conditional
trialDurationUnit	Unit of the trial period. Possible values: day, month, year. When a Trial Duration Period is provided a trialDurationUnit is required.	String	5	Conditional
billingOccurrence	Recurrence of the billing occurrences. (E.g. billingOccurrence=1 & billingUnit= month → charge the consumer every 1 month)	Int	2	Yes
billingUnit	Unit of the billing recurrence. Possible values: day, month, year.	String	5	Yes
billingCycles	Possible values : [-1 , 12]. Number of the billing occurrences. The count of how many times the customer would be charged. -1 could be sent for unlimited subscription.	Int	2	Yes
prepaid	Possible values: true, false. Sending "true" would create a pre-paid plan, the value "false" would create a post-paid plan. If no value is sent it would be always set to "true" by default.	Boolean	5	No
merchantMetadata	In this field you could pass information that you deem important to be saved on a subscription plan level which is not covered by the fields above.	String	255	No

In the below request we are creating a new PrePaid Subscription Plan with a trial duration of 1 day.
The consumer will be billed in total 4 times every 1 month.

The request must provide the followng header:

x-api-key: {merchantKey}

Request sample

Path:: Path: POST {Base URL}/plans
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "name": "Premium",
  "description": "Premium sub for only 90.99 EUR!",
  "recurrentAmount": 90.99,
  "currencyIsoCode": "EUR",
  "trialDurationPeriod": 1,
  "trialDurationUnit": "day",
  "billingOccurrence": 1,
  "billingUnit": "month",
  "billingCycles": 4,
  "prepaid": true,
  "merchantMetadata": "{\"orderId\": 1asd265jh4, \"usageTracking\": false, \"referenceId\": s125jkwh2321 }"
}

Response parameters

Field	Description	Type	Length	Mandatory
id	Unique Identifier of the created Subscription Plan Format: "SubscriptionPlan" + "-" + <UUID>	String	53	Yes
createdAt	Timestamp of when the Subscription Plan was created Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z	DateTime	24	Yes
updatedAt	Timestamp of when the Subscription Plan was last updated Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z	DateTime	24	Yes
deletedAt	Timestamp of when the Subscription Plan was deleted (if applicable) Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z	DateTime	24	Yes
name	Name of the Subscription Plan	String	255	Yes
description	Description of the Subscription Plan	String	255	Yes
recurrentAmount	Amount to be billed recurrently	Double	18.2	Yes
currencyIsoCode	Currency code	String	3	Yes
trialDurationPeriod	Period of the trial	Int	2	Conditional
trialDurationUnit	Unit of the trial period	String	5	Conditional
billingOccurrence	Recurrence of the billing occurrences	Int	2	Yes
billingUnit	Unit of the billing recurrence	String	5	Yes
billingCycles	Number of the billing occurrences	Int	2	Yes
prepaid	The value would be "true" for pre-paid and "false" for post-paid	Boolean	5	No
merchantMetadata	Merchant Metadata fields sent during the creation of the Subscription Plan	String	255	No

Response sample

Status Code:: 201 (Created)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "SubscriptionPlan-12033695-99d8-4dc6-bf51-db64ef27620b",
  "createdAt": "2021-03-17T17:18:53.01Z",
  "updatedAt": "2021-03-17T17:18:53.01Z",
  "deletedAt": null,
  "name": "Premium",
  "description": "Premium sub for only 90.99 EUR!",
  "recurrentAmount": 90.99,
  "currencyIsoCode": "EUR",
  "trialDurationPeriod": 1,
  "trialDurationUnit": "day",
  "billingUnit": "month",
  "billingOccurrence": 1,
  "billingCycles": 4,
  "prepaid": true,
  "merchantMetadata": "{\"orderId\": 1asd265jh4, \"usageTracking\": false, \"referenceId\": s125jkwh2321 }"
}

For error handling, please refer to this section.

Previous

Next