Skip to main content

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

FieldDescriptionTypeLengthMandatory
billingAddressParent element. Billing address of the consumer. Please refer to Data Model for details.Object-No
shippingAddressParent element. Shipping address of the consumer. Please refer to Data Model for details.Object-No
consumerParent element. Customer information. Please refer to Data Model for details.Object-No
businessConsumerParent element. Business/Company information. Please refer to Data Model for details.Object-No
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.Int2No
statusStatus of the subscription (e.g "active", "paused")String8No
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

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.Object-Yes
billingAddressParent element. Billing address of the consumer. Please refer to Data Model for details.Object-Yes
shippingAddressParent element. Shipping address of the consumer. Please refer to Data Model for details.Object-Yes
consumerParent element. Customer 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:

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.