Skip to main content

Get Subscription

Request parameters

FieldDescription
idUnique Identifier of the created Subscription. Format: "Subscription" + "-" + <UUID>
info

The request must provide the following header:

x-api-key: {merchantKey}

Request sample

Path:

GET {baseURL}/subscriptions/Subscription-caf9b798-315b-40aa-9659-cf732f55d847

Header:

Content-Type: application/json
Accept-Language: en-US

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.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-Yes

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US
{
"id": "Subscription-caf9b798-315b-40aa-9659-cf732f55d847",
"createdAt": "2021-03-18T20:56:42.28Z",
"updatedAt": "2021-03-18T20:57:11.43Z",
"deletedAt": null,
"planId": "SubscriptionPlan-d0d665b0-4bf4-45ab-8eaa-d3acbdbc1e16",
"status": "created",
"payment": {
"description": "Post Premium sub",
"recurrentAmount": 18.00,
"currencyIsoCode": "EUR"
},
"startDate": "2021-03-21T15:30:44.718-08:00",
"trialStartDate": "2021-03-21",
"trialEndDate": "2021-03-22",
"nextBillingDate": "2021-07-22",
"billingCyclesRemaining": 1,
"customerAccountId": "customer2-b496-4a3a-bc8f-d2a55af5794a",
"merchantMetadata": "{ \"clientId\": 1248052792, \"preference\": 120}",
"externalMerchantId": "MC_21507252",
"billingAgreement": null,
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": "Building 442A22",
"addressLine3": "7th floor",
"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"
}
}
info

For error handling, please refer to this section.