Skip to main content

Get Subscription

GET 
/subscriptions/:subscriptionId

Returns the details of a specific subscription based on the provided subscription ID.

info

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

Request​

Path Parameters

    subscriptionId stringrequired

    Unique Identifier of the created Subscription. Format: Subscription + - + <UUID>

    Example: Subscription-caf9b798-315b-40aa-9659-cf732f55d847

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}

Responses​

Successful response

Schema
    idstringrequired

    Subscription ID automatically generated by the system.

    Possible values: <= 100 characters

    Example: Subscription-39ab7cc3-57d7-42d7-ad24-a7b8a4164880
    createdAtstring<date-time>required

    Timestamp of when the Subscription was created.

    Possible values: <= 30 characters

    Example: 2024-10-31T14:30:10.51Z
    updatedAtstring<date-time>required

    Timestamp of when the Subscription was last updated.

    Possible values: <= 30 characters

    Example: 2024-10-31T14:30:10.51Z
    deletedAtstring<date-time>nullable

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

    Possible values: <= 30 characters

    planIdstringrequired

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

    Possible values: <= 100 characters

    Example: SubscriptionPlan-700be03c-b1b0-4bea-8971-7f18bdc10d10
    statusstringrequired

    Status of the subscription.

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

    Example: created
    payment objectrequired

    Payment details for the subscription.

    descriptionstringrequired

    Description of the payment plan.

    Possible values: <= 255 characters

    recurrentAmountnumber<decimal>required

    Amount to be charged per billing cycle.

    Possible values: <= 60 characters

    currencyIsoCodestringrequired

    Currency of the payment.

    Possible values: <= 3 characters

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

    Possible values: <= 10 characters

    trialEndDatestring<date>required

    End date of the trial period.

    Possible values: <= 10 characters

    nextBillingDatestring<date>required

    Next scheduled billing date.

    Possible values: <= 10 characters

    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

    customerAccountIdstringrequired

    Customer account associated with the subscription.

    Possible values: <= 125 characters

    merchantMetadatastringnullable

    Metadata provided by the merchant.

    Possible values: <= 255 characters

    externalMerchantIdstringnullable

    External merchant identifier.

    Possible values: <= 255 characters

    billingAgreement objectrequired

    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 address associated with the subscription.

    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

    Shipping address associated with the subscription.

    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 objectrequired

    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
    pausePeriodDaysintegernullable

    Number of days the subscription is paused.

    Possible values: >= 0

    billingNotificationDatestring<date-time>nullable

    Date of the last billing notification.

    Possible values: <= 30 characters

    scheduledBillingCyclesRemainingintegernullable

    Number of scheduled billing cycles remaining.

    Possible values: <= 2 characters, >= 0

    scheduledAmountnumber<decimal>nullable

    Scheduled amount for upcoming billing.

    pendingPaymentsbooleannullable

    Indicates if there are pending payments.

    actionRequiredbooleannullable

    Indicates if any action is required from the merchant or customer.

    extraInfoobjectnullable

    Additional information related to the subscription.

    customReferencesobjectnullable

    Custom references associated with the subscription.

    criteria object[]nullable

    An array of key-value pair objects. Please refer to Data Model for details.

  • Array [
    • namestring
    valuestring
  • ]
    • targetMerchantAccountReferencestringnullable

    Target merchant account reference if applicable.

    Possible values: <= 100 characters

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