Create Subscription

Last changes: 12-08-2023

Request parameters

Field	Description	Type	Length	Mandatory
planId	Plan ID of an existing plan.	String	53	Yes
customerAccountId	Customer Account ID - A unique idetifier 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.	String	125	Yes
startDate	This 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)	String	29	Yes
timezone	Possible values: TZ database name in List of TZ Database Time Zones. (E.g: Europe/Berlin).	String	32	No
externalMerchantId	Field that allows the merchant to store a specific value for external reference. Available as a filtering field.	String	255	No
merchantMetadata	Field that allows the merchant to store a specific metadata linked with the subscription.	String	255	No
billingAddress	Billing address of the consumer. Please refer to Data Model for details.	Object	-	Yes
shippingAddress	Shipping address of the consumer. Please refer to Data Model for details.	Object	-	No
consumer	Customer information. Please refer to Data Model for details.	Object	-	Conditional. Mandatory if "businessConsumer" object is not provided.
businessConsumer	Business/Company information. Please refer to Data Model for details.	Object	-	Conditional. Mandatory if "consumer" object is not provided.

The request must provide the followng 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.

The automated calculation works with calendar days.

Response parameters

Field	Description	Type	Length	Mandatory
id	Subscription ID automatically generated by the system. Format: "Subscription" + "-" + <UUID> (E.g: Subscription-a4622449-7c8d-45aa-9f99-fb41cf5d599a)	String	49	Yes
createdAt	Timestamp of when the Subscription was created. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g: 2021-02-11T15:00:44.718Z)	String	24	Yes
updatedAt	Timestamp 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)	String	24	Yes
deletedAt	Timestamp 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)	String	24	Yes
planId	Plan ID of the existing plan under which the Subscription was created	String	53	Yes
status	Status of the subscription. Upon creation the subscription has the status created.	String	8	Yes
payment	Payment details of the Subscription created inherited from the provided plan. Please refer to Data Model for details.	Object	-	Yes
startDate	This 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)	String	29	Yes
timezone	Possible values: TZ database name in List of TZ Database Time Zones. (E.g: Europe/Berlin).	String	32	No
trialStartDate	Start Date of the Trial (if applicable). Format: YYYY-MM-DD.	String	10	Yes
trialEndDate	End Date of the Trial (if applicable). Format: YYYY-MM-DD.	String	10	Yes
nextBillingDate	Date of the upcoming billing when the customer would be charged. Format: YYYY-MM-DD.	String	10	Yes
billingCyclesRemaining	Number 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.	Int	2	Yes
customerAccountId	Customer Account ID - A unique idetifier 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.	String	125	Yes
merchantMetadata	Field that allows the merchant to store a specific metadata linked with the subscription.	String	255	No
externalMerchantId	Field that allows the merchant to store a specific value for external reference. Available as a filtering field.	String	255	No
billingAgreement	Billing 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
billingAddress	Billing address of the consumer. Please refer to Data Model for details.	Object	-	Yes
shippingAddress	Shipping address of the consumer. Please refer to Data Model for details.	Object	-	Yes
consumer	Customer information. Please refer to Data Model for details.	Object	-	Conditional. Mandatory if "businessConsumer" object is not provided.
businessConsumer	Business/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.

Please refer to Data Model for Object details.

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

For error handling, please refer to this section.

Previous

Next