Skip to main content

Create Subscription

POST 

/subscriptions

Creates a new subscription based on the provided details.

info

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

When the Subscription Plan has trial details (e.g., 14 days), the Subscription trial would start on the Subscription's startDate, and would end after the trial period defined on the plan (e.g., 14 days).

The nextBillingDate is either on the beginning of the period in case of a pre-paid subscription or at the end of a period in case of a post-paid subscription. Please note that if the Subscription Plan has trial details, the period would start right after it, meaning that the end customer would never be charged for a trial period.

info

The automated calculation works with calendar days.

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

    planIdstringrequired

    Unique identifier of an existing subscription plan.

    Possible values: <= 53 characters

    Example: SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9a
    customerAccountIdstringrequired

    Unique identifier for the customer in the merchant's system.

    Possible values: <= 125 characters

    Example: customer1-b496-4a3a-bc8f-d2a55af5794a
    startDatestring<date-time>required

    The start date of the subscription that defines when the subscription becomes active. The value must be a valid timestamp and is evaluated in UTC. SmartPay supports either the current UTC date or a future one. The Subscription module operates in UTC to ensure consistency across different time zones. Merchants must provide a startDate that represents either the current date or a future date in UTC; it cannot be in the past. If a timestamp is provided in the local time zone (e.g., 2025-06-11T01:32:25.00+02:00 for Central European Time), the system automatically offsets it to UTC (e.g., 2025-06-10T23:32:25.00Z). If the resulting UTC date is in the past, the request will be rejected. Merchants operating in local timezones must ensure that their intended startDate corresponds to today or a future date in UTC.

    Possible values: <= 29 characters, Value must match regular expression yyyy-MM-ddTHH:MM:SSZ

    Example: 2021-03-31T15:30:44.18-08:00
    timezonestring

    TZ database name in List of TZ Database Time Zones.

    Possible values: <= 32 characters

    Example: Europe/Berlin
    externalMerchantIdstringnullable

    External reference identifier assigned by the merchant.

    Possible values: <= 255 characters

    Example: MC_21507252
    merchantMetadatastringnullable

    JSON metadata for merchant-specific details.

    Possible values: <= 255 characters

    Example: {"clientId": 1248052792, "preference": 120}
    billingAddress objectrequired

    Billing or shipping address of the consumer. Please refer to Data Model for details.

    addressLine1stringrequired

    Address line 1.

    Possible values: <= 60 characters

    Example: Leopoldstrasse
    addressLine2stringnullable

    Address line 2.

    Possible values: <= 60 characters

    addressLine3stringnullable

    Address line 3.

    Possible values: <= 60 characters

    numberstringrequired

    House number/building number.

    Possible values: <= 10 characters

    Example: 244
    citystringrequired

    City name of the address.

    Possible values: <= 50 characters

    Example: Munich
    postCodestringrequired

    Postal code of the address.

    Possible values: <= 10 characters

    Example: 80807
    countryCodestringrequired

    Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

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

    Example: DE
    statestringnullable

    State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

    Possible values: <= 3 characters

    shippingAddress objectnullable

    Billing or shipping address of the consumer. Please refer to Data Model for details.

    addressLine1stringrequired

    Address line 1.

    Possible values: <= 60 characters

    Example: Leopoldstrasse
    addressLine2stringnullable

    Address line 2.

    Possible values: <= 60 characters

    addressLine3stringnullable

    Address line 3.

    Possible values: <= 60 characters

    numberstringrequired

    House number/building number.

    Possible values: <= 10 characters

    Example: 244
    citystringrequired

    City name of the address.

    Possible values: <= 50 characters

    Example: Munich
    postCodestringrequired

    Postal code of the address.

    Possible values: <= 10 characters

    Example: 80807
    countryCodestringrequired

    Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

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

    Example: DE
    statestringnullable

    State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

    Possible values: <= 3 characters

    consumer objectrequired

    Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
    Conditional. Can be present if businessConsumer is missing from the request.

    firstNamestringrequired

    First name of the consumer.

    Possible values: <= 60 characters

    Example: John
    lastNamestringrequired

    Last name of the consumer.

    Possible values: <= 60 characters

    Example: Smith
    middleNamestringnullable

    Middle name of the consumer.

    Possible values: <= 60 characters

    Example: .
    emailAddressstring<email>required

    Email address of the customer.

    Possible values: <= 255 characters

    Example: john.smith@smithentreprise.com
    titlestring

    Title of the consumer.

    Possible values: <= 3 characters, [Mr, Mrs, Ms]

    Example: Mr
    culturestring

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.

    Possible values: <= 5 characters

    Example: en-de
    dateOfBirthstring<date>required

    Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.

    Example: 1995-01-26
    genderstring

    Gender of the consumer.

    Possible values: [M, F, D]

    Example: M
    mobilePhonestring

    Mobile phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    homePhonestring

    Home phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    workPhonestring

    Work phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    taxIdstringnullable

    Tax ID of the consumer.

    Possible values: <= 30 characters

    Example: DE1927456229
    businessConsumer objectnullablerequired

    Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
    Conditional. Can be present if consumer is missing from the request.

    companyNamestringrequired

    Company legal entity name.

    Possible values: <= 100 characters

    Example: Smith Enterprises Ltd.
    companyTypestringrequired

    Company legal entity type (e.g., GmbH).

    Possible values: <= 100 characters

    Example: GmbH
    emailAddressstring<string>required

    Customer's email address.

    Possible values: <= 255 characters

    Example: contact@smithenterprises.com
    taxIdstringnullable

    Tax identification number.

    Possible values: <= 30 characters

    Example: DE123456789
    culturestringnullable

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.

    Possible values: <= 5 characters

    Example: en-DE
    companyRegistrationNumberstringnullable

    Company registration number

    Possible values: <= 50 characters

    Example: HRB 123456
    companyRegistrationCountryCodestringnullable

    ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.

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

    Example: DE

