API reference

Subscriptions

Subscriptions allow you to charge a customer on a recurring basis. Related guide: Creating subscriptions

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a subscription

POST/v1/subscriptions

Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions. When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment. To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

Body parameters

  • add_invoice_itemsarray of objects

    A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.

    Show 8 child parameters
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • periodobject
      Show 2 child parameters
    • pricestring
    • price_dataobject
      Show 5 child parameters
      • currencystringRequired
      • productstringRequired
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • application_fee_percentnumber

    A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

  • automatic_taxobject

    Automatic tax settings for this subscription.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • backdate_start_dateinteger

    A past timestamp to backdate the subscription's start date to. If set, the first invoice will contain line items for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.

  • billing_cycle_anchorinteger

    A future timestamp in UTC format to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals.

  • billing_cycle_anchor_configobject

    Mutually exclusive with billing_cycle_anchor and only valid with monthly and yearly price intervals. When provided, the billing_cycle_anchor is set to the next occurrence of the day_of_month at the hour, minute, and second UTC.

    Show 5 child parameters
    • day_of_monthintegerRequired
    • hourinteger
    • minuteinteger
    • monthinteger
    • secondinteger
  • billing_modeobject

    Controls how prorations and invoices for subscriptions are calculated and orchestrated.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • classic
      • flexible
    • flexibleobject
      Show 1 child parameter
      • proration_discountsstring
        Possible values
        • included
        • itemized
  • billing_schedulesarray of objects

    An array of billing schedules, which allow you to bill customers in advance for multiple service periods. Requires flexible billing mode and API version 2026-05-27.dahlia or later. Learn more about prebilling.

    Show 3 child parameters
    • bill_untilobjectRequired
      Show 3 child parameters
      • typestringRequired
        Possible values
        • duration
        • timestamp
      • durationobject

        Child parameters are listed in the OpenAPI document.

      • timestampinteger
    • applies_toarray of objects
      Show 2 child parameters
      • typestringRequired
        Possible values
        • price
      • pricestring
    • keystring
  • billing_thresholdsobject

    Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.

    Show 2 child parameters
    • amount_gteinteger
    • reset_billing_cycle_anchorboolean
  • cancel_atinteger | string

    A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period.

    Possible values
    • max_billed_until
    • max_period_end
    • min_period_end
  • cancel_at_period_endboolean

    Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false.

  • collection_methodstring

    Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically.

    Possible values
    • charge_automatically
    • send_invoice
  • currencystring

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • customerstring

    The identifier of the customer to subscribe.

  • customer_accountstring

    The identifier of the account representing the customer to subscribe.

  • days_until_dueinteger

    Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice.

  • default_payment_methodstring

    ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_sourcestring

    ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_tax_ratesarray of strings

    The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription.

  • descriptionstring

    The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.

  • discountsarray of objects

    The coupons to redeem into discounts for the subscription. If not specified or empty, inherits the discount from the subscription's customer.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_settingsobject

    All invoices will be billed using the specified settings.

    Show 5 child parameters
    • account_tax_idsarray of strings
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • descriptionstring
    • footerstring
    • issuerobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • itemsarray of objects

    A list of up to 20 subscription items, each with an attached price.

    Show 7 child parameters
    • billing_thresholdsobject
      Show 1 child parameter
      • usage_gteintegerRequired
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • pricestring
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstringRequired
      • recurringobjectRequired

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • off_sessionboolean

    Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session).

  • on_behalf_ofstring

    The account on behalf of which to charge, for each of the subscription's invoices.

  • payment_behaviorstring

    Controls how Stripe handles the first invoice when payment is required and collection_method=charge_automatically. Subscriptions with collection_method=send_invoice are automatically activated regardless of the first Invoice status.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • payment_settingsobject

    Payment settings to pass to invoices created by the subscription.

    Show 3 child parameters
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
    • save_default_payment_methodstring
      Possible values
      • off
      • on_subscription
  • pending_invoice_item_intervalobject

    Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.

    Show 2 child parameters
    • intervalstringRequired
      Possible values
      • day
      • month
      • week
      • year
    • interval_countinteger
  • proration_behaviorstring

    Determines how to handle prorations resulting from the billing_cycle_anchor. If no value is passed, the default is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • transfer_dataobject

    If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.

    Show 2 child parameters
    • destinationstringRequired
    • amount_percentnumber
  • trial_endstring | integer

    Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately. Can be at most two years from billing_cycle_anchor. See Using trial periods on subscriptions to learn more.

    Possible values
    • now
  • trial_from_planboolean

    Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more.

  • trial_period_daysinteger

    Integer representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See Using trial periods on subscriptions to learn more.

  • trial_settingsobject

    Settings related to subscription trials.

    Show 1 child parameter
    • end_behaviorobjectRequired
      Show 1 child parameter
      • missing_payment_methodstringRequired
        Possible values
        • cancel
        • create_invoice
        • pause

