Update Subscription
Using this service you could update the below fields of a subscription:
- billingAddress
- shippingAddress
- consumer
- businessConsumer
- billingCyclesRemaining
- status (to pause or resume a subscription as covered in this section)
Request parameters
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| billingAddress | Parent element. Billing address of the consumer. Please refer to Data Model for details. | Object | - | No |
| shippingAddress | Parent element. Shipping address of the consumer. Please refer to Data Model for details. | Object | - | No |
| consumer | Parent element. Customer information. Please refer to Data Model for details. | Object | - | No |
| businessConsumer | Parent element. Business/Company information. Please refer to Data Model for details. | Object | - | No |
| 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 | No |
| status | Status of the subscription (e.g "active", "paused") | String | 8 | No |
info
The request must provide the following header:
x-api-key: {merchantKey}
Request sample
Path:
PATCH {baseURL}/subscriptions/Subscription-9487ebbd-28ae-4577-9479-26658167236f
Header:
Content-Type: application/json
Accept-Language: en-US
{
"billingCyclesRemaining": 6,
"billingAddress": {
"addressLine2": "Bavaria",
"number": "2"
},
"shippingAddress": {
"addressLine2": "Bavaria",
"number": "2"
},
"consumer": {
"emailAddress": "john.smith@sentreprise.com"
}
}
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 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. | 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. | Object | - | Yes |
| billingAddress | Parent element. Billing address of the consumer. Please refer to Data Model for details. | Object | - | Yes |
| shippingAddress | Parent element. Shipping address of the consumer. Please refer to Data Model for details. | Object | - | Yes |
| consumer | Parent element. 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:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"id": "Subscription-9487ebbd-28ae-4577-9479-26658167236f",
"createdAt": "2021-03-18T21:30:52.31Z",
"updatedAt": "2021-03-18T21:38:53.52Z",
"deletedAt": null,
"planId": "SubscriptionPlan-d0d665b0-4bf4-45ab-8eaa-d3acbdbc1e16",
"status": "created",
"payment": {
"description": "Post Premium sub",
"recurrentAmount": 18.00,
"currencyIsoCode": "EUR"
},
"startDate": "2021-03-31T15:30:44.718-08:00",
"trialStartDate": "2021-03-21",
"trialEndDate": "2021-03-22",
"nextBillingDate": "2021-07-22",
"billingCyclesRemaining": 6,
"customerAccountId": "customer2-b496-4a3a-bc8f-d2a55af5794a",
"merchantMetadata": "{ \"clientId\": 1248052792, \"preference\": 120}",
"externalMerchantId": "MC_21507252",
"billingAgreement": null,
"billingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": "Bavaria",
"addressLine3": null,
"number": "2",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"shippingAddress": {
"addressLine1": "Leopoldstrasse",
"addressLine2": "Bavaria",
"addressLine3": null,
"number": "2",
"city": "Munich",
"postCode": "80807",
"countryCode": "DE",
"state": null
},
"consumer": {
"firstName": "John",
"lastName": "Smith",
"middleName": ".",
"emailAddress": "john.smith@sentreprise.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.