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}

application/json

Body

required

planId stringrequired

Possible values: <= 53 characters

Unique identifier of an existing subscription plan.

customerAccountId stringrequired

Possible values: <= 125 characters

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

startDate date-timerequired

Possible values: <= 29 characters

The start date of the subscription. It cannot be in the past.

timezone string

Possible values: <= 32 characters

TZ database name in List of TZ Database Time Zones.

externalMerchantId stringnullable

Possible values: <= 255 characters

External reference identifier assigned by the merchant.

merchantMetadata stringnullable

Possible values: <= 255 characters

JSON metadata for merchant-specific details.

billingAddress

object

required

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

shippingAddress

object

nullable

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

consumer

object

required

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.

firstName stringrequired

Possible values: <= 60 characters

First name of the consumer.

lastName stringrequired

Possible values: <= 60 characters

Last name of the consumer.

middleName stringnullable

Possible values: <= 60 characters

Middle name of the consumer.

emailAddress emailrequired

Possible values: <= 255 characters

Email address of the customer.

title stringrequired

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

Title of the consumer.

culture string

Possible values: <= 5 characters

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.

dateOfBirth daterequired

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

gender string

Possible values: [M, F, D]

Gender of the consumer.

mobilePhone string

Possible values: <= 30 characters

Mobile phone of the customer.

homePhone string

Possible values: <= 30 characters

Home phone of the customer.

workPhone string

Possible values: <= 30 characters

Work phone of the customer.

taxId stringnullable

Possible values: <= 30 characters

Tax ID of the consumer.

businessConsumer

object

nullable

required

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.

companyName stringrequired

Possible values: <= 100 characters

Company legal entity name.

companyType stringrequired

Possible values: <= 100 characters

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

emailAddress stringrequired

Possible values: <= 255 characters

Customer's email address.

taxId stringnullable

Possible values: <= 30 characters

Tax identification number.

culture stringnullable

Possible values: <= 5 characters

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.

companyRegistrationNumber stringnullable

Possible values: <= 50 characters

Company registration number

companyRegistrationCountryCode stringnullable

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

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

Responses

201

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.

application/json

Schema

Schema

id stringrequired

Possible values: <= 49 characters

Unique subscription ID assigned by the system.

createdAt date-timerequired

Possible values: <= 24 characters

Timestamp of when the subscription was created.

updatedAt date-timerequired

Possible values: <= 24 characters

Timestamp of when the subscription was last updated.

deletedAt date-timenullablerequired

Possible values: <= 24 characters

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

planId stringrequired

Possible values: <= 53 characters

Identifier of the subscription plan associated with this subscription.

status stringrequired

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

Current status of the subscription.

payment

object

nullable

required

description string

Possible values: <= 255 characters

Description of the payment.

recurrentAmount decimal

Possible values: <= 60 characters

Amount charged per billing cycle.

currencyIsoCode string

Possible values: <= 3 characters

ISO currency code for the payment.

startDate date-timerequired

Possible values: <= 29 characters

The start date of the subscription.

trialStartDate datenullablerequired

Possible values: <= 10 characters

Start date of the trial period, if applicable.

trialEndDate datenullablerequired

Possible values: <= 10 characters

End date of the trial period, if applicable.

nextBillingDate datenullablerequired

Possible values: <= 10 characters

Date of the next scheduled billing.

billingCyclesRemaining integernullablerequired

Possible values: <= 2 characters

Number of remaining billing cycles.

customerAccountId stringrequired

Possible values: <= 125 characters

Unique identifier assigned by the merchant to the customer.

merchantMetadata stringnullable

Possible values: <= 255 characters

JSON metadata containing merchant-specific details.

externalMerchantId stringnullable

Possible values: <= 255 characters

External identifier for reference purposes.

billingAgreement

object

nullable

required

Billing agreement details, if applicable.

id stringrequired

Possible values: <= 50 characters

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

paymentObjectId stringrequired

PaymentObject used for billing this subscription.