Responses​

Subscription created successfully

After creation, the subscription is in "status": "created", meaning it is updatable and not yet active or pending. In order to move it to further statuses, the end customer have to provide their payment option details through the Subscription SDK. Once the payment option details are provided a Billing Agreement is created and linked to the subscription, which moves to the pending status.

This is the payment instrument details that the consumer provided, after consent with the Merchant, to be used for their specific subscription. The billing agreement includes the Stored Payment Option details that the consumer provided within our Subscription SDK. The Stored Payment Option could be added or deleted only through the Subscription SDK.

info

Each time a payment option is changed a new billing agreement is created. Please refer to Data Model for object details.

Schema
    idstringrequired

    Unique subscription ID assigned by the system.

    Possible values: <= 49 characters

    Example: Subscription-39ab7cc3-57d7-42d7-ad24-a7b8a4164880
    createdAtstring<date-time>required

    Timestamp of when the subscription was created.

    Possible values: <= 24 characters

    Example: 2024-10-31T14:30:10.51Z
    updatedAtstring<date-time>required

    Timestamp of when the subscription was last updated.

    Possible values: <= 24 characters

    Example: 2024-10-31T14:30:10.51Z
    deletedAtstring<date-time>nullablerequired

    Timestamp of when the subscription was deleted (if applicable).

    Possible values: <= 24 characters

    planIdstringrequired

    Identifier of the subscription plan associated with this subscription.

    Possible values: <= 53 characters

    Example: SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10
    statusstringrequired

    Current status of the subscription.

    Possible values: [created, pending, trial, active, overdue, canceled, expired, paused]

    Example: created
    payment objectnullablerequired
    descriptionstring

    Description of the payment.

    Possible values: <= 255 characters

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

    Amount charged per billing cycle.

    Possible values: <= 60 characters

    Example: 100
    currencyIsoCodestring

    ISO currency code for the payment.

    Possible values: <= 3 characters

    Example: EUR
    startDatestring<date-time>required

    The start date of the subscription that defines when the subscription becomes active. The value must be a valid timestamp and is evaluated in UTC. SmartPay supports either the current UTC date or a future one. The Subscription module operates in UTC to ensure consistency across different time zones. Merchants must provide a startDate that represents either the current date or a future date in UTC; it cannot be in the past. If a timestamp is provided in the local time zone (e.g., 2025-06-11T01:32:25.00+02:00 for Central European Time), the system automatically offsets it to UTC (e.g., 2025-06-10T23:32:25.00Z). If the resulting UTC date is in the past, the request will be rejected. Merchants operating in local timezones must ensure that their intended startDate corresponds to today or a future date in UTC.

    Possible values: <= 29 characters, Value must match regular expression yyyy-MM-ddTHH:MM:SSZ

    Example: 2021-03-31T15:30:44.18-08:00
    trialStartDatestring<date>nullablerequired

    Start date of the trial period, if applicable.

    Possible values: <= 10 characters

    Example: 2024-10-31
    trialEndDatestring<date>nullablerequired

    End date of the trial period, if applicable.

    Possible values: <= 10 characters

    Example: 2024-11-30
    nextBillingDatestring<date>nullablerequired

    Date of the next scheduled billing.

    Possible values: <= 10 characters

    Example: 2024-11-30
    billingCyclesRemainingintegernullablerequired

    Number of remaining billing cycles.

    Possible values: <= 2 characters, >= 0

    Example: 4
    customerAccountIdstringrequired

    Unique identifier assigned by the merchant to the customer.

    Possible values: <= 125 characters

    Example: BSTEST01
    merchantMetadatastringnullable

    JSON metadata containing merchant-specific details.

    Possible values: <= 255 characters

    Example: {"usage": 250, "client": 1248052792, "monitor": true }
    externalMerchantIdstringnullable

    External identifier for reference purposes.

    Possible values: <= 255 characters

    Example: client_21507252
    billingAgreement objectnullablerequired

    Billing agreement details, if applicable.

    idstringrequired

    Unique Identifier of the Billing Agreement. Format: BillingAgreement + - + <UUID>

    Possible values: <= 50 characters

    Example: BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771
    paymentObjectIdstringrequired

    PaymentObject used for billing this subscription.

    Example: 8ac7a49f8609e07601860ca28ce656ed
    billingAgreementDatestring<date-time>required

    Date when the billing agreement was created.

    Possible values: <= 24 characters

    Example: 2021-01-26T14:29:05.994Z
    namestringrequired

    Display name of the payment option which has been stored.

    Possible values: <= 255 characters

    Example: Mastercard
    codestringrequired

    Code of the payment option which has been stored.

    Possible values: <= 255 characters

    Example: MSTRCRD
    carrierNumberstring

    Masked carrier number of the payment instrument which has been stored.

    Example: 401288****1881
    isExpiredbooleanrequired

    Indicates if a card used as a payment option is expired or not.

    Possible values: [true, false]

    Example: false
    expiryDatestringrequired

    If a card is used as a payment option, this shows its expiry date.

    Possible values: <= 7 characters, Value must match regular expression ^(0[1-9]|1[0-2])/[0-9]{4}$

    Example: 04/2024
    storedPaymentOptionDataobjectnullable

    Additional data related to the stored payment option.

    billingAddress objectrequired

    Billing or shipping address of the consumer. Please refer to Data Model for details.

    addressLine1stringrequired

    Address line 1.

    Possible values: <= 60 characters

    Example: Leopoldstrasse
    addressLine2stringnullable

    Address line 2.

    Possible values: <= 60 characters

    addressLine3stringnullable

    Address line 3.

    Possible values: <= 60 characters

    numberstringrequired

    House number/building number.

    Possible values: <= 10 characters

    Example: 244
    citystringrequired

    City name of the address.

    Possible values: <= 50 characters

    Example: Munich
    postCodestringrequired

    Postal code of the address.

    Possible values: <= 10 characters

    Example: 80807
    countryCodestringrequired

    Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

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

    Example: DE
    statestringnullable

    State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

    Possible values: <= 3 characters

    shippingAddress objectnullablerequired

    Billing or shipping address of the consumer. Please refer to Data Model for details.

    addressLine1stringrequired

    Address line 1.

    Possible values: <= 60 characters

    Example: Leopoldstrasse
    addressLine2stringnullable

    Address line 2.

    Possible values: <= 60 characters

    addressLine3stringnullable

    Address line 3.

    Possible values: <= 60 characters

    numberstringrequired

    House number/building number.

    Possible values: <= 10 characters

    Example: 244
    citystringrequired

    City name of the address.

    Possible values: <= 50 characters

    Example: Munich
    postCodestringrequired

    Postal code of the address.

    Possible values: <= 10 characters

    Example: 80807
    countryCodestringrequired

    Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

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

    Example: DE
    statestringnullable

    State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

    Possible values: <= 3 characters

    consumer objectrequired

    Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
    Conditional. Can be present if businessConsumer is missing from the request.

    firstNamestringrequired

    First name of the consumer.

    Possible values: <= 60 characters

    Example: John
    lastNamestringrequired

    Last name of the consumer.

    Possible values: <= 60 characters

    Example: Smith
    middleNamestringnullable

    Middle name of the consumer.

    Possible values: <= 60 characters

    Example: .
    emailAddressstring<email>required

    Email address of the customer.

    Possible values: <= 255 characters

    Example: john.smith@smithentreprise.com
    titlestring

    Title of the consumer.

    Possible values: <= 3 characters, [Mr, Mrs, Ms]

    Example: Mr
    culturestring

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.

    Possible values: <= 5 characters

    Example: en-de
    dateOfBirthstring<date>required

    Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.

    Example: 1995-01-26
    genderstring

    Gender of the consumer.

    Possible values: [M, F, D]

    Example: M
    mobilePhonestring

    Mobile phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    homePhonestring

    Home phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    workPhonestring

    Work phone of the customer.

    Possible values: <= 30 characters

    Example: 1285765191221
    taxIdstringnullable

    Tax ID of the consumer.

    Possible values: <= 30 characters

    Example: DE1927456229
    pausePeriodDaysintegernullable

    Number of days the subscription is paused.

    Example: 0
    billingNotificationDatestring<date>nullable

    Date when the next billing notification will be sent.

    Possible values: <= 10 characters

    scheduledBillingCyclesRemainingintegernullable

    Number of scheduled billing cycles remaining.

    Possible values: <= 2 characters, >= 0

    scheduledAmountnumber<decimal>nullable

    The scheduled amount for upcoming billing cycles.

    Example: 0
    pendingPaymentsboolean

    Indicates if any payments are pending.

    Example: false
    actionRequiredboolean

    Indicates if any merchant action is required for this subscription.

    Example: false
    extraInfo objectnullable

    Additional metadata related to the subscription.

    productGroupstring

    The product group associated with the subscription.

    Possible values: <= 255 characters

    Example: productGroup
    customerGroupstring

    The customer group classification.

    Possible values: <= 255 characters

    Example: customerGroup
    customReferences objectnullable

    Custom references for tracking.

    custom1string

    Custom reference 1.

    Possible values: <= 255 characters

    Example: payment
    custom2string

    Custom reference 2.

    Possible values: <= 255 characters

    Example: document_123
    custom3string

    Custom reference 3.

    Possible values: <= 255 characters

    Example: ref_number_3765
    criteria object[]nullable

    An array of key-value pair objects. Please refer to Data Model for details.

  • Array [
  • namestring

    Name of the criteria.

    Possible values: <= 50 characters

    Example: zbplRO6U5A6siu2suP7DY
    valuestring

    Value of the criteria.

    Possible values: <= 100 characters

    Example: hTtMVsv7oslFtbXmZd8CQ9tmIo1MsSa
  • ]
  • targetMerchantAccountReferencestringnullable

    Identifier of the target merchant account.

    Possible values: <= 255 characters