WIwithflex
Subscriptions

Pause Subscription

Changed on

Pauses an active subscription.

Nothing is invoiced while the subscription is paused, and its current_period_end shows the pause date. With credit: "unused_time" (the default) the paid time left in the period is credited to the resume charge. With "none" the paused days inside the paid period are not credited, and a resume before the period ends keeps the paid days after it. The first pause moves the subscription to Stripe's flexible billing mode, which is permanent. The response carries the pause object immediately; the customer.subscription.updated event follows. A subscription that is already paused, not active, scheduled to cancel, or still collecting its latest invoice is refused with a typed error.

With resume_at, Flex resumes the subscription on that date, billed as billing_cycle_anchor and proration_behavior say, with the same options as an immediate resume. Either billing field without resume_at is refused with resume_at_required (422), and proration_behavior without billing_cycle_anchor: "unchanged" with proration_behavior_requires_unchanged_anchor (422).

post/v1/subscriptions/{id}/pause

Request

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

Path parameters

idstring required
Example:fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA

Request body

resume_atstring

A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. 2026-06-15T14:30:00Z).

billing_cycle_anchor'now' | 'unchanged'

Where billing restarts when a paused subscription resumes.

  • now: Bill monthly from the resume date, charging the full period now, net of any unused time credited at the pause. After an uncredited pause that ends inside the paid period, nothing is charged now and the next charge covers the time from the old period end.
  • unchanged: Keep the original billing date.
proration_behavior'create_prorations' | 'always_invoice'

How the partial period is billed when a subscription resumes on its original billing date.

  • create_prorations: Bill the partial period on the original billing date, with the next full period.
  • always_invoice: Bill the partial period now, net of any unused time credited at the pause. A negative amount charges nothing and goes to the customer's balance.
credit'unused_time' | 'none'

What a pause credits for the paid time left in the period.

  • unused_time: Credit the unused paid time from the pause to the period end. The resume charge is net of it.
  • none: Credit nothing for the paused days inside the paid period. A resume before the period ends keeps the paid days after it.

Example request

{
  "resume_at": "2026-06-15T14:30:00Z",
  "billing_cycle_anchor": "unchanged",
  "proration_behavior": "always_invoice",
  "credit": "unused_time"
}

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