The Subscription Object

{
  "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f",
  "external_id": "a9x7bq2lmw5p",
  "name": "Disney+, Hulu Bundle Premium",
  "description": "Ad-free streaming with Disney+ and Hulu",
  "merchant": {
    "id": 18,
    "name": "Hulu",
    "category": "Streaming",
    "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png"
  },
  "status": "ACTIVE",
  "billing_cycle": "RECURRING_MONTHLY",
  "next_billing_date": "2026-02-10",
  "last_billing_date": "2026-01-10",
  "start_date": "2025-06-15",
  "expiration_date": null,
  "payment_method": {
    "type": "CARD",
    "brand": "VISA",
    "last_four": "1234"
  },
  "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription.",
  "is_paid": true,
  "is_family_plan": false,
  "is_cancellable": true,
  "price": {
    "total": "11.99",
    "currency": "USD"
  }
}

string

Unique identifier for the subscription.

Example:

"13da3c28-a068-4642-9ce2-b730cfda5f5f"

external_id

string

External identifier for the subscription provided by the merchant.

Example:

"a9x7bq2lmw5p"

name

string

Human-readable subscription name as displayed by the merchant.

Example:

"Disney+, Hulu Bundle Premium"

description

string | null

Description of the subscription plan.

Example:

"Ad-free streaming with Disney+ and Hulu"

merchant

object

The merchant account linked by the user.

Show child attributes

status

Billing and access ongoing.

Allowed value: "ACTIVE"

Example:

"ACTIVE"

billing_cycle

enum<string>

Billing cycle of the subscription.

Available options:

RECURRING_MONTHLY,

RECURRING_BIMONTHLY,

RECURRING_WEEKLY,

RECURRING_BIWEEKLY,

RECURRING_QUARTERLY,

RECURRING_SEMIANNUALLY,

RECURRING_ANNUALLY,

RECURRING_DAILY,

ONE_TIME,

UNRECOGNIZED

Example:

"RECURRING_MONTHLY"

next_billing_date

string<date> | null

Date of the next scheduled charge in UTC. ISO 8601 format (YYYY-MM-DD).

Example:

"2026-02-10"

last_billing_date

string<date> | null

Date of the most recent attempted charge in UTC. ISO 8601 format (YYYY-MM-DD).

Example:

"2026-01-10"

start_date

string<date> | null

Start date for the subscription in UTC. ISO 8601 format (YYYY-MM-DD).

Example:

"2025-06-15"

expiration_date

string<date> | null

Date of the loss of access to the subscription due to cancellation or other means in UTC. ISO 8601 format (YYYY-MM-DD).

Example:

null

payment_method

object

Show child attributes

Example:

{
  "type": "CARD",
  "brand": "VISA",
  "last_four": "1234"
}

cancel_instructions

string | null

Instructions for cancelling the subscription, if available.

Example:

"You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription."

is_paid

boolean | null

Whether the subscription is a paid plan or free.

Example:

true

is_free_trial

boolean | null

Whether the subscription is currently in a free trial period, or was suspended or cancelled while in one.

Example:

false

is_family_plan

boolean | null

Whether the subscription is a family plan.

Example:

false

is_cancellable

boolean

Indicates whether the merchant has marked this subscription as cancellable.

Example:

true

price

object | null

Show child attributes

Overview

Supernova

Development

Sessions

CardSwitcher

TransactionLink

SubscriptionManager

Shopping

Merchants

Merchant Accounts

Detected Accounts

Users

Audit Logs

Agent Authorization

Webhook Endpoints

Request Logs

The Subscription Object