Update Subscription

Last changes: 12-08-2023

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

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

For error handling, please refer to this section.

Previous

Next