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

required

billingAddress

object

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

shippingAddress

object

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

consumer

object

nullable

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.

firstName stringrequired

Possible values: <= 60 characters

First name of the consumer.

lastName stringrequired

Possible values: <= 60 characters

Last name of the consumer.

middleName stringnullable

Possible values: <= 60 characters

Middle name of the consumer.

emailAddress emailrequired

Possible values: <= 255 characters

Email address of the customer.

title stringrequired

Possible values: <= 3 characters, [Mr, Mrs, Ms]

Title of the consumer.

culture string

Possible values: <= 5 characters

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.

dateOfBirth daterequired

Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.

gender string

Possible values: [M, F, D]

Gender of the consumer.

mobilePhone string

Possible values: <= 30 characters

Mobile phone of the customer.

homePhone string

Possible values: <= 30 characters

Home phone of the customer.

workPhone string

Possible values: <= 30 characters

Work phone of the customer.

taxId stringnullable

Possible values: <= 30 characters

Tax ID of the consumer.

businessConsumer

object

nullable

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.

companyName stringrequired

Possible values: <= 100 characters

Company legal entity name.

companyType stringrequired

Possible values: <= 100 characters

Company legal entity type (e.g., GmbH).

emailAddress stringrequired

Possible values: <= 255 characters

Customer's email address.

taxId stringnullable

Possible values: <= 30 characters

Tax identification number.

culture stringnullable

Possible values: <= 5 characters

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.

companyRegistrationNumber stringnullable

Possible values: <= 50 characters

Company registration number

companyRegistrationCountryCode stringnullable

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

ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.

billingCyclesRemaining integer

Possible values: <= 2 characters

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.

status string

Possible values: [active, paused]

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

Responses

200

Subscription updated successfully

application/json

Schema

Schema

id stringrequired

Possible values: <= 49 characters

Subscription ID automatically generated by the system.

createdAt date-timerequired

Timestamp of when the Subscription was created.

updatedAt date-timerequired

Timestamp of when the Subscription was last updated.

deletedAt date-timenullable

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

planId stringrequired

Possible values: <= 255 characters

Plan ID of the existing plan under which the Subscription was created.

status stringrequired

Possible values: <= 8 characters, [created, pending, trial, active, overdue, canceled, expired, paused]

Status of the subscription.

payment

object

required

Payment details of the Subscription created inherited from the provided plan. Please refer to Data Model for details.

description string

Possible values: <= 60 characters

Description of the payment or plan.

recurrentAmount decimalrequired

Possible values: <= 60 characters

Recurrent amount to charge the customer.

currencyIsoCode stringrequired

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

Currency of the charges. Format ISO 4217.

startDate date-timerequired

The start date of the subscription. It cannot be in the past.

timezone string

Possible values: <= 32 characters

TZ database name in List of TZ Database Time Zones.

trialStartDate daterequired

Start Date of the Trial (if applicable).

trialEndDate daterequired

End Date of the Trial (if applicable).

nextBillingDate daterequired

Possible values: <= 10 characters

Date of the upcoming billing when the customer would be charged.

billingCyclesRemaining integerrequired

Possible values: <= 2 characters

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.

customerAccountId stringrequired

Possible values: <= 125 characters

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.

merchantMetadata stringnullable

Possible values: <= 255 characters

Field that allows the merchant to store specific metadata linked with the subscription.

externalMerchantId stringnullable

Possible values: <= 255 characters

Field that allows the merchant to store a specific value for external reference.

billingAgreement

object

nullable

required

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

id stringrequired

Possible values: <= 50 characters

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

paymentObjectId stringrequired

PaymentObject used for billing this subscription.

billingAgreementDate date-timerequired

Possible values: <= 24 characters

Date when the billing agreement was created.

name stringrequired

Possible values: <= 255 characters

Display name of the payment option which has been stored.

code stringrequired

Possible values: <= 255 characters

Code of the payment option which has been stored.

carrierNumber string

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

isExpired booleanrequired

Possible values: [true, false]

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

expiryDate stringrequired

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

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

storedPaymentOptionData objectnullable

Additional data related to the stored payment option.

billingAddress

object

required

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

shippingAddress

object

required

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

addressLine1 stringrequired

Possible values: <= 60 characters

Address line 1.

addressLine2 stringnullable

Possible values: <= 60 characters

Address line 2.

addressLine3 stringnullable

Possible values: <= 60 characters

Address line 3.

number stringrequired

Possible values: <= 10 characters

House number/building number.

city stringrequired

Possible values: <= 50 characters

City name of the address.

postCode stringrequired

Possible values: <= 10 characters

Postal code of the address.

countryCode stringrequired

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

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

state stringnullable

Possible values: <= 3 characters

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

consumer

object

nullable

required

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.

firstName stringrequired

Possible values: <= 60 characters

First name of the consumer.

lastName stringrequired

Possible values: <= 60 characters

Last name of the consumer.

middleName stringnullable

Possible values: <= 60 characters

Middle name of the consumer.

emailAddress emailrequired

Possible values: <= 255 characters

Email address of the customer.

title stringrequired

Possible values: <= 3 characters, [Mr, Mrs, Ms]

Title of the consumer.

culture string

Possible values: <= 5 characters

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.

dateOfBirth daterequired

Date of birth. Dummy data acceptable. Format “YYYY-MM-DD”.

gender string

Possible values: [M, F, D]

Gender of the consumer.

mobilePhone string

Possible values: <= 30 characters

Mobile phone of the customer.

homePhone string

Possible values: <= 30 characters

Home phone of the customer.

workPhone string

Possible values: <= 30 characters

Work phone of the customer.

taxId stringnullable

Possible values: <= 30 characters

Tax ID of the consumer.

businessConsumer

object

nullable

required

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.

companyName stringrequired

Possible values: <= 100 characters

Company legal entity name.

companyType stringrequired

Possible values: <= 100 characters

Company legal entity type (e.g., GmbH).

emailAddress stringrequired

Possible values: <= 255 characters

Customer's email address.

taxId stringnullable

Possible values: <= 30 characters

Tax identification number.

culture stringnullable

Possible values: <= 5 characters

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.

companyRegistrationNumber stringnullable

Possible values: <= 50 characters

Company registration number

companyRegistrationCountryCode stringnullable

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

ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.

Example (from schema)

{
  "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.718-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

traceId string

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

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

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.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "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

traceId string

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

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

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.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "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

traceId string

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

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

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.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "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

traceId string

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

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

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.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "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

traceId string

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

errors

object[]

Array [

message string

A predefined string which describes the error. The purpose of the message is to allow for future usage of translation.

code string

A pre-defined code from the list of error codes.

property string

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.

type string

minimum number

maximum number

maxLength integer

allowedValues string[]

]

Example (from schema)

{
  "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."
    }
  ]
}

Loading...