Skip to main content

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}

Bodyrequired

    namestringrequired

    Name of the Subscription Plan

    Example: Premium
    descriptionstringrequired

    Description of the Subscription Plan

    Example: Premium sub for only 90.99 EUR!
    recurrentAmountnumber<decimal>required

    Amount to be billed recurrently

    Possible values: <= 60 characters

    Example: 90.99
    currencyIsoCodestringrequired

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

    Example: EUR
    trialDurationPeriodinteger

    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.

    Possible values: non-empty and <= 28 characters

    Example: 1
    trialDurationUnitstring

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

    Possible values: [day, month, year]

    Example: day
    billingOccurrenceintegerrequired

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

    Example: 1
    billingUnitstringrequired

    Unit of the billing recurrence.

    Possible values: [day, month, year]

    Example: month
    billingCyclesintegerrequired

    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.

    Example: 4
    prepaidboolean

    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.

    Possible values: [true, false]

    Example: true
    merchantMetadatastringnullable

    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.

    Possible values: <= 255 characters

    Example: {"orderId": 1asd265jh4, "usageTracking": false, "referenceId": s125jkwh2321 }

Responses​

Subscription plan created successfully

Schema
    idstring

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

    Example: SubscriptionPlan-12033695-99d8-4dc6-bf51-db64ef27620b
    createdAtstring<date-time>

    Timestamp of when the Subscription Plan was created.

    Example: 2021-03-17T17:18:53.01Z
    updatedAtstring<date-time>

    Timestamp of when the Subscription Plan was last updated.

    Example: 2021-03-17T17:18:53.01Z
    deletedAtstring<date-time>nullable

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

    namestringrequired

    Name of the Subscription Plan.

    Possible values: <= 255 characters

    Example: Premium
    descriptionstringrequired

    Description of the Subscription Plan.

    Possible values: <= 255 characters

    Example: Premium sub for only 90.99 EUR!
    recurrentAmountnumber<decimal>required

    Amount to be billed recurrently.

    Possible values: <= 60 characters

    Example: 90.99
    currencyIsoCodestringrequired

    Currency code. Format ISO 4217.

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

    Example: EUR
    trialDurationPeriodintegernullable

    Period of the trial. MinValue 1, MaxValue 28.

    Possible values: >= 1 and <= 28

    Example: 1
    trialDurationUnitstringnullable

    Unit of the trial period.

    Possible values: [day, month, year]

    Example: day
    billingOccurrenceintegernullablerequired

    Recurrence of the billing occurrences.

    Example: 1
    billingUnitstringnullablerequired

    Unit of the billing recurrence.

    Possible values: [day, month, year]

    Example: month
    billingCyclesintegerrequired

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

    Possible values: >= -1 and <= 120

    Example: 4
    prepaidboolean

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

    Default value: true
    Example: true
    merchantMetadatastringnullable

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

    Possible values: <= 255 characters

    Example: {"orderId": "1asd265jh4", "usageTracking": false, "referenceId": "s125jkwh2321"}
 Imprint
|
Data protection and privacy
© 2026 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.