Update Subscription

PATCH 
/subscriptions/:subscriptionId

Updates the specified fields of an existing subscription.

info

The request must provide the following header: x-api-key: {merchantKey}

This service allows you to update the following fields of a subscription:

• billingAddress
• shippingAddress
• consumer
• businessConsumer
• billingCyclesRemaining
• status (to pause or resume a subscription as covered in this section)

Request

Path Parameters

subscriptionId stringrequired
Unique Identifier of the created Subscription. Format: Subscription + - + <UUID>
Example: Subscription-9487ebbd-28ae-4577-9479-26658167236f

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

x-api-key stringrequired

x-api-key: {merchantKey}

application/json

Body

Bodyrequired

billingAddress object

Billing or shipping address of the consumer. Please refer to Data Model for details.

addressLine1stringrequired

Address line 1.

Possible values: <= 60 characters

Example: Leopoldstrasse

addressLine2stringnullable

Address line 2.

Possible values: <= 60 characters

addressLine3stringnullable

Address line 3.

Possible values: <= 60 characters

numberstringrequired

House number/building number.

Possible values: <= 10 characters

Example: 244

citystringrequired

City name of the address.

Possible values: <= 50 characters

Example: Munich

postCodestringrequired

Postal code of the address.

Possible values: <= 10 characters

Example: 80807

countryCodestringrequired

Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

Possible values: >= 2 characters and <= 3 characters

Example: DE

statestringnullable

State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

Possible values: <= 3 characters

shippingAddress object

Billing or shipping address of the consumer. Please refer to Data Model for details.

addressLine1stringrequired

Address line 1.

Possible values: <= 60 characters

Example: Leopoldstrasse

addressLine2stringnullable

Address line 2.

Possible values: <= 60 characters

addressLine3stringnullable

Address line 3.

Possible values: <= 60 characters

numberstringrequired

House number/building number.

Possible values: <= 10 characters

Example: 244

citystringrequired

City name of the address.

Possible values: <= 50 characters

Example: Munich

postCodestringrequired

Postal code of the address.

Possible values: <= 10 characters

Example: 80807

countryCodestringrequired

Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

Possible values: >= 2 characters and <= 3 characters

Example: DE

statestringnullable

State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

Possible values: <= 3 characters

consumer objectnullable
Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
Conditional. Can be present if businessConsumer is missing from the request.
firstNamestringrequired
First name of the consumer.
Possible values: <= 60 characters
Example: John
lastNamestringrequired
Last name of the consumer.
Possible values: <= 60 characters
Example: Smith
middleNamestringnullable
Middle name of the consumer.
Possible values: <= 60 characters
Example: .
emailAddressstring<email>required
Email address of the customer.
Possible values: <= 255 characters
Example: john.smith@smithentreprise.com
titlestring
Title of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
Example: Mr
culturestring
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-de
dateOfBirthstring<date>required
Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
Example: 1995-01-26
genderstring
Gender of the consumer.
Possible values: [M, F, D]
Example: M
mobilePhonestring
Mobile phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
homePhonestring
Home phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
workPhonestring
Work phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
taxIdstringnullable
Tax ID of the consumer.
Possible values: <= 30 characters
Example: DE1927456229
businessConsumer objectnullable
Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
Conditional. Can be present if consumer is missing from the request.
companyNamestringrequired
Company legal entity name.
Possible values: <= 100 characters
Example: Smith Enterprises Ltd.
companyTypestringrequired
Company legal entity type (e.g., GmbH).
Possible values: <= 100 characters
Example: GmbH
emailAddressstring<string>required
Customer's email address.
Possible values: <= 255 characters
Example: contact@smithenterprises.com
taxIdstringnullable
Tax identification number.
Possible values: <= 30 characters
Example: DE123456789
culturestringnullable
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-DE
companyRegistrationNumberstringnullable
Company registration number
Possible values: <= 50 characters
Example: HRB 123456
companyRegistrationCountryCodestringnullable
ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.
Possible values: >= 2 characters and <= 3 characters
Example: DE
billingCyclesRemaininginteger

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.