billingAgreementDate date-timerequired

Possible values: <= 24 characters

Date when the billing agreement was created.

name stringrequired

Possible values: <= 255 characters

Display name of the payment option which has been stored.

code stringrequired

Possible values: <= 255 characters

Code of the payment option which has been stored.

carrierNumber string

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

isExpired booleanrequired

Possible values: [true, false]

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

expiryDate stringrequired

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

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

storedPaymentOptionData objectnullable

Additional data related to the stored payment option.

billingAddress

object

required

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

shippingAddress

object

nullable

required

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

consumer

object

required

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.

firstName stringrequired

Possible values: <= 60 characters

First name of the consumer.

lastName stringrequired

Possible values: <= 60 characters

Last name of the consumer.

middleName stringnullable

Possible values: <= 60 characters

Middle name of the consumer.

emailAddress emailrequired

Possible values: <= 255 characters

Email address of the customer.

title stringrequired

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

Title of the consumer.

culture string

Possible values: <= 5 characters

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.

dateOfBirth daterequired

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

gender string

Possible values: [M, F, D]

Gender of the consumer.

mobilePhone string

Possible values: <= 30 characters

Mobile phone of the customer.

homePhone string

Possible values: <= 30 characters

Home phone of the customer.

workPhone string

Possible values: <= 30 characters

Work phone of the customer.

taxId stringnullable

Possible values: <= 30 characters

Tax ID of the consumer.

pausePeriodDays integernullable

Number of days the subscription is paused.

billingNotificationDate datenullable

Possible values: <= 10 characters

Date when the next billing notification will be sent.

scheduledBillingCyclesRemaining integernullable

Possible values: <= 2 characters

Number of scheduled billing cycles remaining.

scheduledAmount decimalnullable

The scheduled amount for upcoming billing cycles.

pendingPayments boolean

Indicates if any payments are pending.

actionRequired boolean

Indicates if any merchant action is required for this subscription.

extraInfo

object

nullable

Additional metadata related to the subscription.

productGroup string

Possible values: <= 255 characters

The product group associated with the subscription.

customerGroup string

Possible values: <= 255 characters

The customer group classification.

customReferences

object

nullable

Custom references for tracking.

custom1 string

Possible values: <= 255 characters

Custom reference 1.

custom2 string

Possible values: <= 255 characters

Custom reference 2.

custom3 string

Possible values: <= 255 characters

Custom reference 3.

criteria

object[]

nullable

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

Array [

name string

Possible values: <= 50 characters

Name of the criteria.

value string

Possible values: <= 100 characters

Value of the criteria.

]

targetMerchantAccountReference stringnullable

Possible values: <= 255 characters

Identifier of the target merchant account.

Example (from schema)

