Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-26336777.7 KB

get/subscription/get-subscription/{subscriptionId}

Path parameters

subscriptionIdstring required
Example:sub_fooBOwYsaK50AEfK

Unique identifier of the subscription

Response

Successful response with subscription details

subscriptionIdstring

Unique identifier of the subscription

interval'DAY' | 'WEEK' | 'MONTH' | 'YEAR'

The interval group between subscriptions.

intervalCountinteger

The number of intervals between subscription billings. For example, interval = MONTH and intervalCount = 3 bills every 3 months.

cycleCountinteger

The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.

remainingCycleCountinteger

The number of billing cycles remaining for the subscription.

currencystring

Three-letter currency code

amountinteger

The amount in lowest count unit (e.g., cents for USD)

presentmentCurrencystring

The currency that the customer paid in

createdAtstring date-time

Timestamp of when the subscription was created

statusstring

The status of the subscription. Refer subscription statuses

upfrontAmountinteger

The amount charged to the customer at the time the subscription was activated. This replaces the first billing cycle charge; regular billing resumes from the next cycle.

trialPeriodCountinteger

The number of trial periods before the first billing cycle.

trialPeriodInterval'DAY' | 'WEEK' | 'MONTH' | 'YEAR'

The interval for the trial period.

metadataobject

A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.

Constraints:

  • Maximum of 50 key-value pairs allowed.
  • Each key must be no longer than 40 characters.
  • Each value must be a string and cannot exceed 500 characters.
updatePaymentMethodLinkstring

The URL to redirect the customer to the xPay payment gateway for updating the payment method. Available only for subscriptions in TRIALING, ACTIVE, or UNPAID status.

Example response

{
  "subscriptionId": "sub_fooBOwYsaK50AEfK",
  "interval": "MONTH",
  "intervalCount": 2,
  "cycleCount": 2,
  "remainingCycleCount": 2,
  "currency": "USD",
  "amount": 100,
  "presentmentCurrency": "USD",
  "createdAt": "2024-09-26T10:41:50.472+00:00",
  "status": "CREATED",
  "upfrontAmount": 200,
  "trialPeriodCount": 7,
  "trialPeriodInterval": "DAY",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  },
  "updatePaymentMethodLink": "https://pay.xpaycheckout.com/subscription/update?subscription_id=sub_123",
  "paymentMetadata": {
    "paymentMethod": "CARD",
    "cardMetadata": {
      "brand": "visa",
      "country": "US",
      "lastFourDigit": "4242",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "cardType": "CREDIT"
    },
    "cardInstallmentMetadata": {
      "cardInstallmentTenure": "three"
    }
  }
}