Create Subscription Plan

POST 
/plans

Creates a new subscription plan based on the provided details.

info

The request must provide the following header: x-api-key: {merchantKey}

In the request example below we are creating a new Prepaid Subscription Plan with a trial duration of 1 day ("trialDurationPeriod": 1, "trialDurationUnit": "day"). The consumer will be billed in total 4 times ("billingCycles": 4) every 1 month ("billingUnit": "month", "billingOccurrence": 1).

Request

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

x-api-key stringrequired

x-api-key: {merchantKey}

application/json

Body

required

name stringrequired

Name of the Subscription Plan

description stringrequired

Description of the Subscription Plan

recurrentAmount decimalrequired

Possible values: <= 60 characters

Amount to be billed recurrently

currencyIsoCode stringrequired

Currency code (e.g., EUR). Format: ISO 4217

trialDurationPeriod integer

Possible values: non-empty and <= 28 characters

Period of the trial. (e.g., 14 days - trialDurationUnit to be set to days).
When a Trial duration Unit is provided a trialDurationPeriod is required.

trialDurationUnit string

Possible values: [day, month, year]

Unit of the trial period. When a Trial Duration Period is provided a trialDurationUnit is required.

billingOccurrence integerrequired

Recurrence of the billing occurrences. (e.g., billingOccurrence=1 & billingUnit=month → charge the consumer every 1 month)

billingUnit stringrequired

Possible values: [day, month, year]

Unit of the billing recurrence.

billingCycles integerrequired

Possible 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.

prepaid boolean

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.

merchantMetadata stringnullable

Possible values: <= 255 characters

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.

Responses

201

Subscription plan created successfully

application/json

Schema

Schema

id string

Unique Identifier of the Subscription Plan. Format: SubscriptionPlan + - + <UUID>

createdAt date-time

Timestamp of when the Subscription Plan was created.

updatedAt date-time

Timestamp of when the Subscription Plan was last updated.

deletedAt date-timenullable

Timestamp of when the Subscription Plan was deleted (if applicable).

name stringrequired

Possible values: <= 255 characters

Name of the Subscription Plan.

description stringrequired

Possible values: <= 255 characters

Description of the Subscription Plan.

recurrentAmount decimalrequired

Possible values: <= 60 characters

Amount to be billed recurrently.

currencyIsoCode stringrequired

Possible values: >= 3 characters and <= 3 characters

Currency code. Format ISO 4217.

trialDurationPeriod integernullable

Possible values: >= 1 and <= 28

Period of the trial. MinValue 1, MaxValue 28.

trialDurationUnit stringnullable

Possible values: [day, month, year]

Unit of the trial period.

billingOccurrence integernullablerequired

Recurrence of the billing occurrences.

billingUnit stringnullablerequired

Possible values: [day, month, year]

Unit of the billing recurrence.

billingCycles integerrequired

Possible values: >= -1 and <= 120

Number of the billing occurrences. -1 for unlimited subscription.

prepaid boolean

Default value: true

The value would be true for pre-paid and false for post-paid.

merchantMetadata stringnullable

Possible values: <= 255 characters

Field that allows the merchant to store specific metadata linked with the subscription plan.

Example (from schema)

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

Example

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

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceId string

Internally generated trace_id for this error message so it can be found easily in the logs.

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

The property from the request object which the error is linked to.

context

object

A json object containing a list of predefined properties which are filled based on the error.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceId string

Internally generated trace_id for this error message so it can be found easily in the logs.

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

The property from the request object which the error is linked to.

context

object

A json object containing a list of predefined properties which are filled based on the error.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceId string

Internally generated trace_id for this error message so it can be found easily in the logs.

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

The property from the request object which the error is linked to.

context

object

A json object containing a list of predefined properties which are filled based on the error.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceId string

Internally generated trace_id for this error message so it can be found easily in the logs.

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

The property from the request object which the error is linked to.

context

object

A json object containing a list of predefined properties which are filled based on the error.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceId string

Internally generated trace_id for this error message so it can be found easily in the logs.

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

The property from the request object which the error is linked to.

context

object

A json object containing a list of predefined properties which are filled based on the error.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}

Loading...