WIwithflex
Subscriptions

Update Pause

Changed on

Changes when a paused subscription resumes on its own, and how that resume bills.

The body replaces the scheduled resume. Send resume_at with the billing fields to set or move it; billing fields you omit take their defaults rather than keeping earlier values. Send resume_at: null to clear it, so the subscription stays paused until you resume it. Flex resumes on the new date, and an earlier date no longer applies. Stripe isn't called. An Idempotency-Key header is not honored here, as on every non-POST endpoint; sending the same body again is safe.

Refusals carry a typed code: subscription_pause_not_enabled (422) when the account isn't in the rollout, not_paused (422) when the subscription isn't paused, pause_in_progress (409) while a pause request holds it, resume_in_progress (409) while a resume holds it or its invoice is open, resume_at_in_past (422) for a date that has passed, resume_at_required (422) for a billing field with a null resume_at, and proration_behavior_requires_unchanged_anchor (422) when proration_behavior comes without billing_cycle_anchor: "unchanged".

patch/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 required

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.

Example request

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

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