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

# Update Subscription

> Update an existing subscription

<Note>
  This endpoint updates subscription details including items, quantities, and payment methods. Plan changes take effect at the next billing cycle.
</Note>

## Authentication

This endpoint requires a valid API key with `subscriptions:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subscription
</ParamField>

## Request Body

<ParamField body="plan_id" type="string">
  Change to a different plan (takes effect next billing cycle)
</ParamField>

<ParamField body="quantity" type="integer">
  Update subscription quantity
</ParamField>

<ParamField body="items" type="array">
  Update subscription items

  <Expandable title="Item properties">
    <ParamField body="id" type="string">
      Item ID to update (omit for new items)
    </ParamField>

    <ParamField body="product_id" type="string">
      Product ID
    </ParamField>

    <ParamField body="quantity" type="integer">
      Item quantity
    </ParamField>

    <ParamField body="deleted" type="boolean">
      Set to true to remove item
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment_method_id" type="string">
  Update default payment method
</ParamField>

<ParamField body="coupon_id" type="string">
  Apply a coupon
</ParamField>

<ParamField body="trial_end" type="string">
  Extend or end trial period
</ParamField>

<ParamField body="metadata" type="object">
  Update custom fields
</ParamField>

### Response

Returns the updated subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request PUT 'https://api.stateset.com/v1/subscriptions/sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "items": [
          {
              "id": "si_123456",
              "quantity": 3
          },
          {
              "product_id": "prod_premium_support",
              "quantity": 1
          }
      ],
      "coupon_id": "SAVE20"
  }'
  ```

  ```javascript Node.js theme={null}
  const subscription = await stateset.subscriptions.update(
    'sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    {
      items: [
        {
          id: "si_123456",
          quantity: 3
        },
        {
          product_id: "prod_premium_support",
          quantity: 1
        }
      ],
      coupon_id: "SAVE20"
    }
  );
  ```

  ```python Python theme={null}
  subscription = stateset.subscriptions.update(
    'sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    items=[
      {
        "id": "si_123456",
        "quantity": 3
      },
      {
        "product_id": "prod_premium_support",
        "quantity": 1
      }
    ],
    coupon_id="SAVE20"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "subscription",
    "updated_at": "2024-01-20T14:00:00Z",
    "status": "active",
    "items": [
      {
        "id": "si_123456",
        "product_id": "prod_addon_storage",
        "product_name": "Additional Storage (10GB)",
        "quantity": 3,
        "unit_price": 500,
        "amount": 1500
      },
      {
        "id": "si_789012",
        "product_id": "prod_premium_support",
        "product_name": "Premium Support",
        "quantity": 1,
        "unit_price": 2900,
        "amount": 2900
      }
    ],
    "discount": {
      "coupon": {
        "id": "SAVE20",
        "percent_off": 20,
        "duration": "repeating",
        "duration_in_months": 3
      }
    },
    "subtotal": 14300,
    "discount_amount": 2860,
    "tax_amount": 915,
    "total_amount": 12355
  }
  ```
</ResponseExample>