Create Subscription
POST/subscriptions
Creates a new subscription based on the provided details.
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.
The automated calculation works with calendar days.
Request
Header Parameters
Must be application/json
Must be be en-US
The origin of the request
The client making the request
x-api-key: {merchantKey}
- application/json
- Body
- Example (auto)
Bodyrequired
Unique identifier of an existing subscription plan.
Possible values: <= 53 characters
SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9aUnique identifier for the customer in the merchant's system.
Possible values: <= 125 characters
customer1-b496-4a3a-bc8f-d2a55af5794aThe 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
2021-03-31T15:30:44.18-08:00TZ database name in List of TZ Database Time Zones.
Possible values: <= 32 characters
Europe/BerlinExternal reference identifier assigned by the merchant.
Possible values: <= 255 characters
MC_21507252JSON metadata for merchant-specific details.
Possible values: <= 255 characters
{"clientId": 1248052792, "preference": 120}billingAddress objectrequired
Billing or shipping address of the consumer. Please refer to Data Model for details.
Address line 1.
Possible values: <= 60 characters
LeopoldstrasseAddress line 2.
Possible values: <= 60 characters
Address line 3.
Possible values: <= 60 characters
House number/building number.
Possible values: <= 10 characters
244City name of the address.
Possible values: <= 50 characters
MunichPostal code of the address.
Possible values: <= 10 characters
80807Country 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
DEState. 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.
Address line 1.
Possible values: <= 60 characters
LeopoldstrasseAddress line 2.
Possible values: <= 60 characters
Address line 3.
Possible values: <= 60 characters
House number/building number.
Possible values: <= 10 characters
244City name of the address.
Possible values: <= 50 characters
MunichPostal code of the address.
Possible values: <= 10 characters
80807Country 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
DEState. 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.
First name of the consumer.
Possible values: <= 60 characters
JohnLast name of the consumer.
Possible values: <= 60 characters
SmithMiddle name of the consumer.
Possible values: <= 60 characters
.Email address of the customer.
Possible values: <= 255 characters
john.smith@smithentreprise.comTitle of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
MrConsists 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
en-deDate of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
1995-01-26Gender of the consumer.
Possible values: [M, F, D]
MMobile phone of the customer.
Possible values: <= 30 characters
1285765191221Home phone of the customer.
Possible values: <= 30 characters
1285765191221Work phone of the customer.
Possible values: <= 30 characters
1285765191221Tax ID of the consumer.
Possible values: <= 30 characters
DE1927456229businessConsumer 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.
Company legal entity name.
Possible values: <= 100 characters
Smith Enterprises Ltd.Company legal entity type (e.g., GmbH).
Possible values: <= 100 characters
GmbHCustomer's email address.
Possible values: <= 255 characters
contact@smithenterprises.comTax identification number.
Possible values: <= 30 characters
DE123456789Consists 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
en-DECompany registration number
Possible values: <= 50 characters
HRB 123456ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.
Possible values: >= 2 characters and <= 3 characters
DE{
"planId": "SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10",
"startDate": "2024-10-31T08:48:19.96Z",
"customerAccountId": "BSTEST01",
"externalMerchantId": "client_21507252",
"merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
"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": {
"companyName": "Smith Enterprises Ltd.",
"companyType": "GmbH",
"emailAddress": "contact@smithenterprises.com",
"taxId": "DE123456789",
"culture": "en-DE",
"companyRegistrationNumber": "HRB 123456",
"companyRegistrationCountryCode": "DE"
}
}
Responses
- 201
- 400
- 401
- 403
- 404
- 500
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.
Each time a payment option is changed a new billing agreement is created. Please refer to Data Model for object details.
- application/json
- Schema
- Example (auto)
- Example
Schema
- Array [
- ]
Unique subscription ID assigned by the system.
Possible values: <= 49 characters
Subscription-39ab7cc3-57d7-42d7-ad24-a7b8a4164880Timestamp of when the subscription was created.
Possible values: <= 24 characters
2024-10-31T14:30:10.51ZTimestamp of when the subscription was last updated.
Possible values: <= 24 characters
2024-10-31T14:30:10.51ZTimestamp of when the subscription was deleted (if applicable).
Possible values: <= 24 characters
Identifier of the subscription plan associated with this subscription.
Possible values: <= 53 characters
SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10Current status of the subscription.
Possible values: [created, pending, trial, active, overdue, canceled, expired, paused]
createdpayment objectnullablerequired
Description of the payment.
Possible values: <= 255 characters
Premium sub for only 100 EUR!Amount charged per billing cycle.
Possible values: <= 60 characters
100ISO currency code for the payment.
Possible values: <= 3 characters
EURThe 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
2021-03-31T15:30:44.18-08:00Start date of the trial period, if applicable.
Possible values: <= 10 characters
2024-10-31End date of the trial period, if applicable.
Possible values: <= 10 characters
2024-11-30Date of the next scheduled billing.
Possible values: <= 10 characters
2024-11-30Number of remaining billing cycles.
Possible values: <= 2 characters, >= 0
4Unique identifier assigned by the merchant to the customer.
Possible values: <= 125 characters
BSTEST01JSON metadata containing merchant-specific details.
Possible values: <= 255 characters
{"usage": 250, "client": 1248052792, "monitor": true }External identifier for reference purposes.
Possible values: <= 255 characters
client_21507252billingAgreement objectnullablerequired
Billing agreement details, if applicable.
Unique Identifier of the Billing Agreement. Format: BillingAgreement + - + <UUID>
Possible values: <= 50 characters
BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771PaymentObject used for billing this subscription.
8ac7a49f8609e07601860ca28ce656edDate when the billing agreement was created.
Possible values: <= 24 characters
2021-01-26T14:29:05.994ZDisplay name of the payment option which has been stored.
Possible values: <= 255 characters
MastercardCode of the payment option which has been stored.
Possible values: <= 255 characters
MSTRCRDMasked carrier number of the payment instrument which has been stored.
401288****1881Indicates if a card used as a payment option is expired or not.
Possible values: [true, false]
falseIf 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}$
04/2024Additional data related to the stored payment option.
billingAddress objectrequired
Billing or shipping address of the consumer. Please refer to Data Model for details.
Address line 1.
Possible values: <= 60 characters
LeopoldstrasseAddress line 2.
Possible values: <= 60 characters
Address line 3.
Possible values: <= 60 characters
House number/building number.
Possible values: <= 10 characters
244City name of the address.
Possible values: <= 50 characters
MunichPostal code of the address.
Possible values: <= 10 characters
80807Country 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
DEState. 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.
Address line 1.
Possible values: <= 60 characters
LeopoldstrasseAddress line 2.
Possible values: <= 60 characters
Address line 3.
Possible values: <= 60 characters
House number/building number.
Possible values: <= 10 characters
244City name of the address.
Possible values: <= 50 characters
MunichPostal code of the address.
Possible values: <= 10 characters
80807Country 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
DEState. 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.
First name of the consumer.
Possible values: <= 60 characters
JohnLast name of the consumer.
Possible values: <= 60 characters
SmithMiddle name of the consumer.
Possible values: <= 60 characters
.Email address of the customer.
Possible values: <= 255 characters
john.smith@smithentreprise.comTitle of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
MrConsists 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
en-deDate of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
1995-01-26Gender of the consumer.
Possible values: [M, F, D]
MMobile phone of the customer.
Possible values: <= 30 characters
1285765191221Home phone of the customer.
Possible values: <= 30 characters
1285765191221Work phone of the customer.
Possible values: <= 30 characters
1285765191221Tax ID of the consumer.
Possible values: <= 30 characters
DE1927456229Number of days the subscription is paused.
0Date when the next billing notification will be sent.
Possible values: <= 10 characters
Number of scheduled billing cycles remaining.
Possible values: <= 2 characters, >= 0
The scheduled amount for upcoming billing cycles.
0Indicates if any payments are pending.
falseIndicates if any merchant action is required for this subscription.
falseextraInfo objectnullable
Additional metadata related to the subscription.
The product group associated with the subscription.
Possible values: <= 255 characters
productGroupThe customer group classification.
Possible values: <= 255 characters
customerGroupcustomReferences objectnullable
Custom references for tracking.
Custom reference 1.
Possible values: <= 255 characters
paymentCustom reference 2.
Possible values: <= 255 characters
document_123Custom reference 3.
Possible values: <= 255 characters
ref_number_3765criteria object[]nullable
An array of key-value pair objects. Please refer to Data Model for details.
Name of the criteria.
Possible values: <= 50 characters
zbplRO6U5A6siu2suP7DYValue of the criteria.
Possible values: <= 100 characters
hTtMVsv7oslFtbXmZd8CQ9tmIo1MsSaIdentifier of the target merchant account.
Possible values: <= 255 characters
{
"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": "2021-03-31T15:30:44.18-08:00",
"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"
}
{
"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
}
Bad request
Unauthorized
Forbidden
Not Found
Internal Server Error