Returns

The subscription object.

POST /v1/subscriptions
curl -X POST https://api.knoxapi.com/v1/subscriptions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

List subscriptions

GET/v1/subscriptions

By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.

Query parameters

  • automatic_taxobject

    Filter subscriptions by their automatic tax settings.

    Show 1 child parameter
    • enabledbooleanRequired
  • collection_methodstring

    The collection method of the subscriptions to retrieve. Either charge_automatically or send_invoice.

    Possible values
    • charge_automatically
    • send_invoice
  • createdobject | integer

    Only return subscriptions that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • current_period_endobject | integer

    Only return subscriptions whose minimum item current_period_end falls within the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • current_period_startobject | integer

    Only return subscriptions whose maximum item current_period_start falls within the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • customerstring

    The ID of the customer whose subscriptions you're retrieving.

  • customer_accountstring

    The ID of the account representing the customer whose subscriptions you're retrieving.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • pricestring

    Filter for subscriptions that contain this recurring price ID.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • statusstring

    The status of the subscriptions to retrieve. Passing in a value of canceled will return all canceled subscriptions, including those belonging to deleted customers. Pass ended to find subscriptions that are canceled and subscriptions that are expired due to incomplete payment. Passing in a value of all will return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned.

    Possible values
    • active
    • all
    • canceled
    • ended
    • incomplete
    • incomplete_expired
    • past_due
    • paused
    • trialing
    • unpaid
  • test_clockstring

    Filter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set.

Returns

A list of subscription objects.

