Create Subscription Plan

Last changes: 09-21-2023

Request parameters

FieldDescriptionTypeLengthMandatory
nameName of the Subscription PlanString255Yes
descriptionDescription of the Subscription PlanString255Yes
recurrentAmountAmount to be billed recurrentlyDouble18.2Yes
currencyIsoCodeCurrency code (E.g. EUR). Format: ISO 4217String3Yes
trialDurationPeriodPeriod 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 2Conditional
trialDurationUnitUnit of the trial period. Possible values: day, month, year.
When a Trial Duration Period is provided a trialDurationUnit is required.
String5Conditional
billingOccurrenceRecurrence of the billing occurrences.
(E.g. billingOccurrence=1 & billingUnit= month → charge the consumer every 1 month)
Int2Yes
billingUnitUnit of the billing recurrence. Possible values: day, month, year.String5Yes
billingCyclesPossible values : [-1 , 120]. Number of the billing occurrences.
The count of how many times the customer would be charged.
-1 could be sent for unlimited subscription.
Int2Yes
prepaidPossible 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.
Boolean5No
merchantMetadataIn 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.String255No

 

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.

 

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

FieldDescriptionTypeLengthMandatory
idUnique Identifier of the created Subscription Plan
Format: "SubscriptionPlan" + "-" + <UUID>
String53Yes
createdAtTimestamp of when the Subscription Plan was created
Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z
DateTime24Yes
updatedAtTimestamp of when the Subscription Plan was last updated
Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z
DateTime24Yes
deletedAtTimestamp of when the Subscription Plan was deleted (if applicable)
Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z
DateTime24Yes
nameName of the Subscription PlanString255Yes
descriptionDescription of the Subscription PlanString255Yes
recurrentAmountAmount to be billed recurrentlyDouble18.2Yes
currencyIsoCodeCurrency codeString3Yes
trialDurationPeriodPeriod of the trialInt 2Conditional
trialDurationUnitUnit of the trial periodString5Conditional
billingOccurrenceRecurrence of the billing occurrencesInt2Yes
billingUnitUnit of the billing recurrenceString5Yes
billingCyclesNumber of the billing occurrencesInt2Yes
prepaidThe value would be "true" for pre-paid and "false" for post-paidBoolean5No
merchantMetadataMerchant Metadata fields sent during the creation of the Subscription PlanString255No

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 }"
}