Update Subscription

Update an existing subscription

PUT /v1/subscriptions/:id

cURL

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"
}'

Response

{
  "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
}

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

Authentication

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

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

The unique identifier of the subscription

Request Body

plan_id · string

Change to a different plan (takes effect next billing cycle)

quantity · integer

Update subscription quantity

items · array

Update subscription items

Show Item properties

id · string

Item ID to update (omit for new items)

product_id · string

Product ID

quantity · integer

Item quantity

deleted · boolean

Set to true to remove item

payment_method_id · string

Update default payment method

coupon_id · string

Apply a coupon

trial_end · string

Extend or end trial period

metadata · object

Update custom fields

Response

Returns the updated subscription object.

cURL

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"
}'

Response

{
  "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
}