Skip to main content

Create Subscription

Request parameters

FieldDescriptionTypeLengthMandatory
planIdPlan ID of an existing plan.String53Yes
customerAccountIdCustomer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g. customer number. For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any.String125Yes
startDateThis is the start date of the subscription. It cannot be in the past (the validation is on the date part yyyy-MM-dd). Format: yyyy-MM-ddTHH:MM:SSZ (E.g 2021-04-25T15:30:44.718-08:00)String29Yes
timezonePossible values: TZ database name in List of TZ Database Time Zones. (E.g: Europe/Berlin).String32No
externalMerchantIdField that allows the merchant to store a specific value for external reference. Available as a filtering field.String255No
merchantMetadataField that allows the merchant to store a specific metadata linked with the subscription.String255No
billingAddressBilling address of the consumer. Please refer to Data Model for details.Object-Yes
shippingAddressShipping address of the consumer. Please refer to Data Model for details.Object-No
consumerCustomer information. Please refer to Data Model for details.Object-Conditional. Mandatory if "businessConsumer" object is not provided.
businessConsumerBusiness/Company information. Please refer to Data Model for details.Object-Conditional. Mandatory if "consumer" object is not provided.
info

The request must provide the following header:

x-api-key: {merchantKey}

Request sample

Path:

POST {BaseUrl}/subscriptions

Header:

Content-Type: application/json
Accept-Language: en-US
{
"planId": "SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9a",
"startDate": "2021-03-31T15:30:44.718-08:00",
"customerAccountId": "customer1-b496-4a3a-bc8f-d2a55af5794a",
"externalMerchantId": "MC_21507252",
"merchantMetadata": "{ \"clientId\": 1248052792, \"preference\": 120}",
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE"
},
"shippingAddress": {
"addressLine1": "Leopoldstrasse",
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE"
},
"consumer": {
"firstName": "John",
"lastName": "Smith",
"middleName": ".",
"emailAddress": "john.smith@smithentreprise.com",
"title": "Mr",
"culture": "de-en",
"dateOfBirth": "1995-01-26",
"gender": "M",
"mobilePhone": "1285765191221",
"homePhone": "1285765191221",
"workPhone": "1285765191221",
"taxId": "DE1927456229"
}
}

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.

Response parameters

FieldDescriptionTypeLengthMandatory
idSubscription ID automatically generated by the system. Format: "Subscription" + "-" + <UUID> (E.g: Subscription-a4622449-7c8d-45aa-9f99-fb41cf5d599a)String49Yes
createdAtTimestamp of when the Subscription was created. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z)String24Yes
updatedAtTimestamp of when the Subscription was last updated. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z)String24Yes
deletedAtTimestamp of when the Subscription was deleted (if applicable). Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z)String24Yes
planIdPlan ID of the existing plan under which the Subscription was createdString53Yes
statusStatus of the subscription. Upon creation the subscription has the status created.String8Yes
paymentPayment details of the Subscription created inherited from the provided plan. Please refer to Data Model for details.Object-Yes
startDateThis is the start date of the subscription. It cannot be in the past. Format: yyyy-MM-ddTHH:MM:SSZ (E.g 2021-04-25T15:30:44.718-08:00)String29Yes
timezonePossible values: TZ database name in List of TZ Database Time Zones. (E.g: Europe/Berlin).String32No
trialStartDateStart Date of the Trial (if applicable). Format: YYYY-MM-DD.String10Yes
trialEndDateEnd Date of the Trial (if applicable). Format: YYYY-MM-DD.String10Yes
nextBillingDateDate of the upcoming billing when the customer would be charged. Format: YYYY-MM-DD.String10Yes
billingCyclesRemainingNumber of the remaining billing cycles to be charged. Populated initially from the input billingCycles of the parent subscription Plan. Every time a billing occurs (successful transaction) then the billingCyclesRemaining is reduced by 1.Int2Yes
customerAccountIdCustomer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g. customer number. For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any.String125Yes
merchantMetadataField that allows the merchant to store a specific metadata linked with the subscription.String255No
externalMerchantIdField that allows the merchant to store a specific value for external reference. Available as a filtering field.String255No
billingAgreementBilling Agreement linked to the Subscription. Hosting the payment instrument information returned as null for newly created subscription as no payment instrument is linked to the subscription yet!Object-Yes
billingAddressBilling address of the consumer. Please refer to Data Model for details.Object-Yes
shippingAddressShipping address of the consumer. Please refer to Data Model for details.Object-Yes
consumerCustomer information. Please refer to Data Model for details.Object-Conditional. Mandatory if "businessConsumer" object is not provided.
businessConsumerBusiness/Company information. Please refer to Data Model for details.Object-Conditional. Mandatory if "consumer" object is not provided.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US
{
"id": "Subscription-a4622449-7c8d-45aa-9f99-fb41cf5d599a",
"createdAt": "2021-03-18T12:05:06.46Z",
"updatedAt": "2021-03-18T12:05:06.46Z",
"deletedAt": null,
"planId": "SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9a",
"status": "created",
"payment": {
"description": "Post Premium sub",
"recurrentAmount": 18.00,
"currencyIsoCode": "EUR"
},
"startDate": "2021-03-31T15:30:44.718-08:00",
"trialStartDate": "2021-03-31",
"trialEndDate": "2021-04-01",
"nextBillingDate": "2021-08-01",
"billingCyclesRemaining": 4,
"customerAccountId": "customer1-b496-4a3a-bc8f-d2a55af5794a",
"merchantMetadata": "{ \"clientId\": 1248052792, \"preference\": 120}",
"externalMerchantId": "MC_21507252",
"billingAgreement": null,
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": null,
"addressLine3": null,
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"shippingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": null,
"addressLine3": null,
"number": "244",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"consumer": {
"firstName": "John",
"lastName": "Smith",
"middleName": ".",
"emailAddress": "john.smith@smithentreprise.com",
"title": "Mr",
"culture": "de-en",
"dateOfBirth": "1995-01-26",
"gender": "M",
"mobilePhone": "1285765191221",
"homePhone": "1285765191221",
"workPhone": "1285765191221",
"taxId": "DE1927456229"
}
}

At this point 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 us their payment option details through our Web SDK. Once the payment option details are provided a Billing Agreement is created and linked to the subscription, which moves to the "pending" status.

Billing Agreement

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

Please refer to Data Model for Object details.

info

Each time a payment option is changed a new billing agreement is created.

info

For error handling, please refer to this section.