Possible values: <= 2 characters, >= 0

statusstring

Status of the subscription (e.g., active)

Possible values: [active, paused]

Example (auto)

{
  "billingCyclesRemaining": 6,
  "billingAddress": {
    "addressLine2": "Bavaria",
    "number": "2"
  },
  "shippingAddress": {
    "addressLine2": "Bavaria",
    "number": "2"
  },
  "consumer": {
    "emailAddress": "john.smith@sentreprise.com"
  }
}

Responses

200

Subscription updated successfully

application/json

Schema

Schema

idstringrequired
Subscription ID automatically generated by the system.
Possible values: <= 49 characters
Example: Subscription-a4622449-7c8d-45aa-9f99-fb41cf5d599a
createdAtstring<date-time>required
Timestamp of when the Subscription was created.
Example: 2021-03-18T12:05:06.46Z
updatedAtstring<date-time>required
Timestamp of when the Subscription was last updated.
Example: 2021-03-18T12:05:06.46Z
deletedAtstring<date-time>nullable

Timestamp of when the Subscription was deleted (if applicable).

planIdstringrequired
Plan ID of the existing plan under which the Subscription was created.
Possible values: <= 255 characters
Example: SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9a
statusstringrequired
Status of the subscription.
Possible values: <= 8 characters, [created, pending, trial, active, overdue, canceled, expired, paused]
Example: created
payment objectrequired
Payment details of the Subscription created inherited from the provided plan. Please refer to Data Model for details.
descriptionstring
Description of the payment or plan.
Possible values: <= 60 characters
Example: Premium sub for only 90.99 EUR!
recurrentAmountnumber<decimal>required
Recurrent amount to charge the customer.
Possible values: <= 60 characters
Example: 90.99
currencyIsoCodestringrequired
Currency of the charges. Format ISO 4217.
Possible values: >= 3 characters and <= 3 characters
Example: EUR
startDatestring<date-time>required
The start date of the subscription that defines when the subscription becomes active. The value must be a valid timestamp and is evaluated in UTC. SmartPay supports either the current UTC date or a future one. The Subscription module operates in UTC to ensure consistency across different time zones.
Merchants must provide a startDate that represents either the current date or a future date in UTC; it cannot be in the past. If a timestamp is provided in the local time zone (e.g., 2025-06-11T01:32:25.00+02:00 for Central European Time), the system automatically offsets it to UTC (e.g., 2025-06-10T23:32:25.00Z). If the resulting UTC date is in the past, the request will be rejected.
Merchants operating in local timezones must ensure that their intended startDate corresponds to today or a future date in UTC.
Possible values: <= 29 characters, Value must match regular expression yyyy-MM-ddTHH:MM:SSZ
Example: 2021-03-31T15:30:44.18-08:00
timezonestring
TZ database name in List of TZ Database Time Zones.
Possible values: <= 32 characters
Example: Europe/Berlin
trialStartDatestring<date>required
Start Date of the Trial (if applicable).
Example: 2021-03-31
trialEndDatestring<date>required
End Date of the Trial (if applicable).
Example: 2021-04-01
nextBillingDatestring<date>required
Date of the upcoming billing when the customer would be charged.
Possible values: <= 10 characters
Example: 2021-08-01
billingCyclesRemainingintegerrequired
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.
Possible values: <= 2 characters, >= 0
Example: 4
customerAccountIdstringrequired
A unique identifier provided by the integrating merchant by which the user's account could be identified, e.g.,, customer number. SmartPay checks if an account exists, allowing the end customer to see previously stored payment instruments, if any.
Possible values: <= 125 characters
Example: customer1-b496-4a3a-bc8f-d2a55af5794a
merchantMetadatastringnullable
Field that allows the merchant to store specific metadata linked with the subscription.
Possible values: <= 255 characters
Example: { "clientId": 1248052792, "preference": 120}
externalMerchantIdstringnullable
Field that allows the merchant to store a specific value for external reference.
Possible values: <= 255 characters
Example: MC_21507252
billingAgreement objectnullablerequired

