WIwithflex
Subscriptions

Update Subscription

Changed on

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}

Request

  • Base URL
    https://api.withflex.com
  • URL
    https://api.withflex.com/v1/subscriptions/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required
Example:fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA

Query parameters

expand_customerboolean nullable

If true, expands the customer object in the response.

expandstring

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

Supported keys: customer; latest_invoice (alias invoice); payment_method; backup_payment_method; price (alias product); and discounts. Combine discounts with coupons (expand=discounts,coupons) to hydrate each discount's nested source.coupon into a full object instead of a bare ID.

Unrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. coupon) returns the same response as no expand at all, with no error.

Request body

Example request

{
  "subscription": {
    "cancel_at_period_end": false,
    "trial_end": "2026-06-15T14:30:00Z",
    "items": [
      {
        "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "price": "fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "price_data": {
          "description": "Premium SPF 50 mineral sunscreen",
          "unit_amount": 2500,
          "recurring": {
            "interval": "day",
            "interval_count": 0,
            "trial_period_days": 0
          },
          "metadata": {
            "order_id": "8842",
            "channel": "shopify"
          },
          "product": "fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "product_data": {
            "name": "Example",
            "description": "Premium SPF 50 mineral sunscreen",
            "upc_code": "example_value",
            "gtin": "example_value",
            "reference_gtin": "example_value",
            "url": "https://example.com",
            "client_reference_id": "example_value",
            "metadata": {
              "order_id": "8842",
              "channel": "shopify"
            },
            "image_urls": [
              "https://example.com/image.png"
            ],
            "categories": [
              "string"
            ],
            "components": [
              "string"
            ]
          }
        }
      }
    ],
    "proration_behavior": "always_invoice",
    "cancel_at": "2026-06-15T14:30:00Z",
    "metadata": {
      "order_id": "8842",
      "channel": "shopify"
    },
    "coupon": "string",
    "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
  }
}

Response

An envelope wrapping a single subscription object.

Example response

{
  "subscription": {
    "subscription_id": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "created_at": "2026-06-15T14:30:00Z",
    "items": [
      {
        "subscription_item_id": "fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "price": "fprice_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": {
      "setup_secret": "string",
      "payment_secret": "string"
    },
    "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",
    "backup_payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "discounts": [
      {
        "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "source": {
          "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
          "type": "coupon"
        },
        "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "test_mode": false,
        "end": "string",
        "start": "string"
      }
    ],
    "pause": {
      "paused_at": "2026-06-15T14:30:00Z",
      "resume_at": "2026-06-15T14:30:00Z",
      "billing_cycle_anchor": "unchanged",
      "proration_behavior": "always_invoice",
      "credit": "unused_time"
    }
  }
}

Changes

  • eec642897a22Revision changes
    • breaking

      the ////////// response's property format changed from email to no format for status

    • breaking

      the /////////////// response's property format changed from email to no format for status

    • warning

      added the new adaptiveShoesDependent enum value to the ///////////////// response property for the response status

    • warning

      added the new automatedCleaner enum value to the ///////////////// response property for the response status

    • warning

      added the new babyMonitorSplit enum value to the ///////////////// response property for the response status

    • warning

      added the new babySleepApp enum value to the ///////////////// response property for the response status

    • warning

      added the new bodyPillow enum value to the ///////////////// response property for the response status

    • warning

      added the new breathWorkDependent enum value to the ///////////////// response property for the response status

    • warning

      added the new coolingSleepwear enum value to the ///////////////// response property for the response status

    • warning

      added the new meneralsNootropicPouch enum value to the ///////////////// response property for the response status

    • warning

      added the new nonenalOdor enum value to the ///////////////// response property for the response status

    • warning

      added the new nursingChairs enum value to the ///////////////// response property for the response status

    • warning

      added the new speechHealthDependent enum value to the ///////////////// response property for the response status

    • warning

      added the new uvClothing enum value to the ///////////////// response property for the response status

    • warning

      added the new uvGlasses enum value to the ///////////////// response property for the response status

    • info

      added the new optional request property /

    • info

      added the optional property / to the response with the status

    • info

      added the optional property //////// to the response with the status

    • info

      added the optional property / to the response with the status