Sign in

v1

latestOpenAPI 3.1.02026-07-2684271522.2 KB
Subscriptions

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.

patch/v1/subscriptions/{id}

Path parameters

idstring required
Example:fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA

Query parameters

expand_customerboolean nullable

If true, expands the customer object in the response.

If true, expands the customer object in the response.

expandstring

Comma-separated list of related objects to expand in the response.

Comma-separated list of related objects to expand in the response.

Request body

Example request

{
  "subscription": {
    "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

An envelope wrapping a single subscription object.

Example response

{
  "subscription": {
    "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "created_at": "2026-06-15T14:30:00Z",
    "items": [
      {}
    ],
    "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"
  }
}