Billing Agreement linked to the Subscription.
Hosting the payment instrument information returned as null for newly created subscription.

idstringrequired

Unique Identifier of the Billing Agreement. Format: BillingAgreement + - + <UUID>

Possible values: <= 50 characters

Example: BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771

paymentObjectIdstringrequired

PaymentObject used for billing this subscription.

Example: 8ac7a49f8609e07601860ca28ce656ed

billingAgreementDatestring<date-time>required

Date when the billing agreement was created.

Possible values: <= 24 characters

Example: 2021-01-26T14:29:05.994Z

namestringrequired

Display name of the payment option which has been stored.

Possible values: <= 255 characters

Example: Mastercard

codestringrequired

Code of the payment option which has been stored.

Possible values: <= 255 characters

Example: MSTRCRD

carrierNumberstring

Masked carrier number of the payment instrument which has been stored.

Example: 401288****1881

isExpiredbooleanrequired

Indicates if a card used as a payment option is expired or not.

Possible values: [true, false]

Example: false

expiryDatestringrequired

If a card is used as a payment option, this shows its expiry date.

Possible values: <= 7 characters, Value must match regular expression ^(0[1-9]|1[0-2])/[0-9]{4}$

Example: 04/2024

storedPaymentOptionDataobjectnullable

Additional data related to the stored payment option.

billingAddress objectrequired

Billing or shipping address of the consumer. Please refer to Data Model for details.

addressLine1stringrequired

Address line 1.

Possible values: <= 60 characters

Example: Leopoldstrasse

addressLine2stringnullable

Address line 2.

Possible values: <= 60 characters

addressLine3stringnullable

Address line 3.

Possible values: <= 60 characters

numberstringrequired

House number/building number.

Possible values: <= 10 characters

Example: 244

citystringrequired

City name of the address.

Possible values: <= 50 characters

Example: Munich

postCodestringrequired

Postal code of the address.

Possible values: <= 10 characters

Example: 80807

countryCodestringrequired

Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

Possible values: >= 2 characters and <= 3 characters

Example: DE

statestringnullable

State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

Possible values: <= 3 characters

shippingAddress objectrequired

Billing or shipping address of the consumer. Please refer to Data Model for details.

addressLine1stringrequired

Address line 1.

Possible values: <= 60 characters

Example: Leopoldstrasse

addressLine2stringnullable

Address line 2.

Possible values: <= 60 characters

addressLine3stringnullable

Address line 3.

Possible values: <= 60 characters

numberstringrequired

House number/building number.

Possible values: <= 10 characters

Example: 244

citystringrequired

City name of the address.

Possible values: <= 50 characters

Example: Munich

postCodestringrequired

Postal code of the address.

Possible values: <= 10 characters

Example: 80807

countryCodestringrequired

Country code. Could be 2 or 3 characters depending on the format used. Format ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3.

Possible values: >= 2 characters and <= 3 characters

Example: DE

statestringnullable

State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN.

Possible values: <= 3 characters