GET /v1/subscriptions
curl -G https://api.knoxapi.com/v1/subscriptions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
    {
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false,
        "liability": {
          "type": "account"
        },
        "disabled_reason": null
      },
      "billing_cycle_anchor": 1234567890,
      "billing_cycle_anchor_config": {
        "day_of_month": 1361669285,
        "hour": null,
        "minute": null,
        "month": null,
        "second": null
      },
      "cancel_at": 1234567890,
      "canceled_at": 1234567890,
      "cancellation_details": {
        "comment": null,
        "feedback": null,
        "reason": null,
        "feedback_option": null
      },
      "collection_method": "charge_automatically",
      "created": 1234567890,
      "currency": "usd",
      "customer": "cus_QXg1o8vcGmoR32",
      "days_until_due": null,
      "default_payment_method": null,
      "default_source": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "ended_at": 1234567890,
      "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
      "invoice_settings": {
        "account_tax_ids": null,
        "issuer": {
          "type": "self"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": {
        "data": [
          {
            "created": 1721954054,
            "discounts": [],
            "id": "si_QXhVnC2h0Jczwc",
            "metadata": {},
            "object": "subscription_item",
            "price": {
              "active": true,
              "billing_scheme": "per_unit",
              "created": 1721948530,
              "currency": "usd",
              "custom_unit_amount": {
                "maximum": null,
                "minimum": null,
                "preset": null
              },
              "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
              "livemode": false,
              "lookup_key": null,
              "metadata": {},
              "nickname": null,
              "object": "price",
              "product": "prod_QXg1hqf4jFNsqG",
              "recurring": {
                "interval": "month",
                "interval_count": 1,
                "meter": null,
                "usage_type": "licensed",
                "trial_period_days": null
              },
              "tax_behavior": "unspecified",
              "tiers_mode": null,
              "transform_quantity": {
                "divide_by": 1592560163,
                "round": "down"
              },
              "type": "recurring",
              "unit_amount": 2000,
              "unit_amount_decimal": "2000"
            },
            "quantity": 1,
            "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
            "tax_rates": [],
            "plan": {
              "active": true,
              "amount": null,
              "amount_decimal": null,
              "billing_scheme": "tiered",
              "created": 1028554472,
              "currency": "currency",
              "id": "obj_123",
              "interval": "month",
              "interval_count": 797691627,
              "livemode": true,
              "metadata": null,
              "meter": null,
              "nickname": null,
              "object": "plan",
              "product": null,
              "tiers_mode": null,
              "transform_usage": {
                "divide_by": 1592560163,
                "round": "down"
              },
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "current_period_end": 976287773,
            "current_period_start": 1896570518,
            "billing_thresholds": {
              "usage_gte": null
            }
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
      },
      "latest_invoice": null,
      "livemode": false,
      "metadata": {},
      "next_pending_invoice_item_invoice": 1234567890,
      "object": "subscription",
      "on_behalf_of": null,
      "pause_collection": {
        "behavior": "mark_uncollectible",
        "resumes_at": null
      },
      "payment_settings": {
        "payment_method_options": {
          "acss_debit": {},
          "bancontact": {
            "preferred_language": "fr"
          },
          "card": {
            "network": null,
            "request_three_d_secure": null
          },
          "customer_balance": {
            "funding_type": null
          },
          "konbini": {},
          "sepa_debit": {},
          "us_bank_account": {},
          "payto": {},
          "pix": {},
          "upi": {},
          "billie": {}
        },
        "payment_method_types": null,
        "save_default_payment_method": null
      },
      "pending_invoice_item_interval": {
        "interval": "month",
        "interval_count": 797691627
      },
      "pending_setup_intent": null,
      "pending_update": {
        "billing_cycle_anchor": null,
        "discount": {
          "checkout_session": null,
          "customer": null,
          "end": null,
          "id": "obj_123",
          "invoice": null,
          "invoice_item": null,
          "object": "discount",
          "promotion_code": null,
          "start": 109757538,
          "subscription": null,
          "subscription_item": null,
          "source": {
            "coupon": null,
            "type": "coupon"
          },
          "customer_account": null
        },
        "discounts": [],
        "expires_at": 833811170,
        "subscription_items": null,
        "trial_end": null,
        "trial_from_plan": null,
        "metadata": null,
        "cancel_at_period_end": null
      },
      "schedule": null,
      "start_date": 1234567890,
      "status": "active",
      "test_clock": null,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": 1234567890,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": 1234567890,
      "cancel_at_period_end": true,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      },
      "billing_mode": {
        "type": "classic",
        "flexible": {}
      },
      "customer_account": null,
      "managed_payments": {
        "enabled": true
      },
      "billing_schedules": [
        {
          "applies_to": null,
          "bill_until": {
            "computed_timestamp": 2082605468,
            "duration": {
              "interval": "month",
              "interval_count": null
            },
            "timestamp": null,
            "type": "duration"
          },
          "key": "key"
        }
      ]
    }
  ]
}

Search subscriptions

GET/v1/subscriptions/search

Search for subscriptions you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Query parameters

  • querystringRequired

    The search query string. See search query language and the list of supported query fields for subscriptions.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • pagestring

    A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Returns

A search result of subscription objects.

