Get All Subscriptions

GET 
/subscriptions

Returns a list of all subscriptions with pagination based on the filters passed on as query parameters.

info

If a query parameter not listed below is included in the request, it will be ignored. Similarly, any query parameter with an invalid value will also be disregarded.

info

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

tip

Gte: Greater Than or Equal >=
Lte: Lower Than or Equal <=

Request

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

pageinteger

Number of the desired page for which data should be returned. Page numbers use zero-based numbering e.g., to get the 10th page, you need to set page=9.

pageSizeinteger

Number of Plans per Page requested (e.g., 10).

createdAtLtestring<date-time>

Created before the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

createdAtGtestring<date-time>

Created after the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

updatedAtLtestring<date-time>

Updated before the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

updatedAtGtestring<date-time>

Updated after the provided date & time. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z'

trialStartDateGtestring<date>

Trial starts after or on the same provided date. Format: yyyy-MM-dd

trialStartDateLtestring<date>

Trial starts before or on the same provided date. Format: yyyy-MM-dd

trialEndDateGtestring<date>

Trial ends after or on the same provided date. Format: yyyy-MM-dd

trialEndDateLtestring<date>

Trial ends before or on the same provided date. Format: yyyy-MM-dd

nextBillingDateGtestring<date>

Next billing date is after or on the same provided date. Format: yyyy-MM-dd

Possible values: <= 10 characters

nextBillingDateLtestring<date>

Next billing date is before or on the same provided date. Format: yyyy-MM-dd

Possible values: <= 10 characters

deletedstring

Possible values: true, false

Possible values: [true, false]

planIdstring

Id of the Subscription Plan. Example: SubscriptionPlan-3613bc8b-7a78-47b5-b19d-17fd9575fef9

externalMerchantIdstring

External merchant identifier provided during the creation of subscription(s)

Example (auto)

{
  "page": 0,
  "pageSize": 0,
  "createdAtLte": "2024-07-29T15:51:28.071Z",
  "createdAtGte": "2024-07-29T15:51:28.071Z",
  "updatedAtLte": "2024-07-29T15:51:28.071Z",
  "updatedAtGte": "2024-07-29T15:51:28.071Z",
  "trialStartDateGte": "2024-07-29",
  "trialStartDateLte": "2024-07-29",
  "trialEndDateGte": "2024-07-29",
  "trialEndDateLte": "2024-07-29",
  "nextBillingDateGte": "2024-07-29",
  "nextBillingDateLte": "2024-07-29",
  "deleted": true,
  "planId": "string",
  "externalMerchantId": "string"
}

Responses

200

Successful response

application/json

Schema

Schema

pageinteger

Number of the page for which the data is to be returned.

pageSizeinteger

Number of the records to display per page.

countinteger

Number of total records (Subscriptions) returned for the made search/request.

totalPagesinteger

Number of pages returned for the made search/request.

data object[]
List of all the Subscription of the page requested. For the Subscription output parameters specification, please refer to Get Subscription API outputs section.
Array [
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)

{
  "page": 0,
  "pageSize": 0,
  "count": 0,
  "totalPages": 0,
  "data": [
    {
      "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"
      }
    }
  ]
}

Example

{
  "page": 1,
  "pageSize": 2,
  "count": 27,
  "totalPages": 14,
  "data": [
    {
      "id": "Subscription-234956e0-96d8-4205-8dd4-d8fa5714c804",
      "createdAt": "2021-03-18T15:45:36.33Z",
      "updatedAt": "2021-03-18T15:45:36.33Z",
      "deletedAt": null,
      "planId": "SubscriptionPlan-5098594c-5483-4faa-a36d-3ba9ac33b095",
      "status": "created",
      "payment": {
        "description": "Premium music for only 25 EUR!",
        "recurrentAmount": 20.99,
        "currencyIsoCode": "EUR"
      },
      "startDate": "2021-03-09T15:30:44.718-08:00",
      "trialStartDate": "2022-03-09",
      "trialEndDate": "2022-03-10",
      "nextBillingDate": "2022-04-10",
      "billingCyclesRemaining": 1,
      "customerAccountId": "d58c3076-b496-4a3a-bc8f-d2a55af5794a",
      "merchantMetadata": "{\"usage\": 250, \"client\": 1248052792, \"monitor\": true }",
      "externalMerchantId": "client_21507252",
      "billingAgreement": null,
      "billingAddress": {
        "addressLine1": "Wall st. , NY",
        "addressLine2": "Building 442A22",
        "addressLine3": "7th floor",
        "number": "224",
        "city": "NEW YORK",
        "postCode": "NEW YORK",
        "countryCode": "USA",
        "state": "AR"
      },
      "shippingAddress": {
        "addressLine1": "Wall st. , NY",
        "addressLine2": "Building 442A22",
        "addressLine3": "7th floor",
        "number": "224",
        "city": "NEW YORK",
        "postCode": "NEW YORK",
        "countryCode": "US",
        "state": "AR"
      },
      "consumer": {
        "firstName": "John",
        "lastName": "Smith",
        "middleName": ".",
        "emailAddress": "john.smith@smithenterprise.com",
        "title": "Mr",
        "culture": "en-de",
        "dateOfBirth": "1995-01-26",
        "gender": "M",
        "mobilePhone": "1285765191221",
        "homePhone": "1285765191221",
        "workPhone": "1285765191221",
        "taxId": "DE1927456229"
      }
    }
  ]
}

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