{
  "id": "Subscription-39ab7cc3-57d7-42d7-ad24-a7b8a4164880",
  "createdAt": "2024-10-31T14:30:10.51Z",
  "updatedAt": "2024-10-31T14:30:10.51Z",
  "deletedAt": "2024-07-29T15:51:28.071Z",
  "planId": "SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10",
  "status": "created",
  "payment": {
    "description": "Premium sub for only 100 EUR!",
    "recurrentAmount": 100,
    "currencyIsoCode": "EUR"
  },
  "startDate": "2024-10-31T08:48:19.96Z",
  "trialStartDate": "2024-10-31",
  "trialEndDate": "2024-11-30",
  "nextBillingDate": "2024-11-30",
  "billingCyclesRemaining": 4,
  "customerAccountId": "BSTEST01",
  "merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
  "externalMerchantId": "client_21507252",
  "billingAgreement": {
    "id": "BillingAgreement-99aad3ef-78d8-492a-829d-9e5db02018fd",
    "paymentObjectId": "8ac7a49f8609e07601860ca28ce656ed",
    "billingAgreementDate": "2023-02-02T15:05:37.28Z",
    "name": "Mastercard",
    "code": "MSTRCRD",
    "carrierNumber": "520000****0015",
    "expiryDate": "12/2025",
    "storedPaymentOptionData": null
  },
  "billingAddress": {
    "addressLine1": "Leopoldstrasse",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE",
    "state": null
  },
  "shippingAddress": {
    "addressLine1": "Leopoldstrasse",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE",
    "state": null
  },
  "consumer": {
    "firstName": "John",
    "lastName": "Smith",
    "middleName": ".",
    "emailAddress": "john.smith@smithentreprise.com",
    "title": "Mr",
    "culture": "en-de",
    "dateOfBirth": "1995-01-26",
    "gender": "M",
    "mobilePhone": "1285765191221",
    "homePhone": "1285765191221",
    "workPhone": "1285765191221",
    "taxId": "DE1927456229"
  },
  "pausePeriodDays": 0,
  "billingNotificationDate": "2024-07-29",
  "scheduledBillingCyclesRemaining": 0,
  "scheduledAmount": 0,
  "pendingPayments": false,
  "actionRequired": false,
  "extraInfo": {
    "productGroup": "productGroup",
    "customerGroup": "customerGroup"
  },
  "customReferences": {
    "custom1": "payment",
    "custom2": "document_123",
    "custom3": "ref_number_3765"
  },
  "criteria": [
    {
      "name": "zbplRO6U5A6siu2suP7DY",
      "value": "hTtMVsv7oslFtbXmZd8CQ9tmIo1MsSa"
    }
  ],
  "targetMerchantAccountReference": "string"
}

Example

{
  "id": "Subscription-39ab7cc3-57d7-42d7-ad24-a7b8a4164880",
  "createdAt": "2024-10-31T14:30:10.51Z",
  "updatedAt": "2024-10-31T14:30:10.51Z",
  "deletedAt": null,
  "planId": "SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10",
  "status": "created",
  "payment": {
    "description": "Premium sub for only 100 EUR!",
    "recurrentAmount": 100,
    "currencyIsoCode": "EUR"
  },
  "startDate": "2024-10-31T08:48:19.96Z",
  "trialStartDate": "2024-10-31",
  "trialEndDate": "2024-11-30",
  "nextBillingDate": "2024-11-30",
  "billingCyclesRemaining": 4,
  "customerAccountId": "BSTEST01",
  "merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
  "externalMerchantId": "client_21507252",
  "billingAgreement": null,
  "billingAddress": {
    "addressLine1": "Wall st. , NY",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "224",
    "city": "NEW YORK",
    "postCode": "NEW YORK",
    "countryCode": "US",
    "state": "AR"
  },
  "shippingAddress": {
    "addressLine1": "Wall st. , NY",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "224",
    "city": "NEW YORK",
    "postCode": "NEW YORK",
    "countryCode": "US",
    "state": "AR"
  },
  "consumer": {
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Name",
    "emailAddress": "john.smith@smithenterprise.com",
    "title": "MR",
    "culture": "en-de",
    "dateOfBirth": "1995-01-26",
    "gender": "M",
    "mobilePhone": "1285765191221",
    "homePhone": "1285765191221",
    "workPhone": "1285765191221",
    "taxId": "DE1927456229"
  },
  "businessConsumer": null,
  "pausePeriodDays": 0,
  "billingNotificationDate": null,
  "scheduledBillingCyclesRemaining": null,
  "scheduledAmount": 0,
  "pendingPayments": false,
  "actionRequired": false,
  "extraInfo": {
    "productGroup": "productGroup",
    "customerGroup": "customerGroup"
  },
  "customReferences": {
    "custom1": "payment",
    "custom2": "document_123",
    "custom3": "ref_number_3765"
  },
  "criteria": [
    {
      "name": "zbplRO6U5A6siu2suP7DY",
      "value": "hTtMVsv7oslFtbXmZd8CQ9tmIo1MsSa"
    }
  ],
  "targetMerchantAccountReference": null
}

400

Bad request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

Loading...