GET /v1/subscriptions/search
curl -G https://api.knoxapi.com/v1/subscriptions/search \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "query=metadata['order_id']:'6735'"
Response
{
  "object": "search_result",
  "url": "/v1/subscriptions/search",
  "has_more": false,
  "data": [
    {
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false,
        "liability": {
          "type": "account"
        },
        "disabled_reason": null
      },
      "billing_cycle_anchor": 1234567890,
      "billing_cycle_anchor_config": {
        "day_of_month": 1361669285,
        "hour": null,
        "minute": null,
        "month": null,
        "second": null
      },
      "cancel_at": 1234567890,
      "canceled_at": 1234567890,
      "cancellation_details": {
        "comment": null,
        "feedback": null,
        "reason": null,
        "feedback_option": null
      },
      "collection_method": "charge_automatically",
      "created": 1234567890,
      "currency": "usd",
      "customer": "cus_QXg1o8vcGmoR32",
      "days_until_due": null,
      "default_payment_method": null,
      "default_source": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "ended_at": 1234567890,
      "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
      "invoice_settings": {
        "account_tax_ids": null,
        "issuer": {
          "type": "self"
        },
        "custom_fields": null,
        "description": null,
        "footer": null
      },
      "items": {
        "data": [
          {
            "created": 1721954054,
            "discounts": [],
            "id": "si_QXhVnC2h0Jczwc",
            "metadata": {},
            "object": "subscription_item",
            "price": {
              "active": true,
              "billing_scheme": "per_unit",
              "created": 1721948530,
              "currency": "usd",
              "custom_unit_amount": {
                "maximum": null,
                "minimum": null,
                "preset": null
              },
              "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
              "livemode": false,
              "lookup_key": null,
              "metadata": {},
              "nickname": null,
              "object": "price",
              "product": "prod_QXg1hqf4jFNsqG",
              "recurring": {
                "interval": "month",
                "interval_count": 1,
                "meter": null,
                "usage_type": "licensed",
                "trial_period_days": null
              },
              "tax_behavior": "unspecified",
              "tiers_mode": null,
              "transform_quantity": {
                "divide_by": 1592560163,
                "round": "down"
              },
              "type": "recurring",
              "unit_amount": 2000,
              "unit_amount_decimal": "2000"
            },
            "quantity": 1,
            "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
            "tax_rates": [],
            "plan": {
              "active": true,
              "amount": null,
              "amount_decimal": null,
              "billing_scheme": "tiered",
              "created": 1028554472,
              "currency": "currency",
              "id": "obj_123",
              "interval": "month",
              "interval_count": 797691627,
              "livemode": true,
              "metadata": null,
              "meter": null,
              "nickname": null,
              "object": "plan",
              "product": null,
              "tiers_mode": null,
              "transform_usage": {
                "divide_by": 1592560163,
                "round": "down"
              },
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "current_period_end": 976287773,
            "current_period_start": 1896570518,
            "billing_thresholds": {
              "usage_gte": null
            }
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
      },
      "latest_invoice": null,
      "livemode": false,
      "metadata": {},
      "next_pending_invoice_item_invoice": 1234567890,
      "object": "subscription",
      "on_behalf_of": null,
      "pause_collection": {
        "behavior": "mark_uncollectible",
        "resumes_at": null
      },
      "payment_settings": {
        "payment_method_options": {
          "acss_debit": {},
          "bancontact": {
            "preferred_language": "fr"
          },
          "card": {
            "network": null,
            "request_three_d_secure": null
          },
          "customer_balance": {
            "funding_type": null
          },
          "konbini": {},
          "sepa_debit": {},
          "us_bank_account": {},
          "payto": {},
          "pix": {},
          "upi": {},
          "billie": {}
        },
        "payment_method_types": null,
        "save_default_payment_method": null
      },
      "pending_invoice_item_interval": {
        "interval": "month",
        "interval_count": 797691627
      },
      "pending_setup_intent": null,
      "pending_update": {
        "billing_cycle_anchor": null,
        "discount": {
          "checkout_session": null,
          "customer": null,
          "end": null,
          "id": "obj_123",
          "invoice": null,
          "invoice_item": null,
          "object": "discount",
          "promotion_code": null,
          "start": 109757538,
          "subscription": null,
          "subscription_item": null,
          "source": {
            "coupon": null,
            "type": "coupon"
          },
          "customer_account": null
        },
        "discounts": [],
        "expires_at": 833811170,
        "subscription_items": null,
        "trial_end": null,
        "trial_from_plan": null,
        "metadata": null,
        "cancel_at_period_end": null
      },
      "schedule": null,
      "start_date": 1234567890,
      "status": "active",
      "test_clock": null,
      "transfer_data": {
        "amount_percent": null,
        "destination": {
          "id": "obj_123",
          "object": "account"
        }
      },
      "trial_end": 1234567890,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": 1234567890,
      "cancel_at_period_end": true,
      "billing_thresholds": {
        "amount_gte": null,
        "reset_billing_cycle_anchor": null
      },
      "billing_mode": {
        "type": "classic",
        "flexible": {}
      },
      "customer_account": null,
      "managed_payments": {
        "enabled": true
      },
      "billing_schedules": [
        {
          "applies_to": null,
          "bill_until": {
            "computed_timestamp": 2082605468,
            "duration": {
              "interval": "month",
              "interval_count": null
            },
            "timestamp": null,
            "type": "duration"
          },
          "key": "key"
        }
      ]
    }
  ],
  "next_page": null
}

Update a subscription

POST/v1/subscriptions/{subscription_exposed_id}

Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the create preview endpoint. By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a 100 price, they’ll be billed 100 immediately. If on May 15 they switch to a 200 price, then on June 1 they’ll be billed 250 (200 for a renewal of her subscription, plus a 50 prorating adjustment for half of the previous month’s 100 difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes. You can also use scripts to prorate your billing. To learn more, see Prorations. Switching prices does not normally change the billing date or generate an immediate charge unless: The billing interval is changed (for example, from monthly to yearly). The subscription moves from free to paid. A trial starts or ends. In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how Stripe immediately attempts payment for subscription changes. If you want to charge for an upgrade immediately, pass proration_behavior as always_invoice to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass create_prorations, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually invoice the customer. If you don’t want to prorate, set the proration_behavior option to none. With this option, the customer is billed 100 on May 1 and 200 on June 1. Similarly, if you set proration_behavior to none when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription. Updating the quantity on a subscription many times in an hour may result in rate limiting. If you need to bill for a frequently changing quantity, consider integrating usage-based billing instead.

Path parameters

  • subscription_exposed_idstringRequired

Body parameters

  • add_invoice_itemsarray of objects

    A list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.

    Show 8 child parameters
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • periodobject
      Show 2 child parameters
    • pricestring
    • price_dataobject
      Show 5 child parameters
      • currencystringRequired
      • productstringRequired
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • application_fee_percentnumber

    A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

  • automatic_taxobject

    Automatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • billing_cycle_anchorstring

    Either now or unchanged. Setting the value to now resets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle documentation.

    Possible values
    • now
    • unchanged
  • billing_schedulesarray of objects

    An array of billing schedules, which allow you to bill customers in advance for multiple service periods. Requires flexible billing mode and API version 2026-05-27.dahlia or later. Learn more about prebilling.

    Show 3 child parameters
    • applies_toarray of objects
      Show 2 child parameters
      • typestringRequired
        Possible values
        • price
      • pricestring
    • bill_untilobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • duration
        • timestamp
      • durationobject

        Child parameters are listed in the OpenAPI document.

      • timestampinteger
    • keystring
  • billing_thresholdsobject

    Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.

    Show 2 child parameters
    • amount_gteinteger
    • reset_billing_cycle_anchorboolean
  • cancel_atinteger | string

    A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period.

    Possible values
    • max_billed_until
    • max_period_end
    • min_period_end
  • cancel_at_period_endboolean

    Indicate whether this subscription should cancel at the end of the current period (current_period_end).

  • cancellation_detailsobject

    Details about why this subscription was cancelled

    Show 3 child parameters
    • commentstring
    • feedbackstring
      Possible values
      • customer_service
      • low_quality
      • missing_features
      • other
      • switched_service
      • too_complex
      • too_expensive
      • unused
    • feedback_optionstring
  • collection_methodstring

    Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically.

    Possible values
    • charge_automatically
    • send_invoice
  • days_until_dueinteger

    Number of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where collection_method is set to send_invoice.

  • default_payment_methodstring

    ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_sourcestring

    ID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If default_payment_method is also set, default_payment_method will take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.

  • default_tax_ratesarray of strings

    The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription. Pass an empty string to remove previously-defined tax rates.

  • descriptionstring

    The subscription's description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.

  • discountsarray of objects

    The coupons to redeem into discounts for the subscription. A populated array overwrites the existing discounts on the subscription. If not specified or empty array, it leaves the subscription's discounts unchanged. If empty string, it clears the subscription's discounts.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_settingsobject

    All invoices will be billed using the specified settings.

    Show 5 child parameters
    • account_tax_idsarray of strings
    • custom_fieldsarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired
    • descriptionstring
    • footerstring
    • issuerobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • itemsarray of objects

    A list of up to 20 subscription items, each with an attached price.

    Show 10 child parameters
    • billing_thresholdsobject
      Show 1 child parameter
      • usage_gteintegerRequired
    • clear_usageboolean
    • deletedboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • idstring
    • metadataobject
    • pricestring
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstringRequired
      • recurringobjectRequired

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • off_sessionboolean

    Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to false (on-session).

  • on_behalf_ofstring

    The account on behalf of which to charge, for each of the subscription's invoices.

  • pause_collectionobject

    If specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to paused. Learn more about pausing collection.

    Show 2 child parameters
    • behaviorstringRequired
      Possible values
      • keep_as_draft
      • mark_uncollectible
      • void
    • resumes_atinteger
  • payment_behaviorstring

    Controls how Stripe handles payment when a subscription update requires payment and collection_method=charge_automatically.

    Possible values
    • allow_incomplete
    • default_incomplete
    • error_if_incomplete
    • pending_if_incomplete
  • payment_settingsobject

    Payment settings to pass to invoices created by the subscription.

    Show 3 child parameters
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
    • save_default_payment_methodstring
      Possible values
      • off
      • on_subscription
  • pending_invoice_item_intervalobject

    Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.

    Show 2 child parameters
    • intervalstringRequired
      Possible values
      • day
      • month
      • week
      • year
    • interval_countinteger
  • proration_behaviorstring

    Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item's quantity changes. The default value is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • proration_dateinteger

    If set, prorations will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same prorations that were previewed with the create preview endpoint. proration_date can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.

  • transfer_dataobject

    If specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges. This will be unset if you POST an empty value.

    Show 2 child parameters
    • destinationstringRequired
    • amount_percentnumber
  • trial_endstring | integer

    Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The billing_cycle_anchor will be updated to the trial_end value. The special value now can be provided to end the customer's trial immediately. Can be at most two years from billing_cycle_anchor.

    Possible values
    • now
  • trial_from_planboolean

    Indicates if a plan's trial_period_days should be applied to the subscription. Setting trial_end per subscription is preferred, and this defaults to false. Setting this flag to true together with trial_end is not allowed. See Using trial periods on subscriptions to learn more.

  • trial_settingsobject

    Settings related to subscription trials.

    Show 1 child parameter
    • end_behaviorobjectRequired
      Show 1 child parameter
      • missing_payment_methodstringRequired
        Possible values
        • cancel
        • create_invoice
        • pause

Returns

The subscription object.

POST /v1/subscriptions/{subscription_exposed_id}
curl https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Retrieve a subscription

GET/v1/subscriptions/{subscription_exposed_id}

Retrieves the subscription with the given ID.

Path parameters

  • subscription_exposed_idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The subscription object.

GET /v1/subscriptions/{subscription_exposed_id}
curl https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Cancel a subscription

DELETE/v1/subscriptions/{subscription_exposed_id}

Cancels a customer’s subscription immediately. The customer won’t be charged again for the subscription. After it’s canceled, the subscription is largely immutable. You can still update its metadata and cancellation_details. Any pending invoice items that you’ve created are still charged at the end of the period, unless manually deleted. If you’ve set the subscription to cancel at the end of the period, any pending prorations are also left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations are removed if invoice_now and prorate are both set to false. By default, upon subscription cancellation, Stripe stops automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.

Path parameters

  • subscription_exposed_idstringRequired

Body parameters

  • cancellation_detailsobject

    Details about why this subscription was cancelled

    Show 3 child parameters
    • commentstring
    • feedbackstring
      Possible values
      • customer_service
      • low_quality
      • missing_features
      • other
      • switched_service
      • too_complex
      • too_expensive
      • unused
    • feedback_optionstring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_nowboolean

    Will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items. Defaults to false.

  • prorateboolean

    Will generate a proration invoice item that credits remaining unused time until the subscription period end. Defaults to false.

Returns

The subscription object.

DELETE /v1/subscriptions/{subscription_exposed_id}
curl -X DELETE https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Delete a subscription discount

DELETE/v1/subscriptions/{subscription_exposed_id}/discount

Removes the currently applied discount on a subscription.

Path parameters

  • subscription_exposed_idstringRequired

Returns

The deleted_discount object.

DELETE /v1/subscriptions/{subscription_exposed_id}/discount
curl -X DELETE https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123/discount \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "",
  "object": "discount",
  "start": 1234567890,
  "checkout_session": null,
  "customer": null,
  "invoice": null,
  "invoice_item": null,
  "promotion_code": null,
  "subscription": null,
  "subscription_item": null,
  "source": {
    "coupon": null,
    "type": "coupon"
  },
  "customer_account": null
}

Migrate a subscription

POST/v1/subscriptions/{subscription}/migrate

Upgrade the billing_mode of an existing subscription.

Path parameters

  • subscriptionstringRequired

Body parameters

  • billing_modeobjectRequired

    Controls how prorations and invoices for subscriptions are calculated and orchestrated.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • flexible
    • flexibleobject
      Show 1 child parameter
      • proration_discountsstring
        Possible values
        • included
        • itemized
  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The subscription object.

POST /v1/subscriptions/{subscription}/migrate
curl https://api.knoxapi.com/v1/subscriptions/sub_1Pgc6rB7WZ01zgkWNy0Cn5nw/migrate \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "billing_mode[type]=classic"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Resume a subscription

POST/v1/subscriptions/{subscription}/resume

Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. Resume is only available for subscriptions that use charge_automatically collection. If Stripe doesn’t generate a resumption invoice, the subscription becomes active immediately. When a resumption invoice is generated, Stripe finalizes it immediately. If the invoice is paid or marked uncollectible, the subscription becomes active. If the invoice is manually voided, the subscription stays paused. If there is no payment attempt within 23 hours, Stripe voids the invoice and the subscription stays paused. Learn more about resuming subscriptions.

Path parameters

  • subscriptionstringRequired

Body parameters

  • billing_cycle_anchorstring

    The billing cycle anchor that applies when the subscription is resumed. Either now or unchanged. The default is now. For more information, see the billing cycle documentation.

    Possible values
    • now
    • unchanged
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • proration_behaviorstring

    Determines how to handle prorations resulting from the billing_cycle_anchor being unchanged. When the billing_cycle_anchor is set to now (default value), no prorations are generated. If no value is passed, the default is create_prorations.

    Possible values
    • always_invoice
    • create_prorations
    • none
  • proration_dateinteger

    If set, prorations will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same prorations that were previewed with the create preview endpoint.

Returns

The subscription object.

POST /v1/subscriptions/{subscription}/resume
curl -X POST https://api.knoxapi.com/v1/subscriptions/sub_1Pgc6rB7WZ01zgkWNy0Cn5nw/resume \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "application": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "disabled_reason": null
  },
  "billing_cycle_anchor": 1234567890,
  "billing_cycle_anchor_config": {
    "day_of_month": 1361669285,
    "hour": null,
    "minute": null,
    "month": null,
    "second": null
  },
  "cancel_at": 1234567890,
  "canceled_at": 1234567890,
  "cancellation_details": {
    "comment": null,
    "feedback": null,
    "reason": null,
    "feedback_option": null
  },
  "collection_method": "charge_automatically",
  "created": 1234567890,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "days_until_due": null,
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "ended_at": 1234567890,
  "id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
  "invoice_settings": {
    "account_tax_ids": null,
    "issuer": {
      "type": "self"
    },
    "custom_fields": null,
    "description": null,
    "footer": null
  },
  "items": {
    "data": [
      {
        "created": 1721954054,
        "discounts": [],
        "id": "si_QXhVnC2h0Jczwc",
        "metadata": {},
        "object": "subscription_item",
        "price": {
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1721948530,
          "currency": "usd",
          "custom_unit_amount": {
            "maximum": null,
            "minimum": null,
            "preset": null
          },
          "id": "price_1PgafmB7WZ01zgkW6dKueIc5",
          "livemode": false,
          "lookup_key": null,
          "metadata": {},
          "nickname": null,
          "object": "price",
          "product": "prod_QXg1hqf4jFNsqG",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "meter": null,
            "usage_type": "licensed",
            "trial_period_days": null
          },
          "tax_behavior": "unspecified",
          "tiers_mode": null,
          "transform_quantity": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 1,
        "subscription": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
        "tax_rates": [],
        "plan": {
          "active": true,
          "amount": null,
          "amount_decimal": null,
          "billing_scheme": "tiered",
          "created": 1028554472,
          "currency": "currency",
          "id": "obj_123",
          "interval": "month",
          "interval_count": 797691627,
          "livemode": true,
          "metadata": null,
          "meter": null,
          "nickname": null,
          "object": "plan",
          "product": null,
          "tiers_mode": null,
          "transform_usage": {
            "divide_by": 1592560163,
            "round": "down"
          },
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "current_period_end": 976287773,
        "current_period_start": 1896570518,
        "billing_thresholds": {
          "usage_gte": null
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
  },
  "latest_invoice": null,
  "livemode": false,
  "metadata": {},
  "next_pending_invoice_item_invoice": 1234567890,
  "object": "subscription",
  "on_behalf_of": null,
  "pause_collection": {
    "behavior": "mark_uncollectible",
    "resumes_at": null
  },
  "payment_settings": {
    "payment_method_options": {
      "acss_debit": {},
      "bancontact": {
        "preferred_language": "fr"
      },
      "card": {
        "network": null,
        "request_three_d_secure": null
      },
      "customer_balance": {
        "funding_type": null
      },
      "konbini": {},
      "sepa_debit": {},
      "us_bank_account": {},
      "payto": {},
      "pix": {},
      "upi": {},
      "billie": {}
    },
    "payment_method_types": null,
    "save_default_payment_method": null
  },
  "pending_invoice_item_interval": {
    "interval": "month",
    "interval_count": 797691627
  },
  "pending_setup_intent": null,
  "pending_update": {
    "billing_cycle_anchor": null,
    "discount": {
      "checkout_session": null,
      "customer": null,
      "end": null,
      "id": "obj_123",
      "invoice": null,
      "invoice_item": null,
      "object": "discount",
      "promotion_code": null,
      "start": 109757538,
      "subscription": null,
      "subscription_item": null,
      "source": {
        "coupon": null,
        "type": "coupon"
      },
      "customer_account": null
    },
    "discounts": [],
    "expires_at": 833811170,
    "subscription_items": null,
    "trial_end": null,
    "trial_from_plan": null,
    "metadata": null,
    "cancel_at_period_end": null
  },
  "schedule": null,
  "start_date": 1234567890,
  "status": "active",
  "test_clock": null,
  "transfer_data": {
    "amount_percent": null,
    "destination": {
      "id": "obj_123",
      "object": "account"
    }
  },
  "trial_end": 1234567890,
  "trial_settings": {
    "end_behavior": {
      "missing_payment_method": "create_invoice"
    }
  },
  "trial_start": 1234567890,
  "cancel_at_period_end": true,
  "billing_thresholds": {
    "amount_gte": null,
    "reset_billing_cycle_anchor": null
  },
  "billing_mode": {
    "type": "classic",
    "flexible": {}
  },
  "customer_account": null,
  "managed_payments": {
    "enabled": true
  },
  "billing_schedules": [
    {
      "applies_to": null,
      "bill_until": {
        "computed_timestamp": 2082605468,
        "duration": {
          "interval": "month",
          "interval_count": null
        },
        "timestamp": null,
        "type": "duration"
      },
      "key": "key"
    }
  ]
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.