v1

latestOpenAPI 3.1.02026-07-24170121.2 MB

Pause a Subscription

This API pauses an active subscription for a specific duration and unit. The allowed pause unit depends on the subscription plan interval: day plans allow days, week plans allow weeks, month plans allow months, and year plans allow years. When the pause is applied, the subscription status is changed to paused, pause timestamps are stored, and current_period_end is recalculated to the next charge date after the pause.

post/v1/subscriptions/{id}/pause

Path parameters

idstring required

id here refers to a specific subscription that needs to be paused.

Headers

Acceptstring required

Indicates which content types, expressed as MIME types, the client is able to understand.

Content-Typestring required

Indicates the media type of the resource sent in the HTTP message body. Possible Values: application/json application/x-www-form-urlencoded

Request body

durationinteger required

Pause duration value. Minimum is 1. Maximum allowed values are enforced server-side based on the selected unit: 365 for days, 52 for weeks, 12 for months, and 1 for years.

unit'days' | 'weeks' | 'months' | 'years' required

Pause duration unit. Allowed values are days, weeks, months, and years. Business rules may further restrict the allowed value based on the subscription plan interval.

Example request

{
  "duration": 2,
  "unit": "weeks"
}

Response

200

Example response

{
  "data": {
    "object": "Subscription",
    "id": "xlRP0jgPl0ljAXog",
    "customer_id": "jDPAnVxA4xPDVpKM",
    "billing_type": 1,
    "current_period_end": 1727700436,
    "current_period_start": 1726145236,
    "plan_ref": "n2pv6j6p2pvj3Ygq",
    "start_at": 1726490836,
    "status": "paused",
    "tax_percent": 5,
    "created_at": 1726145236,
    "updated_at": 1726490836,
    "description": "testr",
    "payment_type": "card",
    "paused_at": 1726490836,
    "pause_end_at": 1727700436,
    "pause_units_allowed": [
      "weeks"
    ],
    "plan": {
      "data": {
        "object": "Plan",
        "plan_id": "plan_d2b50d00",
        "amount": 99,
        "interval": "week",
        "interval_count": 1,
        "name": "test",
        "statement_descriptor": "dfghdfhg",
        "currency": "usd",
        "created_at": 1724503321,
        "updated_at": 1724505447
      }
    }
  },
  "meta": {
    "include": [
      "plan"
    ]
  }
}