Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Retrieve a subscription item 

Retrieves the subscription item with the given ID.

Parameters

No parameters.

Returns

Returns a subscription item if a valid subscription item ID was provided. Raises an error otherwise.

GET /v1/subscription_items/:id
curl https://api.stripe.com/v1/subscription_items/si_NcLYdDxLHxlFo7 \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:"
Response
{
  "id": "si_NcLYdDxLHxlFo7",
  "object": "subscription_item",
  "created": 1680126546,
  "metadata": {},
  "price": {
    "id": "price_1Mr6rdLkdIwHu7ixwPmiybbR",
    "object": "price",
    "active": true,
    "billing_scheme": "per_unit",
    "created": 1680126545,
    "currency": "usd",
    "custom_unit_amount": null,
    "discounts": null,
    "livemode": false,
    "lookup_key": null,
    "metadata": {},
    "nickname": null,
    "product": "prod_NcLYGKH0eY5b8s",
    "recurring": {
      "interval": "month",
      "interval_count": 1,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "tax_behavior": "unspecified",
    "tiers_mode": null,
    "transform_quantity": null,
    "type": "recurring",
    "unit_amount": 1000,
    "unit_amount_decimal": "1000"
  },
  "quantity": 2,
  "subscription": "sub_1Mr6rbLkdIwHu7ix4Xm9Ahtd",
  "tax_rates": []
}

List all subscription items 

Returns a list of your subscription items for a given subscription.

Parameters

  • subscriptionstringRequired

    The ID of the subscription whose items will be retrieved.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit subscription items, starting after subscription item starting_after. Each entry in the array is a separate subscription item object. If no more subscription items are available, the resulting array will be empty.

GET /v1/subscription_items
curl -G https://api.stripe.com/v1/subscription_items \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:" \
  -d limit=3 \
  -d subscription=sub_1NQH9iLkdIwHu7ixxhHui9yi
Response
{
  "object": "list",
  "url": "/v1/subscription_items",
  "has_more": false,
  "data": [
    {
      "id": "si_OCgWsGlqpbN4EP",
      "object": "subscription_item",
      "created": 1688507587,
      "metadata": {},
      "price": {
        "id": "price_1NQH9iLkdIwHu7ix3tkaSxhj",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1688507586,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_OCgWE6cbwiSu27",
        "recurring": {
          "interval": "month",
          "interval_count": 1,
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "recurring",
        "unit_amount": 1000,
        "unit_amount_decimal": "1000"
      },
      "quantity": 1,
      "subscription": "sub_1NQH9iLkdIwHu7ixxhHui9yi",
      "tax_rates": []
    }
  ]
}

Delete a subscription item 

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Parameters

  • proration_behaviorenum

    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 enum values
    always_invoice

    Always invoice immediately for prorations.

    create_prorations

    Will cause proration invoice items to be created when applicable. These proration items will only be invoiced immediately under certain conditions.

    none

    Disable creating prorations in this request.

More parameters

  • clear_usageboolean

  • proration_datetimestamp

Returns

An subscription item object with a deleted flag upon success. Otherwise, this call raises an error, such as if the subscription item has already been deleted.

DELETE /v1/subscription_items/:id
curl -X DELETE https://api.stripe.com/v1/subscription_items/si_NcLYdDxLHxlFo7 \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:"
Response
{
  "id": "si_NcLYdDxLHxlFo7",
  "object": "subscription_item",
  "deleted": true
}