consumer objectnullablerequired
Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
Conditional. Can be present if businessConsumer is missing from the request.
firstNamestringrequired
First name of the consumer.
Possible values: <= 60 characters
Example: John
lastNamestringrequired
Last name of the consumer.
Possible values: <= 60 characters
Example: Smith
middleNamestringnullable
Middle name of the consumer.
Possible values: <= 60 characters
Example: .
emailAddressstring<email>required
Email address of the customer.
Possible values: <= 255 characters
Example: john.smith@smithentreprise.com
titlestring
Title of the consumer.
Possible values: <= 3 characters, [Mr, Mrs, Ms]
Example: Mr
culturestring
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-de
dateOfBirthstring<date>required
Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.
Example: 1995-01-26
genderstring
Gender of the consumer.
Possible values: [M, F, D]
Example: M
mobilePhonestring
Mobile phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
homePhonestring
Home phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
workPhonestring
Work phone of the customer.
Possible values: <= 30 characters
Example: 1285765191221
taxIdstringnullable
Tax ID of the consumer.
Possible values: <= 30 characters
Example: DE1927456229
businessConsumer objectnullablerequired
Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
Conditional. Can be present if consumer is missing from the request.
companyNamestringrequired
Company legal entity name.
Possible values: <= 100 characters
Example: Smith Enterprises Ltd.
companyTypestringrequired
Company legal entity type (e.g., GmbH).
Possible values: <= 100 characters
Example: GmbH
emailAddressstring<string>required
Customer's email address.
Possible values: <= 255 characters
Example: contact@smithenterprises.com
taxIdstringnullable
Tax identification number.
Possible values: <= 30 characters
Example: DE123456789
culturestringnullable
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g.,, en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-DE
companyRegistrationNumberstringnullable
Company registration number
Possible values: <= 50 characters
Example: HRB 123456
companyRegistrationCountryCodestringnullable
ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.
Possible values: >= 2 characters and <= 3 characters
Example: DE

Example (auto)

{
  "id": "Subscription-a4622449-7c8d-45aa-9f99-fb41cf5d599a",
  "createdAt": "2021-03-18T12:05:06.46Z",
  "updatedAt": "2021-03-18T12:05:06.46Z",
  "deletedAt": "2024-07-29T15:51:28.071Z",
  "planId": "SubscriptionPlan-9d4f69c3-5f76-4667-98d6-02de0124ac9a",
  "status": "created",
  "payment": {
    "description": "Post Premium sub",
    "recurrentAmount": 18,
    "currencyIsoCode": "EUR"
  },
  "startDate": "2021-03-31T15:30:44.18-08:00",
  "timezone": "Europe/Berlin",
  "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": {
    "id": "BillingAgreement-99aad3ef-78d8-492a-829d-9e5db02018fd",
    "paymentObjectId": "8ac7a49f8609e07601860ca28ce656ed",
    "billingAgreementDate": "2023-02-02T15:05:37.28Z",
    "name": "Mastercard",
    "code": "MSTRCRD",
    "carrierNumber": "520000****0015",
    "expiryDate": "12/2025",
    "storedPaymentOptionData": null
  },
  "billingAddress": {
    "addressLine1": "Leopoldstrasse",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE",
    "state": null
  },
  "shippingAddress": {
    "addressLine1": "Leopoldstrasse",
    "addressLine2": "Building 442A22",
    "addressLine3": "7th floor",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE",
    "state": null
  },
  "consumer": {
    "firstName": "John",
    "lastName": "Smith",
    "middleName": ".",
    "emailAddress": "john.smith@smithentreprise.com",
    "title": "Mr",
    "culture": "en-de",
    "dateOfBirth": "1995-01-26",
    "gender": "M",
    "mobilePhone": "1285765191221",
    "homePhone": "1285765191221",
    "workPhone": "1285765191221",
    "taxId": "DE1927456229"
  },
  "businessConsumer": {
    "companyName": "Smith Enterprises Ltd.",
    "companyType": "GmbH",
    "emailAddress": "contact@smithenterprises.com",
    "taxId": "DE123456789",
    "culture": "en-DE",
    "companyRegistrationNumber": "HRB 123456",
    "companyRegistrationCountryCode": "DE"
  }
}

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

traceIdstring

Internally generated trace_id for this error message so it can be found easily in the logs.

errors object[]
Array [
messagestring
A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.
codestring
A pre-defined code from the list of error codes.
propertystring
The property from the request object which the error is linked to.
context object
A json object containing a list of predefined properties which are filled based on the error.
typestring
minimumnumber
maximumnumber
maxLengthinteger
allowedValuesstring[]
]

Example (auto)

{
  "traceId": "string",
  "errors": [
    {
      "message": "string",
      "code": "string",
      "property": "string",
      "context": {
        "type": "string",
        "minimum": 0,
        "maximum": 0,
        "maxLength": 0,
        "allowedValues": [
          "string"
        ]
      }
    }
  ]
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}