Update Subscription
Updates an existing subscription. Any omitted field is left unchanged, and an empty request body is a no-op that simply returns the current subscription.
The change is first applied in Stripe and then mirrored to Flex, so the response
reflects the resulting status and billing period. Updating items switches each item to
the supplied recurring price (or to a newly created price when price_data is given, in
which case a new Price is created in Stripe and Flex); item prices must be recurring.
proration_behavior controls how mid-cycle changes are prorated (create_prorations by
default). Supplied metadata is merged into any existing metadata. Passing an empty
string for coupon removes the current coupon.
Authorizations
Use a Bearer token to access this API.
Path Parameters
"fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
Query Parameters
If true, expands the customer object in the response.
false
Comma-separated list of related objects to expand in the response.
Body
An envelope wrapping a single subscription object.
An envelope wrapping a single subscription object.
The subscription payload carried by the request or response.
{
"cancel_at_period_end": false,
"trial_end": "2026-06-15T14:30:00Z",
"proration_behavior": "always_invoice",
"cancel_at": "2026-06-15T14:30:00Z",
"metadata": { "order_id": "8842", "channel": "shopify" }
}Response
Success
An envelope wrapping a single subscription object.
The subscription payload carried by the request or response.
{
"subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"created_at": "2026-06-15T14:30:00Z",
"items": [
{
"subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"quantity": 2500,
"created_at": "2026-06-15T14:30:00Z",
"updated_at": "2026-06-15T14:30:00Z",
"test_mode": false
}
],
"latest_invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"status": "incomplete",
"cancel_at_period_end": false,
"current_period_end": "string",
"current_period_start": "string",
"metadata": { "order_id": "8842", "channel": "shopify" },
"test_mode": false,
"client_secret": {},
"proration_behavior": "always_invoice",
"trial_start": "string",
"trial_end": "string",
"cancel_at": "2026-06-15T14:30:00Z",
"canceled_at": "2026-06-15T14:30:00Z",
"default_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
}