Skip to main content

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}

Body

required

    page integer

    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.

    pageSize integer

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

    createdAtLte date-time

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

    createdAtGte date-time

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

    updatedAtLte date-time

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

    updatedAtGte date-time

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

    trialStartDateGte date

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

    trialStartDateLte date

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

    trialEndDateGte date

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

    trialEndDateLte date

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

    nextBillingDateGte date

    Possible values: <= 10 characters

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

    nextBillingDateLte date

    Possible values: <= 10 characters

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

    deleted string

    Possible values: [true, false]

    Possible values: true, false

    planId string

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

    externalMerchantId string

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

Responses​

Successful response

Schema

    page integer

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

    pageSize integer

    Number of the records to display per page.

    count integer

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

    totalPages integer

    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 [

    • 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.

  • ]

Loading...
 Imprint
|
Data protection and privacy
© 2025 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.