> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.

# subscriptions_update

> Update a subscription. Parameters not provided are left unchanged. To change an item send its `id`; omitting the `id` adds a new item instead.

<div className="tool-route"><span className="tool-row-method" data-method="POST">POST</span><code>{"https://api.stripe.com/v1/subscriptions/{subscription}"}</code></div>

```python stripe_subscriptions_update.py theme={null}
from charter.packs import stripe

result = await stripe.subscriptions_update.ainvoke({"subscription": ...})
```

## Path parameters

<div className="reference-table">
  | Field                                                                | Type     | Description                           |
  | -------------------------------------------------------------------- | -------- | ------------------------------------- |
  | `subscription` <span className="required" title="required">\*</span> | `string` | The ID of the subscription to update. |
</div>

## Body

<div className="reference-table">
  | Field                  | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                   |
  | ---------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `description`          | `string`                                                                                                  | An arbitrary string attached to the subscription. <span className="field-constraints">max length 500</span>                                                                                                                                                                                                                                                                                   |
  | `metadata`             | map of `string`                                                                                           | Set of key-value pairs attached to the subscription.                                                                                                                                                                                                                                                                                                                                          |
  | `trialEnd`             | `string` \| `integer`                                                                                     | When the trial ends: the string 'now' to end it immediately, or a Unix timestamp at most two years out. Overrides any trial the plan defines. A timestamp is seconds, not milliseconds: 1700000000, not 1700000000000.                                                                                                                                                                        |
  | `cancelAt`             | `integer` \| [CancelAtSentinel](/charter/charter/packs/stripe/subscriptions/objects#cancelatsentinel) \| `string` | When to cancel: a Unix timestamp, or one of 'max\_billed\_until', 'max\_period\_end', 'min\_period\_end'. A timestamp before the current period ends prorates if prorations are enabled. Pass an empty string to clear a cancellation that was scheduled earlier; `cancel_at_period_end` does not clear a timestamp. A timestamp is seconds, not milliseconds: 1700000000, not 1700000000000. |
  | `collectionMethod`     | [CollectionMethod](/charter/charter/packs/stripe/subscriptions/objects#collectionmethod)                          | How to collect payment. Absent, Stripe charges automatically.                                                                                                                                                                                                                                                                                                                                 |
  | `daysUntilDue`         | `integer`                                                                                                 | Days until an invoice is due. Valid only when collection\_method is 'send\_invoice'. <span className="field-constraints">≥ 0</span>                                                                                                                                                                                                                                                           |
  | `defaultPaymentMethod` | `string`                                                                                                  | The payment method to charge. It must already belong to this subscription's customer.                                                                                                                                                                                                                                                                                                         |
  | `items`                | [SubscriptionItemUpdate](/charter/charter/packs/stripe/subscriptions/objects#subscriptionitemupdate)\[]           | The items to change, up to 20. Absent, the items are left alone. <span className="field-constraints">max 20 items</span>                                                                                                                                                                                                                                                                      |
  | `cancelAtPeriodEnd`    | `boolean`                                                                                                 | Whether the subscription cancels at the end of the current period. Send it only to change the setting.                                                                                                                                                                                                                                                                                        |
  | `prorationBehavior`    | [ProrationBehaviorOnUpdate](/charter/charter/packs/stripe/subscriptions/objects#prorationbehavioronupdate)        | How to handle prorations when the billing cycle or an item quantity changes. Absent, Stripe creates them.                                                                                                                                                                                                                                                                                     |
  | `paymentBehavior`      | [PaymentBehaviorOnUpdate](/charter/charter/packs/stripe/subscriptions/objects#paymentbehavioronupdate)            | What to do if payment for the update fails. Absent, Stripe allows the subscription to go past\_due.                                                                                                                                                                                                                                                                                           |
  | `prorationDate`        | `integer`                                                                                                 | A Unix timestamp to calculate prorations against, as though the update happened then. Absent, Stripe uses now. A timestamp is seconds, not milliseconds: 1700000000, not 1700000000000.                                                                                                                                                                                                       |
  | `cancellationDetails`  | [CancellationDetails](/charter/charter/packs/stripe/subscriptions/objects#cancellationdetails)                    | Why the subscription is being cancelled.                                                                                                                                                                                                                                                                                                                                                      |
  | `discounts`            | [SubscriptionDiscount](/charter/charter/packs/stripe/subscriptions/objects#subscriptiondiscount)\[]               | Coupons and promotion codes. A populated array replaces the subscription's existing discounts. Absent, they are left alone.                                                                                                                                                                                                                                                                   |
</div>