# Create a subscription item

Adds a new item to an existing subscription. No existing items will be changed or replaced.

## Prerequisites

Before you can run the following code snippet, you need to call these APIs with the provided parameters to set up the prerequisite API object(s).

1. Create a payment method
POST /v1/payment_methods {"type":"card","card":{"token":"tok_visa"}}
2. Create a customer and attach the payment method
POST /v1/customers {"name":"Jenny Rosen","email":"jennyrosen@example.com","payment_method":"${node.prerequisites.createPaymentMethod.createPaymentMethod:id}","invoice_settings":{"default_payment_method":"${node.prerequisites.createPaymentMethod.createPaymentMethod:id}"}}
3. Create a product
POST /v1/products {"name":"Gold Plan"}
4. Create a price
POST /v1/prices {"product":"${node.prerequisites.createProduct.createProduct:id}","unit_amount":2000,"currency":"usd","recurring":{"interval":"month"}}
5. Create a subscription
POST /v1/subscriptions {"customer":"${node.prerequisites.createCustomer.createCustomer:id}","items":[{"price":"${node.prerequisites.createPrice.createPrice:id}"}]}

## Request

```curl
curl https://api.stripe.com/v1/subscription_items \
  -u "<<YOUR_SECRET_KEY>>" \
  -d subscription={{SUBSCRIPTION_ID}} \
  -d price={{PRICE_ID}} \
  -d quantity=2
```

### Response

```json
{
  "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": []
}
```

## Returns

Returns the created `Subscription Item` object, if successful. Otherwise, this call raises [an error](https://docs.stripe.com/api/errors.md).

## Parameters

- `subscription` (string, required)
  The identifier of the subscription to modify.

- `billing_thresholds` (object, optional)
  Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.

  - `billing_thresholds.usage_gte` (integer, required)
    Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 [monetary threshold](https://docs.stripe.com/docs/api/subscriptions/update.md#update_subscription-billing_thresholds-amount_gte))

- `discounts` (array of objects, optional)
  The coupons to redeem into discounts for the subscription item.

  - `discounts.coupon` (string, optional)
    ID of the coupon to create a new discount for.

  - `discounts.discount` (string, optional)
    ID of an existing discount on the object (or one of its ancestors) to reuse.

  - `discounts.promotion_code` (string, optional)
    ID of the promotion code to create a new discount for.

- `metadata` (map, optional)
  Set of [key-value pairs](https://docs.stripe.com/docs/api/metadata.md) 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`.

- `payment_behavior` (enum, optional)
  Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
Possible enum values:
  - `allow_incomplete`
    This is the default behavior since [2019-03-14](changelog/2019-03-14/subscriptions-successfully-created-first-payment-fails). Transition the subscription to `status=past_due` if payment fails. If you have payment retries configured, Stripe automatically retries the payment. If the payment requires action, you receive an `invoice.payment_action_required` webhook and must manage additional user actions. For example, SCA regulations might require 3DS authentication to complete payment. See the [SCA Migration Guide](https://docs.stripe.com/docs/billing/migration/strong-customer-authentication.md) for Billing to learn more.

  - `default_incomplete`
    When payment is required, transition the subscription to `status=past_due` without attempting payment. You must request explicit confirmation of the Invoice’s PaymentIntent. The resulting Invoice has [auto_advance=false](https://docs.stripe.com/docs/api/invoices/object.md#invoice_object-auto_advance), so Stripe doesn’t automatically attempt payment, retry payment, or finalize the subscription.

  - `error_if_incomplete`
    If payment fails, return an HTTP `402` status code and don’t update the subscription. This behavior doesn’t support payments that require user action, such as 3DS authentication, because it returns an error instead of creating a PaymentIntent with `status=requires_action`. This behavior was the default for API versions before [2019-03-14](changelog/2019-03-14/subscriptions-successfully-created-first-payment-fails).

  - `pending_if_incomplete`
    If payment fails, Stripe creates a [pending update](https://docs.stripe.com/docs/billing/subscriptions/pending-updates.md), which applies only if the payment eventually succeeds. This behavior doesn’t support all [attributes and payment methods](https://docs.stripe.com/docs/billing/pending-updates-reference.md#supported-attributes). This option is the simplest way to ensure the customer completes payment before Stripe applies the update.

- `price` (string, optional)
  The ID of the price object.

- `price_data` (object, optional)
  Data used to generate a new [Price](https://docs.stripe.com/docs/api/prices.md) object inline.

  - `price_data.currency` (enum, required)
    Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://docs.stripe.com/currencies.md).

  - `price_data.product` (string, required)
    The ID of the [Product](https://docs.stripe.com/api/products.md) that this [Price](https://docs.stripe.com/api/prices.md) will belong to.

  - `price_data.recurring` (object, required)
    The recurring components of a price such as `interval` and `interval_count`.

    - `price_data.recurring.interval` (enum, required)
      Specifies billing frequency. Either `day`, `week`, `month` or `year`.
Possible enum values:
      - `day`
      - `month`
      - `week`
      - `year`

    - `price_data.recurring.interval_count` (integer, optional)
      The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).

  - `price_data.tax_behavior` (enum, recommended if calculating taxes)
    Only required if a [default tax behavior](https://docs.stripe.com/docs/tax/products-prices-tax-categories-tax-behavior.md#setting-a-default-tax-behavior-\(recommended\)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed.
Possible enum values:
    - `exclusive`
    - `inclusive`
    - `unspecified`

  - `price_data.unit_amount` (integer, optional)
    A positive integer in the smallest currency unit (or 0 for a free price) representing how much to charge.

  - `price_data.unit_amount_decimal` (string, required conditionally)
    Same as `unit_amount`, but accepts a decimal value in the smallest currency unit with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set.

- `proration_behavior` (enum, optional)
  Determines how to handle [prorations](https://docs.stripe.com/docs/billing/subscriptions/prorations.md) 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](https://docs.stripe.com/docs/subscriptions/upgrading-downgrading.md#immediate-payment).

  - `none`
    Disable creating prorations in this request.

- `proration_date` (timestamp, optional)
  If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the [upcoming invoice](https://docs.stripe.com/api/invoices/create_preview.md) endpoint.

- `quantity` (integer, optional)
  The quantity you’d like to apply to the subscription item you’re creating.

- `tax_rates` (array of strings, optional)
  A list of [Tax Rate](https://docs.stripe.com/docs/api/tax_rates.md) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/docs/api/subscriptions/create.md#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.